Defines verification and operations for authenticated WebSocket connections, covering handshake origin, message authorization, limits, liveness, backpressure, reconnect, deployment drain, and observability.
Package status: reference context ready for human review. The contract and test scenarios are complete, but no claim is made that an adopting implementation has passed them.
Decision
Authorize both the HTTP upgrade and each message action. Bind a connection to an authenticated subject, tenant, policy version, and expiry; apply bounded queues and resume semantics rather than assuming a persistent socket is reliable.
Scope
- Upgrade, authentication, Origin validation, subscriptions, message schema, authorization, limits, heartbeat, reconnect, resume, drain, and audit.
- Browser and service clients with authenticated bidirectional messaging.
- Load, abuse, and deployment verification.
Outside this block
- A specific transport library or end-to-end event-store design.
- Using a connected socket as permanent proof of authorization.
Contract
- Browser upgrades validate an allowlisted Origin and use credentials protected from URL/log leakage.
- Each inbound message validates envelope schema, size, rate, action, resource, tenant, and current authorization.
- Subscription authorization is rechecked on policy change or at a bounded interval.
- Outbound queues have byte/message limits and an explicit slow-consumer policy.
- Messages that support resume carry monotonic stream offsets; delivery semantics and duplicate handling are declared.
- Server drain stops new upgrades, notifies or closes connections with a reconnectable code, and has a hard deadline.
Implementation guidance
- Use a small envelope with message ID, type, version, correlation ID, and payload.
- Prefer secure same-site cookies or a short-lived handshake credential sent in an approved mechanism; redact it everywhere.
- Implement ping/pong or application heartbeats with measured idle and timeout profiles.
- Load-test reconnect storms and slow consumers, not only steady message throughput.
Failure handling and safeguards
- Invalid schema or unauthorized action returns a bounded error and may close repeated offenders without echoing sensitive payload.
- When authorization cannot be refreshed, stop protected subscriptions.
- When a resume offset is outside retention, require a snapshot refresh rather than silently skipping history.
Verification and operations
- Measure active connections, upgrade denial by reason, message rate/bytes, authz denial, queue depth, slow-consumer closes, heartbeat timeout, reconnect rate, and resume failures.
- Alert on origin-denial spikes, memory per connection, and reconnect storms.
- Run deployment drain and revocation tests in staging and periodically in production-safe exercises.
The executable-looking examples in this package are fixtures and acceptance contracts. Run
python tools/validate.py from the collection root to check package structure and metadata; then
implement and execute the scenarios in the target repository.
Adoption assumptions
- Names and numeric values in
example.yamlare an adoption profile, not universal defaults. - The adopting team must map actors, data classes, error vocabulary, and ownership to its system.