websocket

type BroadcastSocketAdapterOptions struct {
	// OnError receives encode failures, dropped-frame notices
	// ([ErrFrameDropped]), and unmatched/log-action upstream stream errors.
	OnError func(error)
	// ErrorFrames declares typed error patterns via [ErrorFrame] — same
	// declarative surface [DuplexSocketAdapterOptions.ErrorFrames] uses.
	// When a rule matches an error received on the port's stream Errors
	// channel, the resolved action determines behaviour — see [ErrorFrame].
	// Per-session write/encode failures (already [SocketError]-wrapped) are
	// NOT matched against ErrorFrames — only upstream stream errors are.
	ErrorFrames []ErrorFrameRule
	// Observer receives per-connection RecordRequest and per-frame
	// RecordPublish events. Resolved from ctx when nil.
	Observer stats.Observer
}

type DialAdapterOptions struct {
	// MaxBackoff caps the exponential reconnect backoff. Default 30s
	// (initial step 250ms, doubling per consecutive failure, reset after
	// a successful read).
	MaxBackoff time.Duration
	// Observer receives RecordRequest per dial attempt and
	// RecordSubscribe/RecordPublish per frame. Resolved from ctx when nil.
	Observer stats.Observer
}

type Dialer interface {
	Dial(ctx context.Context, url string) (Socket, error)
}

type DialerOptions struct {
	// Subprotocols lists requested Sec-WebSocket-Protocol values.
	Subprotocols []string
	// RequestHeader is sent with the upgrade request (auth tokens, …).
	RequestHeader http.Header
	// PingInterval is the client keepalive cadence. Default 30s.
	PingInterval time.Duration
	// ReadLimit caps inbound frame size in bytes. Default 1 MiB.
	ReadLimit int64
}

type DuplexSocketAdapterOptions struct {
	// Observer receives per-connection RecordRequest, per-inbound-frame
	// RecordSubscribe, and per-outbound-frame RecordPublish events.
	// Resolved from ctx when nil.
	Observer stats.Observer

	// ErrorFrames declares typed error patterns via [ErrorFrame] — each rule
	// carries its own independently codec-validated payload (pre-encoded),
	// so no type erasure or runtime type assertion against the socket's Out
	// type is needed. When a rule matches an error received on the port's
	// outbound stream Errors channel, the resolved action determines
	// behaviour — see [ErrorFrame].
	ErrorFrames []ErrorFrameRule
}

type ErrorFrameResponse struct {
	// Body is the JSON-encoded typed error payload.
	Body []byte
	// Value is the typed payload before encoding.
	Value any
	// Action is the resolved action for the matched rule.
	Action events.ErrorAction
}

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

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

type IngestSocketAdapterOptions struct {
	// Observer receives per-connection RecordRequest and per-frame
	// RecordSubscribe events. Resolved from ctx when nil.
	Observer stats.Observer
}

type Mux interface {
	Handle(pattern string, handler http.Handler)
}

type Socket interface {
	ReadMessage() ([]byte, error)
	WriteMessage(data []byte) error
	Close() error
}

type SocketError struct {
	// Path is the declared upgrade path template (e.g. "/live/{room}").
	Path string
	// Session identifies the affected peer. Empty for upgrade failures
	// (no session exists yet) and broadcast-level errors.
	Session ports.Session
	// Op is the operation: "upgrade", "read", "write", or "close".
	Op string
	// Err is the underlying error. For a dropped frame (slow client) this
	// is [ErrFrameDropped].
	Err error
}

type Upgrader interface {
	Upgrade(w http.ResponseWriter, r *http.Request) (Socket, error)
}

type UpgraderOptions struct {
	// Subprotocols lists acceptable Sec-WebSocket-Protocol values.
	// Usually taken from the port's [ports.Socket].Subprotocols.
	Subprotocols []string
	// PingInterval is the keepalive ping cadence. Default 30s.
	PingInterval time.Duration
	// ReadLimit caps inbound frame size in bytes. Default 1 MiB.
	ReadLimit int64
	// CheckOrigin overrides gorilla's same-origin policy. Nil keeps the
	// default (reject cross-origin browser connections).
	CheckOrigin func(r *http.Request) bool
}