ws

type UnimplementedWSServer ¶

type UnimplementedWSServer struct{}

UnimplementedWSServer returns ErrNotImplemented for every WebSocket endpoint, after closing the connection with status 1011 (the server cannot fulfil the request) and reason "not implemented".

func (UnimplementedWSServer) Binary(_ context.Context, conn *wsx.Conn) error

func (UnimplementedWSServer) Feed(_ context.Context, conn *wsx.Conn) error

type WSOptions ¶

type WSOptions struct {
	Auth    func(*http.Request) error
	AuthJWT func(*http.Request) error
	// Limiters is an optional per-path override of the auto-built
	// process-local *wsx.Limiter. Use to wire e.g. a Redis-backed
	// limiter for cross-pod accounting. A path not present in the map
	// gets the auto-built limiter. GAP-0075.
	Limiters map[string]*wsx.Limiter
	// ShutdownContext, when non-nil, bounds every connection these routes
	// accept: once it is cancelled, each open connection is closed with
	// status 1001 (going away) and its ctx is cancelled, so a handler parked
	// in conn.ReadMessage returns. http.Server.Shutdown neither closes nor
	// waits for hijacked connections, so a server that mounts these routes
	// should cancel it when it shuts down; the generated Serve does
	// (SONNY-792). Nil leaves each connection open until its handler returns
	// or its upgrade request's context ends. It bounds the connections these
	// routes accept; a handler a GraphQL subscription runs in-process is
	// bounded by the resolvers' WithShutdownContext instead, which the
	// generated Serve passes the same context.
	ShutdownContext context.Context
	// Handlers, when non-nil, counts every handler these routes run, from
	// the upgrade request until the connection is closed, so a server's
	// shutdown can wait for them (Handlers.Wait). Once Wait has begun, a new
	// upgrade is refused with 503. The generated Serve cancels
	// ShutdownContext, then waits under its shutdown deadline (SONNY-792).
	Handlers *wsx.HandlerGroup
}

WSOptions configures cross-cutting concerns for WebSocket endpoints.

type WSServerInterface ¶

type WSServerInterface interface {
	Binary(ctx context.Context, conn *wsx.Conn) error
	Feed(ctx context.Context, conn *wsx.Conn) error
}

WSServerInterface defines the business logic contract for generated WebSocket endpoints. Embed UnimplementedWSServer and override only the endpoints you need.

ctx is the connection-scoped context (SONNY-792). The generated wrapper derives it from the upgrade request's context after the route's auth verifier has run, so it keeps every value that request carried -- the verifier's claims (securex.ClaimsFromContext), the request and correlation ids, the upgrade's tracing span -- and adds the verified caller: callerctx.MustCaller(ctx) (or securex.MustCaller(ctx)). The caller is built once, at upgrade time, and is shared and read-only; its identity fields come only from what the route's verifier attested -- never from an unverified header, a query parameter or a frame. It is KindUnknown, with no roles and no scopes, when nothing attested an identity: every public route, and an api_key route unless its verifier stashes claims. conn.Context() returns this same ctx.

ctx lives exactly as long as the connection. It is cancelled when your method returns (the wrapper then closes conn). If ctx ends first -- WSOptions.ShutdownContext is cancelled (the generated Serve does this when the server shuts down; the client then gets close status 1001, going away) or the upgrade request's own context is cancelled -- the wrapper closes conn, so a method parked in conn.ReadMessage returns. A peer close or network failure reaches your method as a conn.ReadMessage or conn.WriteMessage error: return, and every goroutine you started with ctx sees it end. Pass ctx to every downstream call; do not swap in a detached root context, which would lose both the caller and the cancellation.

A method can also be reached through a GraphQL subscription, over an in-process connection. ctx then ends with the subscription, or when the server shuts down (the GraphQL resolvers' WithShutdownContext; the generated Serve passes it, and closes the subscriber's graphql-ws connection with 1001 too). Either way the generated Serve ends every WebSocket connection it owns at shutdown.

IMPORTANT (L-53): each method receives the raw *wsx.Conn. Calling conn.ReadMessage() directly performs NO schema validation, even for an endpoint that declares a messageSchema -- the framework cannot intercept or enforce validation on your behalf here (doing so would require either a breaking signature change on this interface, or teaching the config-agnostic pkg/wsx package about a specific generation's schema types, neither of which is done). For an endpoint with a declared messageSchema, call Read<MethodName>(conn) instead of conn.ReadMessage() -- that is the validating entry point; see its doc comment below.