gvisor

Documentation

Overview

Package gvisor provides a user-space TCP carrier backed by gVisor netstack. It supports both an in-process virtual link for cheap tests and an outer UDP packet-carrier link for real process/host boundaries. Selecting this carrier does not select gvisor_packet_link_rebind mobility; that requires a planner-owned endpoint handle and peer agreement.

Index

• Variables
• func Available() error
• func PacketAvailable() error
• type Domain
  • func NewDomain() *Domain
  • func (d *Domain) Factory() *DomainFactory
  • func (d *Domain) Listen(addr string) (*LocalListener, error)
• type DomainFactory
  • func (f *DomainFactory) DialPath(ctx context.Context, spec transport.PathSpec) (transport.PathConn, error)
  • func (f *DomainFactory) Probe(ctx context.Context, spec transport.PathSpec) (transport.PathQuality, error)
• type Listener
  • func ListenPacket(addr string, options ...PacketOption) (*Listener, error)
  • func (l *Listener) Accept(ctx context.Context) (transport.PathConn, error)
  • func (l *Listener) AcceptPath(ctx context.Context) (transport.PathConn, error)
  • func (l *Listener) Addr() net.Addr
  • func (l *Listener) Close() error
  • func (l *Listener) Factory() *Transport
  • func (listener *Listener) LeafMobilityImplementation() leafmobility.ImplementationEvidence
  • func (*Listener) SessionKind() transport.PathSessionKind
• type LocalListener
  • func (l *LocalListener) Accept(ctx context.Context) (transport.PathConn, error)
  • func (l *LocalListener) AcceptPath(ctx context.Context) (transport.PathConn, error)
  • func (l *LocalListener) Addr() net.Addr
  • func (l *LocalListener) Close() error
  • func (l *LocalListener) Factory() *DomainFactory
  • func (*LocalListener) SessionKind() transport.PathSessionKind
• type OuterMTUError
  • func (e *OuterMTUError) Error() string
  • func (e *OuterMTUError) Is(target error) bool
  • func (e *OuterMTUError) Unwrap() error
• type PacketOption
  • func WithPSK(key []byte) PacketOption
  • func WithTrustedCarrier() PacketOption
• type Transport
  • func New(options ...PacketOption) *Transport
  • func NewPacket(options ...PacketOption) (*Transport, error)
  • func (t *Transport) DialPath(ctx context.Context, spec transport.PathSpec) (transport.PathConn, error)
  • func (transport *Transport) LeafMobilityImplementation() leafmobility.ImplementationEvidence
  • func (t *Transport) Probe(ctx context.Context, spec transport.PathSpec) (transport.PathQuality, error)

Variables

var ErrOuterMTU = errors.New("gvisor: outer UDP datagram rejected by path MTU")

ErrOuterMTU identifies a definite zero-byte outer UDP rejection caused by the active path MTU. Callers can use errors.Is without depending on errno.

var ErrOuterPacketUnsupported = errors.New("gvisor: outer UDP packet carrier is unsupported on this platform")

ErrOuterPacketUnsupported reports that this platform cannot prove and enforce the outer UDP no-fragment contract. Process-local gVisor links do not depend on this capability.

var ErrPacketTrustRequired = errors.New("gvisor: packet carrier requires an explicit trust or authentication binding")

ErrPacketTrustRequired reports that an outer UDP packet carrier was used without an explicit carrier-integrity assertion or authentication binding.

Functions

func Available

func Available() error

Available reports whether process-local gVisor carriers are compiled in. Use PacketAvailable for real outer UDP packet carriers. Neither method says whether a particular session is eligible for packet-link rebinding.

func PacketAvailable

func PacketAvailable() error

PacketAvailable reports whether real outer UDP packet carriers can enforce the platform PMTU contract. Available continues to describe process-local gVisor carrier availability.

Types

type Domain

type Domain struct {
	// contains filtered or unexported fields
}

Domain owns process-local gVisor listener resolution. A Domain is explicit so independent rendr Runtime instances never share hidden endpoint state.

func NewDomain

func NewDomain() *Domain

NewDomain returns an isolated process-local gVisor endpoint domain.

func (*Domain) Factory

func (d *Domain) Factory() *DomainFactory

Factory returns a path factory scoped to d's process-local listeners.

func (*Domain) Listen

func (d *Domain) Listen(addr string) (*LocalListener, error)

Listen creates a process-local gVisor TCP listener in d. If addr is empty, a unique address is allocated within the Domain. The returned address is a Domain-local key, not an OS socket address.

type DomainFactory

type DomainFactory struct {
	// contains filtered or unexported fields
}

DomainFactory resolves process-local listeners in one explicit Domain. It deliberately has no specialized mobility implementation method because its paths have no replaceable outer packet link.

func (*DomainFactory) DialPath

func (f *DomainFactory) DialPath(ctx context.Context, spec transport.PathSpec) (transport.PathConn, error)

DialPath resolves and dials a listener in the factory's process-local Domain.

func (*DomainFactory) Probe

func (f *DomainFactory) Probe(ctx context.Context, spec transport.PathSpec) (transport.PathQuality, error)

Probe dials, captures handshake RTT, and closes.

type Listener

type Listener struct {
	// contains filtered or unexported fields
}

Listener accepts gVisor TCP paths for one virtual network.

func ListenPacket

func ListenPacket(addr string, options ...PacketOption) (*Listener, error)

