Transport Interface Definition in OpenFlux: A Complete Guide to the Abstraction Layer

The transport interface definition in OpenFlux is a generic Go interface declared in transport/transport.go that specifies six core methods—Start(), Stop(), Send(), Receive(), IsConnected(), and Stats()—enabling pluggable network transport implementations for the tunnel.

The OpenFlux tunneling framework relies on a clean abstraction layer to handle diverse network transports without coupling to specific protocols. At the heart of this architecture lies the Transport interface definition, which standardizes how components initialize connections, exchange data, and report metrics. Understanding this interface is essential for anyone extending OpenFlux with custom transport implementations.

Transport Interface Specification in OpenFlux

The transport interface definition in OpenFlux lives in transport/transport.go and acts as the contract between the tunnel core and any underlying network mechanism. This generic interface ensures that whether you are using TCP, UDP, WebSocket, or proprietary protocols, the tunnel logic remains unchanged.

Core Method Signatures

According to the source code, the interface declares six mandatory methods:

type Transport interface {
    Start() error
    Stop() error
    Send(data []byte) error
    Receive(callback func([]byte))
    IsConnected() bool
    Stats() TransportStats
}

Each method serves a distinct purpose in the transport lifecycle:

• Start() – Initializes the transport and begins background processing required for connectivity.
• Stop() – Gracefully terminates the transport, ensuring all resources are released and connections closed.
• Send(data []byte) – Transmits raw packet data through the underlying network connection.
• Receive(callback) – Registers a callback function that the transport invokes whenever inbound data arrives.
• IsConnected() – Returns a boolean indicating whether the transport currently maintains an active connection.
• Stats() – Retrieves runtime telemetry including bytes transferred, packet counts, and connection uptime.

TransportStats and Runtime Observability

Supporting the interface is the TransportStats struct, which aggregates operational metrics. When Stats() is called, implementations return this structure containing data such as bytes sent/received, reconnection attempts, and total uptime. This standardization allows the OpenFlux control plane to monitor transport health regardless of the underlying implementation.

Implementing a Custom Transport

To satisfy the transport interface definition in OpenFlux, a concrete type must implement all six methods. The repository provides a BaseTransport helper in transport/transport.go that handles common functionality like callback management and statistics tracking.

Here is a complete example of a custom DummyTransport that implements the interface using the base transport:

type DummyTransport struct {
    base transport.BaseTransport
}

// Compile-time interface verification
var _ transport.Transport = (*DummyTransport)(nil)

func NewDummyTransport(cfg transport.TransportConfig) *DummyTransport {
    return &DummyTransport{
        base: *transport.NewBaseTransport(cfg),
    }
}

func (d *DummyTransport) Start() error {
    return d.base.Start()
}

func (d *DummyTransport) Stop() error {
    return d.base.Stop()
}

func (d *DummyTransport) Send(data []byte) error {
    d.base.RecordSend(len(data))
    d.base.CallReceive(data) // Simulate echo for testing
    return nil
}

func (d *DummyTransport) Receive(cb func([]byte)) {
    d.base.Receive(cb)
}

func (d *DummyTransport) IsConnected() bool {
    return d.base.IsConnected()
}

func (d *DummyTransport) Stats() transport.TransportStats {
    return d.base.Stats()
}

Using Built-in Transport Implementations

OpenFlux ships with several concrete implementations that satisfy the transport interface. The YandexTransport in transport/yandex/yandex.go demonstrates how production transports wrap protocol-specific logic while adhering to the common contract.

cfg := transport.DefaultConfig()
yandexTr, err := transport.NewYandexTransport(cfg)
if err != nil {
    log.Fatal(err)
}
defer yandexTr.Stop()

// Register inbound data handler
yandexTr.Receive(func(pkt []byte) {
    fmt.Printf("Received %d bytes\n", len(pkt))
})

// Initialize transport
if err := yandexTr.Start(); err != nil {
    log.Fatal(err)
}

// Transmit data
payload := []byte("hello")
if err := yandexTr.Send(payload); err != nil {
    log.Printf("send error: %v", err)
}

// Query metrics
stats := yandexTr.Stats()
fmt.Printf("Uptime: %s, Sent: %d bytes\n", stats.Uptime, stats.BytesSent)

Key Source Files for Transport Implementation

Understanding the transport interface definition in OpenFlux requires familiarity with these specific files:

• transport/transport.go – Defines the Transport interface, TransportConfig, BaseTransport helper, and TransportStats struct.
• transport/oneme/max_transport.go – Reference implementation showing how to build custom transports on top of BaseTransport.
• transport/yandex/yandex.go – Production-grade implementation demonstrating protocol-specific wrapper logic.
• transport/encrypted.go – Wrapper transport that adds encryption while maintaining the same interface compliance.
• transport/compressor.go – Middleware transport implementing compression without breaking the interface contract.

Summary

• The transport interface definition in OpenFlux is located in transport/transport.go and specifies six core lifecycle methods.
• Start(), Stop(), Send(), Receive(), IsConnected(), and Stats() form the complete contract that all transport implementations must satisfy.
• The TransportStats struct provides standardized runtime metrics regardless of underlying protocol.
• Developers can create custom transports by implementing the interface directly or leveraging the BaseTransport helper for common functionality.
• Built-in implementations like YandexTransport, EncryptedTransport, and Compressor demonstrate how the interface enables composable, layered network architectures.

Frequently Asked Questions

What file contains the transport interface definition in OpenFlux?

The transport interface definition in OpenFlux is declared in transport/transport.go. This file also contains the TransportConfig structure, the BaseTransport helper type, and the TransportStats struct used for metrics collection.

Which methods are required to implement the OpenFlux Transport interface?

Any concrete implementation must provide six methods: Start() error for initialization, Stop() error for shutdown, Send(data []byte) error for outbound data, Receive(callback func([]byte)) for inbound data handling, IsConnected() bool for status checks, and Stats() TransportStats for telemetry retrieval.

Does OpenFlux provide helper types for implementing custom transports?

Yes, the BaseTransport struct defined in transport/transport.go provides reusable logic for callback management, connection state tracking, and statistics collection. Implementers can embed or wrap this base type to reduce boilerplate when creating custom transports like those shown in transport/oneme/max_transport.go.

Can transport implementations be chained or wrapped in OpenFlux?

Absolutely. The repository includes transport/encrypted.go and transport/compressor.go, which demonstrate the decorator pattern. Both files define transports that wrap other Transport implementations, adding encryption or compression while maintaining strict adherence to the interface contract, enabling composable network pipelines.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}