Crate supertunnel 

SuperTunnel

A modular, asynchronous networking framework designed for building stateful TCP tunnels that make network disruptions transparent to application streams. Super Tunnel enables you to route application connections through a proxy server while adding resiliency features that enable your tunnels to survive network disconnections. Specifically, you can build resilient tunnels by stacking Super Tunnel’s framing, reliability, session resumption, and stream multiplexing layers with your own security protocol implementation.

SuperTunnel is designed to be composed with a security protocol that provides security features such as encryption and resistance to network traffic analysis. SuperTunnel itself does NOT provide security; it provides stateful session resumption and stream multiplexing features while allowing you to focus on developing strong security protocols.

For Protocol Integrators

If your goal is to integrate SuperTunnel into your existing applications without writing custom protocol logic, you can leverage the pre-built layers provided in the proto module.

The standard SuperTunnel stack generally consists of:

• Payload (proto::payload): Chunks raw application data into discrete messages.
• Routing (proto::routing): Multiplexes multiple distinct logical sessions over a single tunnel.
• Reliability (proto::reliability): Guarantees ordered delivery and handles retransmissions.
• Resumption (proto::resumption): Manages session identifiers and facilitates seamless reconnection.
• Framing (proto::framing): Encapsulates messages into a continuous byte stream for transport.

Getting Started: The best way to understand how to wire these layers together is to review the internal source code of the reference implementation examples:

• See examples/client.rs for establishing a multiplexed outbound tunnel.
• See examples/server.rs for accepting, demultiplexing, and routing inbound tunnel connections.

For Protocol Implementors

SuperTunnel is designed to be extensible. You can write your own protocol layers by implementing the Protocol trait and injecting them anywhere in a SuperTunnel stack.

The Protocol Trait

The Protocol trait represents a single transformation layer. It typically takes an underlying asynchronous stream and sink (representing the layer above it) and returns a new upgraded stream and sink (representing this layer’s interface to the layer below).

Building Custom Protocols

When writing a new Protocol implementation, you will often need to manage concurrent state, encode/decode messages, or handle multiple inner streams. The library provides utilities to make this easier:

• The util Module: Contains abstractions for I/O transformation.

  • Use EncodedStream and DecodedSink to bridge between raw bytes and your typed Rust structs using a Codec.
  • Use MuxedEncodedStream and DemuxedDecodedSink if your protocol needs to funnel multiple logical data flows into a single transport layer.

• The sync Module: Contains synchronization primitives for asynchronous state machines where standard locks are unsuitable.

  • Use PollMutex to safely share state between the split read and write halves of your protocol. It provides a poll-based lock that integrates cleanly with Stream and Sink implementations.
  • Use SharedStream or SharedSink when multiple asynchronous tasks need safe, concurrent access to a single underlying I/O resource.

Getting Started: To see these utilities applied in concrete implementations, you can study the internal source code of the reference implementation protocols provided in this library:

• State Sharing: See proto::reliability. Its SharedReliabilityState demonstrates how to use PollMutex to safely share sequence numbers and acknowledgment tracking between the concurrent read and write halves of the reliability layer.
• Multiplexing: See proto::routing. Both the client and server routing implementations heavily rely on MuxedEncodedStream and DemuxedDecodedSink to multiplex numerous dynamic client sessions into a single underlying transport stream.
• Codec Bridging: See proto::framing. It contains a straightforward example of using EncodedStream and DecodedSink to apply a Codec directly to raw byte streams.

Modules

io

Asynchronous I/O utilities.

net

Network addressing.

proto

Core crate::Protocol trait implementations and definitions.

sync

Synchronization and shared state primitives.

util

Tools and adapters for managing streams and sinks and for stacking multiple crate::Protocol layers.

Traits

FrameSize

Trait defining the size constraints for the framing protocol.

Identify

Trait for objects that possess a unique identifier.

Protocol

The core trait defining a discrete layer in the protocol stack.

SessionConnector

Trait for establishing outbound network connections.