ListenPacket creates a gVisor TCP listener whose virtual link is carried by outer UDP datagrams. Unlike Domain.Listen, addr is a real OS UDP listen address, so the transport can span processes or hosts while remaining unprivileged.

func (*Listener) Accept

func (l *Listener) Accept(ctx context.Context) (transport.PathConn, error)

Accept accepts one inbound gVisor TCP path and wraps it in rendr's standard length-prefixed PathConn framing.

func (*Listener) AcceptPath

func (l *Listener) AcceptPath(ctx context.Context) (transport.PathConn, error)

AcceptPath delegates to Accept.

func (*Listener) Addr

func (l *Listener) Addr() net.Addr

Addr returns the Domain-local key or outer packet-carrier address.

func (*Listener) Close

func (l *Listener) Close() error

Close stops admission immediately. The virtual network remains alive until every accepted path has closed or terminally died.

func (*Listener) Factory

func (l *Listener) Factory() *Transport

Factory returns the outer-packet client path factory paired with this listener.

func (*Listener) LeafMobilityImplementation

func (listener *Listener) LeafMobilityImplementation() leafmobility.ImplementationEvidence

LeafMobilityImplementation reports implementation presence only. Accepted packet-carried endpoints receive independent claims and factual preflight.

func (*Listener) SessionKind

func (*Listener) SessionKind() transport.PathSessionKind

SessionKind reports that gVisor's framed TCP path can carry either rendr session contract.

type LocalListener

type LocalListener struct {
	// contains filtered or unexported fields
}

LocalListener is a process-local gVisor TCP listener. It deliberately does not expose packet-link mobility implementation evidence.

func (*LocalListener) Accept

func (l *LocalListener) Accept(ctx context.Context) (transport.PathConn, error)

Accept returns the next process-local gVisor path.

func (*LocalListener) AcceptPath

func (l *LocalListener) AcceptPath(ctx context.Context) (transport.PathConn, error)

AcceptPath returns the next process-local gVisor path.

func (*LocalListener) Addr

func (l *LocalListener) Addr() net.Addr

Addr returns the Domain-local listener key.

func (*LocalListener) Close

func (l *LocalListener) Close() error

Close stops process-local admission and releases the listener after retained paths close.

func (*LocalListener) Factory

func (l *LocalListener) Factory() *DomainFactory

Factory returns the process-local factory paired with this listener.

func (*LocalListener) SessionKind

func (*LocalListener) SessionKind() transport.PathSessionKind

SessionKind reports the process-local gVisor framed session contract.

type OuterMTUError

type OuterMTUError struct {
	DatagramBytes    int
	MaxDatagramBytes int
	PathMTU          int
	RequiredPathMTU  int
	Err              error
}

OuterMTUError is the stable error form for an EMSGSIZE outer UDP write. DatagramBytes is the attempted UDP payload size; MaxDatagramBytes is the protocol-v5 DATA ceiling derived from the IPv6 minimum MTU.

func (*OuterMTUError) Error

func (e *OuterMTUError) Error() string

func (*OuterMTUError) Is

func (e *OuterMTUError) Is(target error) bool

func (*OuterMTUError) Unwrap

func (e *OuterMTUError) Unwrap() error

type PacketOption

type PacketOption interface {
	// contains filtered or unexported methods
}

PacketOption configures the trust boundary for an outer UDP packet carrier. It is intentionally local to this optional adapter and does not grant a core mobility capability.

func WithPSK

func WithPSK(key []byte) PacketOption

WithPSK binds packet admission, DATA, and mobility controls to a shared key. It provides integrity and peer possession authentication, not encryption. Callers that need confidentiality must still use a confidential carrier or an application protocol such as TLS.

func WithTrustedCarrier

func WithTrustedCarrier() PacketOption

WithTrustedCarrier asserts that the caller-provided UDP carrier already satisfies rendr's C2 integrity boundary, including exclusion of active MITM tuple and payload manipulation. The private link handshake remains an off-path token exchange in this mode; it is not peer authentication.

type Transport

type Transport struct {
	// contains filtered or unexported fields
}

Transport is the gVisor netstack-backed TCP adapter for real outer UDP packet carriers.

func New

func New(options ...PacketOption) *Transport

New returns a gVisor transport for real outer UDP packet carriers. Packet dialing fails with ErrPacketTrustRequired unless options explicitly assert a trusted C2 carrier or configure a PSK. Configuration errors are reported by DialPath; NewPacket is available when eager validation is preferred.

func NewPacket

func NewPacket(options ...PacketOption) (*Transport, error)

NewPacket returns an eagerly validated outer UDP packet transport.

func (*Transport) DialPath

func (t *Transport) DialPath(ctx context.Context, spec transport.PathSpec) (transport.PathConn, error)

DialPath connects through a real outer UDP packet carrier. Each dial creates a fresh gVisor TCP connection.

func (*Transport) LeafMobilityImplementation

func (transport *Transport) LeafMobilityImplementation() leafmobility.ImplementationEvidence

LeafMobilityImplementation reports implementation presence only. Each packet-carried endpoint must still prove sealed ownership, current route eligibility, and peer agreement before the driver can execute.

func (*Transport) Probe

func (t *Transport) Probe(ctx context.Context, spec transport.PathSpec) (transport.PathQuality, error)

Probe dials, captures handshake RTT, and closes.