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

> Understand the transport interface definition in OpenFlux. This guide explores the abstraction layer and its six core methods for pluggable network transports.

- Repository: [p1neappleXpress/OpenFlux](https://github.com/p1neappleXpress/OpenFlux)
- Tags: deep-dive
- Published: 2026-09-13

---

**The transport interface definition in OpenFlux is a generic Go interface declared in [`transport/transport.go`](https://github.com/p1neappleXpress/OpenFlux/blob/main/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`](https://github.com/p1neappleXpress/OpenFlux/blob/main/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:

```go
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`](https://github.com/p1neappleXpress/OpenFlux/blob/main/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:

```go
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`](https://github.com/p1neappleXpress/OpenFlux/blob/main/transport/yandex/yandex.go) demonstrates how production transports wrap protocol-specific logic while adhering to the common contract.

```go
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`](https://github.com/p1neappleXpress/OpenFlux/blob/main/transport/transport.go)** – Defines the `Transport` interface, `TransportConfig`, `BaseTransport` helper, and `TransportStats` struct.
- **[`transport/oneme/max_transport.go`](https://github.com/p1neappleXpress/OpenFlux/blob/main/transport/oneme/max_transport.go)** – Reference implementation showing how to build custom transports on top of `BaseTransport`.
- **[`transport/yandex/yandex.go`](https://github.com/p1neappleXpress/OpenFlux/blob/main/transport/yandex/yandex.go)** – Production-grade implementation demonstrating protocol-specific wrapper logic.
- **[`transport/encrypted.go`](https://github.com/p1neappleXpress/OpenFlux/blob/main/transport/encrypted.go)** – Wrapper transport that adds encryption while maintaining the same interface compliance.
- **[`transport/compressor.go`](https://github.com/p1neappleXpress/OpenFlux/blob/main/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`](https://github.com/p1neappleXpress/OpenFlux/blob/main/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`](https://github.com/p1neappleXpress/OpenFlux/blob/main/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`](https://github.com/p1neappleXpress/OpenFlux/blob/main/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`](https://github.com/p1neappleXpress/OpenFlux/blob/main/transport/oneme/max_transport.go).

### Can transport implementations be chained or wrapped in OpenFlux?

Absolutely. The repository includes [`transport/encrypted.go`](https://github.com/p1neappleXpress/OpenFlux/blob/main/transport/encrypted.go) and [`transport/compressor.go`](https://github.com/p1neappleXpress/OpenFlux/blob/main/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.