Documentation
¶
Overview ¶
Code generated by apic; DO NOT EDIT.
Index ¶
- Variables
- func ReadItems(conn *wsx.Conn) (types.ItemEvent, error)
- func RegisterGeneratedWS(mux *http.ServeMux, srv WSServerInterface, opts WSOptions)
- func WithWSLimiter(opts *WSOptions, path string, lim *wsx.Limiter)
- func WsValidateItemEvent(b []byte) (types.ItemEvent, error)
- type UnimplementedWSServer
- type WSOptions
- type WSServerInterface
Constants ¶
This section is empty.
Variables ¶
var ErrNotImplemented = errors.New("not implemented")
ErrNotImplemented is returned by UnimplementedWSServer methods.
Functions ¶
func ReadItems ¶ added in v0.17.0
ReadItems is the VALIDATING entry point for this endpoint's declared messageSchema (types.ItemEvent): it reads one WebSocket message from conn and runs it through WsValidateItemEvent (G-04) before returning it. Call this instead of conn.ReadMessage() directly inside Items -- conn.ReadMessage() returns the raw frame with NO schema validation performed; this wrapper is the only way that validation actually happens on the read path (L-53: it is opt-in, not framework-enforced -- nothing stops Items from calling conn.ReadMessage() instead and skipping validation entirely).
func RegisterGeneratedWS ¶
func RegisterGeneratedWS(mux *http.ServeMux, srv WSServerInterface, opts WSOptions)
RegisterGeneratedWS registers WebSocket endpoints; srv handles business logic.
GAP-0076: when the configuration declares at least one WebSocket endpoint with auth: "jwt" but the caller supplied a nil opts.AuthJWT, this function panics with securex.ErrAuthVerifierRequired BEFORE any endpoint is registered. The same guard fires for auth: "api_key" + nil opts.Auth via securex.ErrAuthAPIKeyRequired. Use securex.NewTestVerifier() as the unit-test escape hatch.
func WithWSLimiter ¶
WithWSLimiter installs a custom *wsx.Limiter for a single path. Pass to the caller's option-builder when assembling WSOptions. The override survives ws.go.tmpl regeneration: a consumer that wires a Redis-backed cap need not patch the template. GAP-0075.
func WsValidateItemEvent ¶ added in v0.17.0
WsValidateItemEvent decodes a WebSocket text/JSON message payload against the declared messageSchema types.ItemEvent and enforces its Valid() constraints (G-04). REST, MCP, and GraphQL all decode + Valid() their bound schemas before a handler ever sees the value; the WebSocket surface owns its own read loop (WSServerInterface hands the raw *wsx.Conn to the business handler, so the generator cannot unilaterally intercept every read the way it does for REST/MCP/GraphQL's single request/response cycle), so this helper -- plus the Read<MethodName> wrapper(s) below that call it -- is the enforcement point: use it (directly, or via the wrapper) instead of decoding conn.ReadMessage()'s payload by hand, and a malformed or constraint-violating frame is rejected before your handler logic runs. The frame is decoded strictly (RejectUnknownMembers, as the REST binder does), so an unknown or misspelled member is refused, not dropped (SONNY-2538).
Types ¶
type UnimplementedWSServer ¶
type UnimplementedWSServer struct{}
UnimplementedWSServer returns ErrNotImplemented for every WebSocket endpoint.
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
}
WSOptions configures cross-cutting concerns for WebSocket endpoints.
type WSServerInterface ¶
WSServerInterface defines the business logic contract for generated WebSocket endpoints. Embed UnimplementedWSServer and override only the endpoints you need.
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.
Source Files