relay

Documentation

Overview

Package relay connects the local Canary app host to an optional public relay. The relay is transport only: it forwards allowlisted HTTP and streaming paths to the local host, while device grants, sessions, authorization, app state, daemon access, and broker authority remain local.

Index

• Constants
• type Client
• type Noop
  • func (n Noop) PairingURL(raw string) string
  • func (n Noop) Run(context.Context)
  • func (n Noop) Status() Status
• type RouteRegistration
• type Status
• type Worker
  • func NewWorker(opts WorkerOptions) (*Worker, error)
  • func (w *Worker) PairingURL(raw string) string
  • func (w *Worker) PublicURL() string
  • func (w *Worker) Run(ctx context.Context)
  • func (w *Worker) Status() Status
• type WorkerOptions

Constants

const DefaultWorkerURL = "https://remote.osauer.dev"

DefaultWorkerURL is the public relay origin used when WorkerOptions.BaseURL is empty.

Types

type Client

type Client interface {
	// Run maintains transport activity until ctx cancellation or implementation
	// shutdown. Callers normally invoke it in a background goroutine.
	Run(ctx context.Context)
	// Status returns the latest detached transport status.
	Status() Status
	// PairingURL annotates raw with non-authorizing transport routing data.
	PairingURL(raw string) string
}

Client is the app host's optional relay transport. Implementations may expose the local host through an allowlisted remote route but do not authenticate devices or authorize app operations.

type Noop

type Noop struct {
	PublicURL string
}

Noop is a disabled relay client. PublicURL is reported for local app links, but Run starts no transport and PairingURL leaves URLs unchanged.

func (Noop) PairingURL

func (n Noop) PairingURL(raw string) string

PairingURL returns raw unchanged because Noop has no remote route.

func (Noop) Run

func (n Noop) Run(context.Context)

Run implements Client without starting background work.

func (Noop) Status

func (n Noop) Status() Status

Status returns the disabled relay state and configured public URL.

type RouteRegistration

type RouteRegistration struct {
	RouteID        string
	PublicURL      string
	ConnectorURL   string
	ConnectorToken string
	ExpiresAt      time.Time
}

RouteRegistration contains relay-issued transport coordinates. RouteID is a non-authorizing route selector; ConnectorToken is a bearer secret used only by the outbound connector. ExpiresAt is the relay-reported route expiry.

type Status

type Status struct {
	Mode      string `json:"mode"`
	URL       string `json:"url,omitempty"`
	Connected bool   `json:"connected"`
	Message   string `json:"message,omitempty"`
}

Status is a concurrency-safe snapshot of relay transport state. URL is the public app origin, Connected reports only the connector transport, and Message is diagnostic text rather than authorization or app-health state.

type Worker

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

Worker maintains one outbound relay registration and WebSocket connection to the local app host. It forwards only package-allowlisted paths and delegates authentication and authorization to the local HTTP server. Status, PairingURL, and PublicURL may be called concurrently with Run; Run itself should be started only once.

func NewWorker

func NewWorker(opts WorkerOptions) (*Worker, error)

NewWorker validates opts and constructs a stopped Worker without performing network I/O. An empty BaseURL uses DefaultWorkerURL, OriginURL is required, and resume route ID and connector token must be either both present or both absent. A nil HTTPClient uses the package's dual-stack client.

func (*Worker) PairingURL

func (w *Worker) PairingURL(raw string) string

PairingURL adds the current non-authorizing route ID as the remote query parameter unless raw already supplies one. It returns raw unchanged for a nil Worker, an unavailable route, or an invalid URL, and never includes the connector token.

func (*Worker) PublicURL

func (w *Worker) PublicURL() string

PublicURL returns the current public relay origin. Before registration this is the configured base URL; after registration it is the relay-issued URL. A nil Worker returns an empty string.

func (*Worker) Run

func (w *Worker) Run(ctx context.Context)

Run registers or resumes the relay route and maintains its outbound WebSocket until ctx is cancelled. Transient registration and connection failures are retried with bounded backoff and reported through Worker.Status. Definitive route rejection triggers fresh registration. Run returns no error and must not be invoked concurrently on one Worker.

func (*Worker) Status

func (w *Worker) Status() Status

Status returns a detached, concurrency-safe snapshot of the relay connection. Connected describes the WebSocket transport only; it does not establish device authentication, daemon availability, or broker readiness.

type WorkerOptions

type WorkerOptions struct {
	BaseURL              string
	OriginURL            string
	Version              string
	HTTPClient           *http.Client
	ResumeRouteID        string
	ResumeConnectorToken string
	OnRoute              func(RouteRegistration) error
}

WorkerOptions configures one outbound relay connector. OriginURL is the local app-host origin to which allowlisted requests are forwarded. ResumeRouteID and ResumeConnectorToken must be supplied together; the token is a bearer secret. OnRoute receives new or extended route credentials for durable app-local storage and must protect ConnectorToken.