transport

Documentation

Overview

Package transport abstracts the QUIC carrier under ORP. ORP frames are carried on QUIC streams; control on stream 0, data on streams N>0. Callers (Agent and Relay) consume Conn/Stream and never see quic-go directly — this isolates transport choice from protocol semantics.

Index

• Constants
• type Conn
  • func DialQUIC(ctx context.Context, addr string, tlsConf *tls.Config, qcfg *quic.Config) (Conn, error)
• type Listener
  • func ListenQUIC(addr string, tlsConf *tls.Config, qcfg *quic.Config) (Listener, error)
• type Stream

Constants

const ALPN = "orp/1"

ALPN is the application-layer protocol identifier negotiated at the TLS handshake. Both sides advertise it so a misconfigured peer (e.g., an HTTP/3 client hitting a relay port) is rejected during the handshake instead of leaking into ORP framing.

const DefaultKeepAlivePeriod = 3 * time.Second

DefaultKeepAlivePeriod is the interval at which the dialing side sends QUIC PING frames so MaxIdleTimeout doesn't fire on a healthy link. ~MaxIdleTimeout/3 leaves room for one missed PING before the idle timer fires.

const DefaultMaxIdleTimeout = 10 * time.Second

DefaultMaxIdleTimeout bounds how long a QUIC connection may sit without observed traffic before either side tears it down. The 10 s value is short enough for an agent to notice a dead relay within the relay's resume window, long enough that brief packet drops do not tear down a healthy link.

Types

type Conn

type Conn interface {
	// OpenStream creates a new stream initiated by this peer.
	OpenStream(ctx context.Context) (Stream, error)

	// AcceptStream blocks until the remote peer initiates a stream.
	AcceptStream(ctx context.Context) (Stream, error)

	LocalAddr() net.Addr
	RemoteAddr() net.Addr

	// TLS returns the negotiated TLS state. The relay extracts the
	// peer's URI SAN from PeerCertificates here. Callers that don't
	// need it can ignore.
	TLS() tlsConnectionState

	// Close terminates the connection and all in-flight streams. The
	// remote sees the connection close cleanly.
	Close() error
}

Conn is a multiplexed bidirectional carrier between two peers. The underlying transport is QUIC today; the interface stays narrow so the implementation can be swapped (e.g., for in-process tests).

func DialQUIC

func DialQUIC(ctx context.Context, addr string, tlsConf *tls.Config, qcfg *quic.Config) (Conn, error)

DialQUIC opens a QUIC connection to addr. The caller-supplied tlsConf must contain at least one client certificate when mTLS is required; ALPN is set automatically if not present. Idle / keepalive defaults are applied per withDefaults when qcfg leaves them zero.

type Listener

type Listener interface {
	Accept(ctx context.Context) (Conn, error)
	Addr() net.Addr
	Close() error
}

Listener accepts incoming Conns.

func ListenQUIC

func ListenQUIC(addr string, tlsConf *tls.Config, qcfg *quic.Config) (Listener, error)

ListenQUIC opens a UDP-based QUIC listener at addr. Use ":0" for an ephemeral port; recover the actual address via Listener.Addr.

type Stream

type Stream interface {
	io.ReadWriteCloser

	// StreamID is the QUIC stream id; stable for the lifetime of the
	// stream. ORP reserves id 0 for control.
	StreamID() uint64
}

Stream is a single bidirectional byte stream. ORP layers framing on top via lib/orp.