6.3.1 Developer Guide — Realtime & Events — WebSockets — Channels and Scopes

WebSockets provide low-latency, bidirectional communication for real-time features such as notifications, presence indicators, and live updates. The real-time layer is designed to deliver events efficiently while enforcing strict scoping and authorization rules.

Connection Lifecycle

WebSocket connections are established explicitly by authenticated clients. Each connection is bound to a resolved tenant, organization, and user context.

Lifecycle stages:

Authentication and context resolution

Channel subscription

Event delivery

Graceful disconnect

Connections without valid context are rejected deterministically.

Channel Model

Channels represent scoped streams of real-time events. Clients must explicitly subscribe to channels they are authorized to access.

Channel types:

User-specific channels

Organization-scoped channels

System or module channels

Channels are namespaced to prevent collisions.

Subscription Authorization

Channel subscriptions are authorized server-side. Clients cannot subscribe to channels outside their scope.

Authorization checks include:

Tenant and organization match

Role and permission validation

Feature availability

Example authorization:

if (!$user->canSubscribe($channel)) { abort(403); }

Event Publishing

Events are published to channels asynchronously. Publishing does not depend on active subscribers.

Publishing guarantees:

At-least-once delivery

Ordered per channel where applicable

Non-blocking dispatch

Example publish:

WebSocket::publish($channel, $event);

Payload Structure

Real-time payloads are compact and versioned. Sensitive data is excluded by default.

Payload characteristics:

Minimal required fields

Explicit event type

Versioned schema

Presence and State

Presence information may be derived from active connections. Presence data is transient and not persisted.

Presence behavior:

Best-effort accuracy

No persistence guarantees

Scope-limited visibility

Error Handling and Reconnection

Clients are expected to handle transient disconnects. The system supports graceful reconnection without data corruption.

Error handling guarantees:

Deterministic close codes

No silent subscription loss

Explicit re-subscription on reconnect

Security and Isolation

WebSocket traffic is encrypted in transit. Channel access is tenant- and organization-scoped. Events cannot cross boundaries, and authorization is enforced on every subscription and publish action.