relay

package
v0.12.2 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Sep 8, 2026 License: Apache-2.0 Imports: 22 Imported by: 0

Documentation

Overview

Package relay implements the Headless side of the owned Relay transport. It deliberately depends only on net/http and the protocol primitives so the local daemon remains the authority for Sessions, PTYs, and transcripts.

Index

Constants

View Source 
const (
	FrameOpen      byte = 1
	FrameClose     byte = 2
	FrameText      byte = 3
	FrameBinary    byte = 4
	FrameHTTPHeads byte = 5
	FrameData      byte = 6
	FrameEnd       byte = 7
	FrameWindow    byte = 8
	FrameError     byte = 9
	// Stable descriptive aliases used by callers that do not need the
	// abbreviated wire names above.
	FrameHTTPHeaders  byte = FrameHTTPHeads
	FrameWindowUpdate byte = FrameWindow
)

Variables

View Source 
var ErrRouteNotFound = errors.New("Relay route not found")

Functions

func BackoffDelay 

func BackoffDelay(attempt int, randomFn func() float64) time.Duration

func ContextWithPublicRoute 

func ContextWithPublicRoute(ctx context.Context) context.Context

ContextWithPublicRoute is used by transport-focused tests and adapters that invoke the Host HTTP handler in-process. Production callers should rely on Connector, which installs the marker only after capability verification.

func IsPublicRoute 

func IsPublicRoute(ctx context.Context) bool

IsPublicRoute reports whether a request was dispatched from a Relay route explicitly marked public. The marker is installed only after the BRLY/2 stream capability has been verified by Connector.

func VerifyCapability 

func VerifyCapability(token string, keys map[string]ed25519.PublicKey, hostID, scope string, generation uint64, now time.Time) (map[string]any, error)

Types

type Config 

type Config struct {
	URL             string
	HostID          string
	Name            string
	Secret          string
	Handler         http.Handler
	RelayPublicKeys map[string]ed25519.PublicKey
	Dial            func(context.Context, string, http.Header) (*websocket.Conn, *http.Response, error)
	Random          func() float64
	OnState         func(string)
	OnControl       func(context.Context, StreamOpen, Frame) error
}

Config controls a supervised outbound Host connection. Handler is invoked in-process for HTTP streams; no loopback address is inferred or required.

type ConnectionID 

type ConnectionID [16]byte

ConnectionID identifies one virtual stream on a Host connection. IDs are opaque and must never be reused while the underlying WebSocket is alive.

type Connector 

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

func New 

func New(config Config) (*Connector, error)

func (*Connector) Send 

func (connector *Connector) Send(value Frame) error

Send writes a frame on the authenticated Host connection. It is primarily used by the Headless control adapter to send responses for a Relay stream; callers must use the ID supplied by the corresponding OPEN frame.

func (*Connector) Start 

func (connector *Connector) Start(parent context.Context)

func (*Connector) State 

func (connector *Connector) State() (running, connected bool, currentState, lastError string)

State returns a snapshot of the supervised connector. running reflects the dial loop; connected reflects an open WebSocket; currentState is the most recent label surfaced to OnState ("connecting", "waiting", "open"); lastError is the most recent connectOnce failure or empty when the last attempt succeeded.

func (*Connector) Stop 

func (connector *Connector) Stop()

type Device 

type Device struct {
	ID         string    `json:"id"`
	ClientID   string    `json:"client_id,omitempty"`
	CreatedAt  time.Time `json:"created_at"`
	LastSeenAt time.Time `json:"last_seen_at"`
}

Device is a client association issued by Relay for one Host. The ID is an opaque, non-secret handle suitable for display and revocation.

type Frame 

type Frame struct {
	Kind    byte
	ID      ConnectionID
	Payload []byte
}

Frame is one complete BRLY/2 message. Payload ownership belongs to the caller; Connector copies it before writing to the WebSocket.

type LiveActivityClient 

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

LiveActivityClient publishes Host snapshots to an enrolled Relay. The Host Secret is kept in the client and is sent only as an Authorization header; redirects are disabled so it cannot leave the configured Relay origin.

func NewLiveActivityClient 

func NewLiveActivityClient(baseURL, hostID, token string) (*LiveActivityClient, error)

NewLiveActivityClient validates the Relay origin and Host identity before a request is made. It mirrors RouteClient's URL policy and intentionally does not infer a local listener or a WebSocket path.

func (*LiveActivityClient) Publish 

func (client *LiveActivityClient) Publish(ctx context.Context, snapshot LiveActivitySnapshot) error

Publish sends one complete snapshot. A Relay without APNs credentials may accept the snapshot and report zero deliveries; that keeps Host lifecycle independent from optional mobile notification configuration.

type LiveActivitySession 

type LiveActivitySession struct {
	ID         string `json:"id"`
	Title      string `json:"title,omitempty"`
	Connection string `json:"connection"`
	Activity   string `json:"activity,omitempty"`
	Attention  bool   `json:"attention,omitempty"`
}

LiveActivitySession is the Host-owned projection for one Session. Relay uses the session ID to select the registered ActivityKit push token and keeps the remaining fields opaque until it builds the APNs content state.

