Documentation
¶
Overview ¶
Package transport provides mutually authenticated, multiplexed peer sessions over WebRTC data channels or the gateway's WebSocket relay.
Index ¶
- Constants
- Variables
- func Bridge(ctx context.Context, a, b net.Conn)
- func CloseWrite(conn net.Conn) error
- func NewTCPListener(ctx context.Context, conn net.Conn, address string) (net.Listener, error)
- func ReadMachineState(ctx context.Context, base string, id *identity.Identity, revision uint64, ...) (model.MachineState, bool, error)
- func ServeConnectionTest(conn net.Conn, q model.ConnectionTestOptions) error
- func ServeTCPListener(ctx context.Context, stream net.Conn, listener net.Listener, ...) error
- func ValidateLogChunk(chunk model.TaskLogChunk, offset int64) error
- func WaitForGateway(ctx context.Context, operation string, call func(context.Context) error) error
- type Config
- type DuplexConn
- type Lane
- type Options
- type Peer
- func (p *Peer) Close() error
- func (p *Peer) ConnectionRoutes() model.ConnectionRouteCounts
- func (p *Peer) Connections() map[string]string
- func (p *Peer) FollowTaskLogs(ctx context.Context, target, id string, offset int64, ...) error
- func (p *Peer) IdentityID() string
- func (p *Peer) IsMember(id string) bool
- func (p *Peer) Lookup(ctx context.Context, name string) (model.Node, error)
- func (p *Peer) MachineState(ctx context.Context, revision uint64) (model.MachineState, bool, error)
- func (p *Peer) MachineStatePushed() bool
- func (p *Peer) MachineStateWake() <-chan struct{}
- func (p *Peer) Nodes(ctx context.Context) ([]model.Node, error)
- func (p *Peer) Open(ctx context.Context, target string) (net.Conn, error)
- func (p *Peer) OpenLane(ctx context.Context, target string, lane Lane) (net.Conn, error)
- func (p *Peer) OpenRPC(ctx context.Context, target, method string, params any) (net.Conn, json.RawMessage, error)
- func (p *Peer) OpenTCP(ctx context.Context, target, address string) (net.Conn, error)
- func (p *Peer) OpenTCPListener(ctx context.Context, target, listen string) (net.Conn, string, error)
- func (p *Peer) Owner(id string) string
- func (p *Peer) Resolve(ctx context.Context, name string) (model.Node, error)
- func (p *Peer) Select(ctx context.Context, args json.RawMessage) (model.Node, error)
- func (p *Peer) SendControl(ctx context.Context, kind string, data []byte) error
- func (p *Peer) SessionStats() []model.PeerSession
- func (p *Peer) SetCapabilities(capabilities []model.Capability)
- func (p *Peer) SetControlHandler(handler func(string, []byte))
- func (p *Peer) SetSecretsHandler(key []byte, handler func([]byte))
- func (p *Peer) SetSoftware(info buildinfo.Info)
- func (p *Peer) SetStartupHandler(handler func([]byte))
- func (p *Peer) SetSystemInfo(info model.SystemInfo)
- func (p *Peer) SetWakeHandler(handler func([]byte))
- func (p *Peer) Start(ctx context.Context) error
- func (p *Peer) Stats() model.TransportStats
- func (p *Peer) SupportsNodeHealth() bool
- func (p *Peer) TestConnection(ctx context.Context, target string, options model.ConnectionTestOptions) (model.ConnectionTestResult, error)
Constants ¶
const DuplexVersion = 1
const LogStreamVersion = "task-logs-v1"
const MaxLogChunk = 64 * 1024
const MaxTCPListenerConnections = 128
const TCPListenerProtocol = "tcp-listen-v1"
Variables ¶
var ErrHalfCloseUnsupported = errors.New("connection does not support write-side EOF")
Functions ¶
func Bridge ¶
Bridge preserves the opposite direction after graceful EOF when the destination supports CloseWrite. Errors, cancellation, and legacy full-close streams end both directions. Every copy goroutine is joined before return.
func CloseWrite ¶
func NewTCPListener ¶
NewTCPListener receives sockets multiplexed within an authorized tcp.listen stream. EOF records preserve TCP half-close independently of yamux FIN.
func ReadMachineState ¶
func ReadMachineState(ctx context.Context, base string, id *identity.Identity, revision uint64, inspectOnly bool) (model.MachineState, bool, error)
ReadMachineState reads only the signing identity's policy, even after its bearer credential has been revoked. The bool reports gateway lifecycle support.
func ServeConnectionTest ¶
func ServeConnectionTest(conn net.Conn, q model.ConnectionTestOptions) error
ServeConnectionTest runs only after the node checks membership, instruction authority, method permissions, concurrency, and maintenance admission.
func ServeTCPListener ¶
func ServeTCPListener(ctx context.Context, stream net.Conn, listener net.Listener, wrap func(net.Conn) net.Conn) error
ServeTCPListener owns the bound listener and all of its sockets. Losing the requesting stream closes them even while no TCP connections are active.
func ValidateLogChunk ¶
func ValidateLogChunk(chunk model.TaskLogChunk, offset int64) error
func WaitForGateway ¶
WaitForGateway retries transient connection and policy-query failures during node startup. It must not be used to replay execution or other side effects. Authentication, protocol, TLS validation, and local persistence errors fail immediately. The caller's context owns the entire wait.
Types ¶
type DuplexConn ¶
DuplexConn adds bounded data records and a write-side EOF record to a byte stream. This keeps TCP half-close independent of yamux and WebSocket Close.
func NewDuplexConn ¶
func NewDuplexConn(conn net.Conn) *DuplexConn
func (*DuplexConn) Close ¶
func (c *DuplexConn) Close() error
func (*DuplexConn) CloseWrite ¶
func (c *DuplexConn) CloseWrite() error
type Lane ¶
type Lane string
Lanes isolate long-lived and bulk traffic from short control RPCs. Each lane has its own authenticated TLS/yamux session, including on legacy receivers.
type Options ¶ added in v0.6.3
type Options struct {
// ConfigureWebRTC customizes each peer's legacy and trickle setting engines
// after the transport defaults are applied and before its APIs are created.
ConfigureWebRTC func(*webrtc.SettingEngine) `json:"-"`
}
Options supplies per-peer construction settings, not serialized node or wire configuration. The zero value retains the production networking defaults.
type Peer ¶
type Peer struct {
// contains filtered or unexported fields
}
func (*Peer) ConnectionRoutes ¶ added in v0.2.0
func (p *Peer) ConnectionRoutes() model.ConnectionRouteCounts
ConnectionRoutes separates direct ICE paths, TURN, and the gateway relay. Like Connections, it counts each usable peer once and prefers WebRTC over gateway relay sessions, including relays draining after a direct re-probe.
func (*Peer) Connections ¶
func (*Peer) FollowTaskLogs ¶
func (p *Peer) FollowTaskLogs(ctx context.Context, target, id string, offset int64, emit func(model.TaskLogChunk) error) error
FollowTaskLogs uses one stream on upgraded receivers, or read-only polling on older ones. It never reconnects a broken stream or resubmits the task.
func (*Peer) IdentityID ¶
func (*Peer) IsMember ¶
IsMember only accepts identities attested by this gateway's scoped directory. Identity ownership is immutable, so established direct sessions can remain usable during a gateway outage without crossing fleet boundaries.
func (*Peer) Lookup ¶
Lookup separates fleet-machine discovery from identity checks for live clients. Online results are reused briefly; the gateway's offline notification for an identity, a directory change, or a reconnect evicts them early.
func (*Peer) MachineState ¶
func (*Peer) MachineStatePushed ¶ added in v0.5.7
MachineStatePushed reports whether a live gateway connection will hint at policy changes, so the node can rely on a slower poll as its fallback.
func (*Peer) MachineStateWake ¶ added in v0.5.7
func (p *Peer) MachineStateWake() <-chan struct{}
MachineStateWake signals that this node should read its policy now.
func (*Peer) OpenRPC ¶
func (p *Peer) OpenRPC(ctx context.Context, target, method string, params any) (net.Conn, json.RawMessage, error)
OpenRPC sends one request. The returned stream may contain a bulk payload. It never replays a request after writing application bytes.
func (*Peer) OpenTCPListener ¶
func (p *Peer) OpenTCPListener(ctx context.Context, target, listen string) (net.Conn, string, error)
OpenTCPListener binds a remote port without granting the receiver access to arbitrary services on the caller. Only sockets on this stream are forwarded.
func (*Peer) Owner ¶
Owner is derived only from authenticated gateway metadata, never from an RPC. Transport identities still identify artifact-grant recipients and TLS peers.
func (*Peer) Select ¶
Select uses the same admission filters for node and standalone callers. Among matching machines it prefers the one reporting the fewest active operations, choosing randomly among ties or when load is not visible.
func (*Peer) SendControl ¶
func (*Peer) SessionStats ¶
func (p *Peer) SessionStats() []model.PeerSession
func (*Peer) SetCapabilities ¶
func (p *Peer) SetCapabilities(capabilities []model.Capability)
SetCapabilities updates registration metadata before Start.
func (*Peer) SetControlHandler ¶
func (*Peer) SetSecretsHandler ¶ added in v0.6.0
SetSecretsHandler installs a bounded, gateway-only management handler before Start.
func (*Peer) SetSoftware ¶
func (*Peer) SetStartupHandler ¶ added in v0.5.0
SetStartupHandler is configured before Start by an installed node only.
func (*Peer) SetSystemInfo ¶
func (p *Peer) SetSystemInfo(info model.SystemInfo)
SetSystemInfo attaches an initial hardware/resource snapshot before Start.
func (*Peer) SetWakeHandler ¶ added in v0.5.0
SetWakeHandler receives wake requests the gateway relays for the fleet owner.
func (*Peer) Stats ¶
func (p *Peer) Stats() model.TransportStats
Stats reports cumulative transport counters for local diagnostics.
func (*Peer) SupportsNodeHealth ¶
SupportsNodeHealth prevents new reports from disconnecting older gateways.
func (*Peer) TestConnection ¶
func (p *Peer) TestConnection(ctx context.Context, target string, options model.ConnectionTestOptions) (model.ConnectionTestResult, error)
TestConnection measures one authenticated bulk stream, without disk staging or replay. Upload/download are sequential and relative to the initiating peer.
Source Files
¶
Directories
¶
| Path | Synopsis |
|---|---|
|
Package transporttest supplies isolated transport construction for local tests.
|
Package transporttest supplies isolated transport construction for local tests. |