websocket

type Accept struct {
	// Tenant is the pinned tenant slug of the upgrade run (unforgeable).
	Tenant string
	// Stack is the web stack that accepted; session runs enter
	// <Stack>/_websocket/0.
	Stack string
	// Ingress and HostnameVerified are copied from the upgrade run's
	// route facts onto every session run's route pre-stamp.
	Ingress          string
	HostnameVerified bool

	// State is a JSON object (≤ StateMaxBytes) stamped verbatim as
	// `_txc.websocket.session.state` on every message; "" = none.
	State string
	// Subprotocols the stack is willing to speak, in preference order;
	// SubprotocolRequired refuses the upgrade when none is offered.
	Subprotocols        []string
	SubprotocolRequired bool
	// Origins are host patterns allowed cross-origin; AnyOrigin disables
	// the check. With neither, only same-host origins (or no Origin
	// header — a non-browser client) are accepted.
	Origins   []string
	AnyOrigin bool
	// Events the stack wants as runs beyond messages (EventClose).
	Events map[string]bool
	// Per-session overrides, 0 = chassis default; the controller clamps
	// them to the chassis ceilings.
	IdleTimeout     time.Duration
	MaxMessageBytes int64
}

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

type Directory interface {
	Register(ctx context.Context, tenant, sid, node, stack string) error
	Refresh(ctx context.Context, tenant, sid, node, stack string) error
	Unregister(ctx context.Context, tenant, sid string) error
	// Lookup answers the owning node's address; found=false is a miss.
	Lookup(ctx context.Context, tenant, sid string) (node string, found bool, err error)
}

type LocalHandler interface {
	Send(ctx context.Context, tenant, sid string, typ MessageType, data []byte) error
	Close(ctx context.Context, tenant, sid string, code int, reason string) error
}

type MessageType int

type Registry interface {
	Enabled() bool
	// RecordAccept stores a stack's decision for the session id the web head
	// minted on the upgrade request.
	RecordAccept(sid string, a Accept) error
	// Send writes one message to a live session of the tenant.
	Send(ctx context.Context, tenant, id string, typ MessageType, data []byte) error
	// CloseSession starts the close handshake on a live session of the tenant.
	CloseSession(ctx context.Context, tenant, id string, code int, reason string) error
}

type Relay interface {
	// Node is the address other nodes use to reach THIS node's inbox — the
	// backend's subject-safe rendering of RelayConfig.NodeID. The controller
	// records it in the directory beside every session it owns.
	Node() string
	// Send writes one message to a session that lives on `node`. It returns
	// the owning node's answer as the Registry errors (ErrSessionNotFound
	// when nothing on that node owns the session, ErrSessionClosed,
	// ErrWriteTimeout, ErrMessageTooLarge), ErrWriteTimeout when ctx expires
	// first, or ErrRelayUnavailable when the bus itself is down.
	Send(ctx context.Context, node, tenant, sid string, typ MessageType, data []byte) error
	// Close starts the close handshake on a session that lives on `node`.
	Close(ctx context.Context, node, tenant, sid string, code int, reason string) error
	// Shutdown stops answering for this node and releases the bus
	// connection, bounded by ctx.
	Shutdown(ctx context.Context) error
}

type RelayConfig struct {
	// NodeID names this chassis (the operator's FQDN, per-Machine on a
	// cloud fleet). The backend derives Node() from it.
	NodeID  string
	Logger  *zap.Logger
	Handler LocalHandler
}

type RelayConstructor func(cfg RelayConfig) (Relay, error)