channel

Load the triad-channel skill for the authoritative channel() signature and state typing rules. Load triad-behaviors for channel-specific assertion phrases.

Add a new WebSocket channel to the project based on the user's description ($ARGUMENTS).

Prerequisites

1. Confirm the project uses @triadjs/fastify — Express and Hono adapters do NOT support channels. If the project is on a non-Fastify adapter, tell the user and stop.
2. Install @fastify/websocket if not already present: npm install @fastify/websocket.

Steps

1. Place the channel in src/channels/<name>.ts.

2. Define the state interface and use the phantom witness pattern:

   interface ChatRoomState {
     userId: string;
     userName: string;
     roomId: string;
   }
   
   channel({
     state: {} as ChatRoomState, // phantom — value ignored, type used for ctx.state
     // ...
   });
   

   Without the witness, ctx.state is Record<string, any>.

3. Declare clientMessages (what clients send) and serverMessages (what the server emits). Every clientMessages key must have a matching handlers[key] — missing or extra keys are compile errors.

4. Implement onConnect — validate the handshake (via schemas or ctx.reject(code, msg)), seed ctx.state, optionally broadcast a join event.

5. Implement onDisconnect — optionally broadcast a leave event. Don't throw.

6. Implement per-message handlers — call repositories via ctx.services, then:

   • ctx.broadcast.eventName(payload) to send to everyone including the sender
   • ctx.broadcastOthers.eventName(payload) to exclude the sender
   • ctx.send.eventName(payload) to reply only to this client

7. If the channel is browser-facing, use auth.strategy: 'first-message' — browsers cannot set custom headers on new WebSocket(). Declare an __auth client message and cast ctx.authPayload inside onConnect.

8. Add channel behaviors:

   behaviors: [
     scenario('broadcasting a message reaches every client')
       .given('two connected clients')
       .setup(async () => ({ /* ... */ }))
       .when('alice sends a sendMessage')
       .then('all clients receive a message event')
       .and('bob receives a message with text "hello"'),
   ]
   

   Use channel-specific phrases from the triad-behaviors skill — <client> receives a <type> event, all clients receive..., connection is rejected with code N.