type LiveActivitySnapshot 

type LiveActivitySnapshot struct {
	Connection            string                `json:"connection"`
	ActiveSessionCount    int                   `json:"activeSessionCount"`
	WorkingSessionCount   int                   `json:"workingSessionCount"`
	AttentionSessionCount int                   `json:"attentionSessionCount"`
	Sessions              []LiveActivitySession `json:"sessions"`
	UpdatedAt             time.Time             `json:"updatedAt"`
}

LiveActivitySnapshot is a complete Host snapshot. Sending a complete projection lets Relay end an Activity whose Session was deleted without requiring Relay to understand Warren's roster protocol.

type PairingClient 

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

PairingClient performs the two authenticated Relay calls needed to create a shareable invite. The Host Secret remains in the daemon process and is never serialized into PairingResult.

func NewPairingClient 

func NewPairingClient(baseURL, hostID, token string) (*PairingClient, error)

NewPairingClient validates the Relay origin and Host identity before any request is made. Redirects are disabled so the Host Secret cannot be sent to an alternate origin.

func (*PairingClient) Share 

func (client *PairingClient) Share(ctx context.Context) (PairingResult, error)

Share starts a reusable pairing window and exchanges the resulting code for a single opaque invite URL. The Relay remains the authority for expiry and invalidation when a new pairing code is generated.

type PairingResult 

type PairingResult struct {
	PairingURL string `json:"pairing_url"`
	ExpiresIn  int    `json:"expires_in"`
	ExpiresAt  string `json:"expires_at,omitempty"`
	Reusable   bool   `json:"reusable"`
}

PairingResult is the safe, client-facing portion of a Relay share action. Access capabilities and pairing codes are deliberately omitted: the daemon uses them internally and returns only the opaque URL that can be copied or rendered as a QR code by Desktop.

type Route 

type Route struct {
	ID               string   `json:"route_id"`
	PublicHostname   string   `json:"public_hostname"`
	HostID           string   `json:"host_id"`
	Generation       uint64   `json:"generation"`
	PathPrefix       string   `json:"path_prefix"`
	AuthMode         string   `json:"auth_mode"`
	Enabled          bool     `json:"enabled"`
	AllowCredentials bool     `json:"allow_credentials,omitempty"`
	AllowedMethods   []string `json:"allowed_methods,omitempty"`
	AllowedPaths     []string `json:"allowed_paths,omitempty"`
}

Route is the Relay-owned public HTTP/Upgrade route for one Host. It deliberately mirrors Relay's wire representation so the Host can keep only non-secret route metadata in its settings file.

func (Route) PublicURL 

func (route Route) PublicURL(relayURL string) (string, error)

PublicURL derives the canonical browser address from Relay route metadata. IP/localhost deployments keep the Relay port and use the route path; DNS deployments use the route hostname and its configured path prefix. The returned path always ends in a slash so relative Web/PWA assets resolve inside a path-scoped route.

type RouteClient 

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

RouteClient performs authenticated route lifecycle calls against Relay. The token is held only in memory and is never included in a URL.

func NewRouteClient 

func NewRouteClient(baseURL, hostID, token string) (*RouteClient, error)

NewRouteClient validates the Relay origin and Host identity before any request is made. Redirects are disabled so the Host Secret cannot be sent to an alternate origin.

func (*RouteClient) Configure 

func (client *RouteClient) Configure(ctx context.Context, route Route) (Route, error)

Configure creates or updates the Host route. Nil fields preserve Relay's existing values; an omitted body asks Relay to allocate its default address.

func (*RouteClient) Devices 

func (client *RouteClient) Devices(ctx context.Context) ([]Device, error)

Devices returns the currently active client associations for this Host.

func (*RouteClient) Disable 

func (client *RouteClient) Disable(ctx context.Context) error

Disable marks the Relay route unavailable and closes public streams.

func (*RouteClient) Get 

func (client *RouteClient) Get(ctx context.Context) (Route, error)

Get returns the current Relay route.

func (*RouteClient) RevokeDevice 

func (client *RouteClient) RevokeDevice(ctx context.Context, deviceID string) error

RevokeDevice permanently invalidates one client association.

type StreamOpen 

type StreamOpen struct {
	// p2p-signal is the canonical authenticated signaling class.
	Class      string `json:"class"`
	Version    string `json:"version,omitempty"`
	RequestID  string `json:"request_id,omitempty"`
	DeadlineMS int64  `json:"deadline_ms,omitempty"`
	RouteID    string `json:"route_id,omitempty"`
	HostID     string `json:"host_id,omitempty"`
	ClientID   string `json:"client_id,omitempty"`
	Token      string `json:"access_token,omitempty"`
	// PublicRoute is set only by Relay for an authenticated public route.
	// It lets the Host distinguish that one explicitly public WebSocket path
	// from a direct unauthenticated request without forwarding a Host Secret.
	PublicRoute bool `json:"public_route,omitempty"`
}

StreamOpen describes a Relay-created virtual stream.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.