| name | aquilia-websocket-builder |
| description | Build Aquilia WebSocket and realtime features. Use for SocketController, @Socket, OnConnect/OnDisconnect/Event/AckEvent/Subscribe/Unsubscribe/Guard decorators, adapters, envelopes, middleware, client generation, and aq ws commands. |
Aquilia Websocket Builder
Purpose
Implement realtime channels with Aquilia socket controllers and runtime adapters.
Trigger Conditions
Use for WebSocket endpoints, rooms, events, acknowledgements, subscriptions, presence, Redis/in-memory adapters, message validation, rate limits, and aq ws commands.
Inputs
- Socket path, namespace, allowed origins, message limits, event names, schemas, rooms, and adapter choice.
- Whether generated TypeScript client output is needed.
Execution Flow
- Create a class decorated with
@Socket("/ws/path/:param", ...) that subclasses SocketController.
- Implement lifecycle methods with
@OnConnect() and @OnDisconnect().
- Implement events with
@Event, @AckEvent, @Subscribe, and @Unsubscribe; validate payloads with Schema.
- Register the socket controller in
AppManifest.socket_controllers or rely on socket auto-discovery.
- Use
aq ws inspect, broadcast, gen-client, purge-room, and kick for operational workflows.
Constraints
- Do not invent a Socket.IO protocol; use Aquilia envelopes/runtime classes.
- Respect
allowed_origins, message_rate_limit, and max_message_size.
- Redis adapter requires redis optional dependency and URL configuration.
Implementation Anchors
aquilia/sockets/decorators.py, aquilia/sockets/runtime.py, aquilia/sockets/connection.py, aquilia/sockets/envelope.py, aquilia/sockets/adapters/, aquilia/cli/commands/ws.py, examples/websocket_app/modules/chat/sockets.py.
Examples
- Create
@Socket("/ws/chat/:room", allowed_origins=["*"], message_rate_limit=20).
- Add
@Event("message.send", schema=Schema({"room": str, "text": str}), ack=True).
- Generate a TypeScript client with
aq ws gen-client --out client.ts.
Failure Handling
Handshake/auth/origin failures should map to socket faults. Invalid payloads should fail schema validation. If events do not register, inspect socket_controllers and SocketCompiler metadata.
