# WebSocket Feature-First ## Table of Contents - [What is WebSocket Feature-First?](#what-is-websocket-feature-first) - [Quick Start](#quick-start) - [Convention over Configuration](#convention-over-configuration) - [Folder Structure = WebSocket Events](#folder-structure--websocket-events) - [Event Types](#event-types) - [Event Name Inference](#event-name-inference) - [Steps (Sequential Execution)](#steps-sequential-execution) - [Step Parameters](#step-parameters) - [Context (ctx)](#1-context-ctx) - [Trigger (trigger)](#2-trigger-trigger) - [Responder (responder)](#3-responder-responder) - [Async Tasks](#async-tasks) - [Feature Configuration](#feature-configuration) - [Complete Example: Chat Application](#complete-example-chat-application) - [Best Practices](#best-practices) - [TypeScript Support](#typescript-support) - [FAQ](#faq) --- > Socket.io WebSocket applications with Feature-First architecture Numflow extends its Convention over Configuration philosophy to WebSocket applications using Socket.io. Just like HTTP routes, WebSocket events can be organized by folder structure. --- ## What is WebSocket Feature-First? WebSocket Feature-First brings the same auto-orchestration pattern from HTTP features to WebSocket events: - **Auto-Discovery**: Scans folder structure to find WebSocket event handlers - **Auto-Execution**: Executes steps in numeric order - **Auto-Error Handling**: Catches errors and routes to onError handlers - **Connection Context**: Context persists for the lifetime of the connection --- ## Quick Start ### 1. Install Socket.io ```bash npm install socket.io ``` ### 2. Create Folder Structure ``` ws/ chat/ @connect/ steps/ 100-authenticate.js send/ @message/ steps/ 100-validate.js 200-broadcast.js ``` ### 3. Write Steps ```javascript // ws/chat/@connect/steps/100-authenticate.js module.exports = async (ctx, trigger, responder) => { ctx.userId = trigger.socket.handshake.auth.userId ctx.username = await getUserName(ctx.userId) responder.emit('connected', { userId: ctx.userId }) } ``` ```javascript // ws/chat/send/@message/steps/100-validate.js module.exports = async (ctx, trigger, responder) => { if (!trigger.data.message) { throw new Error('Message is required') } ctx.message = trigger.data.message } ``` ```javascript // ws/chat/send/@message/steps/200-broadcast.js module.exports = async (ctx, trigger, responder) => { responder.broadcast('chat:message', { user: ctx.username, message: ctx.message, timestamp: Date.now() }) responder.emit('chat:sent', { success: true }) } ``` ### 4. Set Up Server ```javascript const numflow = require('numflow') const { createServer } = require('http') const { Server } = require('socket.io') const { createWsHandler } = require('numflow') const app = numflow() const server = createServer(app.handler) const io = new Server(server) // Create WebSocket handler from folder structure const wsHandler = await createWsHandler('./ws') // Connect to Socket.io io.on('connection', wsHandler) server.listen(3000, () => { console.log('Server running on port 3000') }) ``` **That's it!** Folder structure defines your WebSocket events automatically. --- ## Convention over Configuration ### Folder Structure = WebSocket Events ``` ws/ chat/ @connect/ <- 'connect' event (connection) steps/ 100-authenticate.js 200-join-default-room.js @disconnect/ <- 'disconnect' event (disconnection) steps/ 100-cleanup.js send/ @message/ <- 'chat:send' event steps/ 100-validate.js 200-broadcast.js async-tasks/ save-to-db.js join/ @message/ <- 'chat:join' event steps/ 100-join-room.js ``` ### Event Types Use `@` prefix to define event types: | Folder | Event Type | Description | |--------|------------|-------------| | `@connect` | Connection | Runs when client connects | | `@disconnect` | Disconnection | Runs when client disconnects | | `@message` | Custom Message | Custom event from client | ### Event Name Inference The folder path becomes the event name: ``` chat/send/@message/ -> 'chat:send' event chat/join/@message/ -> 'chat:join' event room/create/@message/ -> 'room:create' event user/typing/@message/ -> 'user:typing' event ``` > Note: `@connect` and `@disconnect` always resolve to 'connect' and 'disconnect' respectively. --- ## Steps (Sequential Execution) Steps are executed in numeric order, just like HTTP features: ```javascript // ws/chat/send/@message/steps/100-validate.js module.exports = async (ctx, trigger, responder) => { if (!trigger.data.message) { throw new Error('Message is required') } ctx.message = trigger.data.message } ``` ```javascript // ws/chat/send/@message/steps/200-broadcast.js module.exports = async (ctx, trigger, responder) => { responder.to(ctx.room).emit('chat:message', { user: ctx.userId, message: ctx.message, timestamp: Date.now() }) responder.emit('chat:sent', { success: true }) } ``` **Flow**: 100 -> 200 (automatic!) ### Early Exit with `ctx.__stop` Set `ctx.__stop = true` to halt step execution: ```javascript module.exports = async (ctx, trigger, responder) => { if (!isAuthenticated(ctx)) { responder.emit('error', { message: 'Unauthorized' }) responder.disconnect() ctx.__stop = true // Stop further steps return } } ``` --- ## Step Parameters Each step receives three parameters: `(ctx, trigger, responder)`. ### 1. Context (`ctx`) Context persists for the lifetime of the connection: ```javascript // ws/chat/@connect/steps/100-authenticate.js module.exports = async (ctx, trigger, responder) => { // Set user info on connection ctx.userId = trigger.socket.handshake.auth.userId ctx.username = await getUserName(ctx.userId) ctx.room = 'general' } // ws/chat/send/@message/steps/200-broadcast.js module.exports = async (ctx, trigger, responder) => { // ctx.userId and ctx.username are still available! responder.to(ctx.room).emit('message', { user: ctx.username, text: ctx.message }) } ``` Unlike HTTP features where context is per-request, WebSocket context is **per-connection** and persists across all events for that socket. ### 2. Trigger (`trigger`) Contains event information: ```typescript interface WsTrigger { type: 'ws' // Always 'ws' event: WsEventType // 'connect' | 'disconnect' | 'message' eventName: string // e.g., 'chat:send' data: any // Data sent by client socket: Socket // Socket.io socket object io: Server // Socket.io server object } ``` ### 3. Responder (`responder`) Helper for sending responses: ```typescript interface WsResponder { // Emit to current socket emit(event: string, data: any): void // Broadcast to all except self broadcast(event: string, data: any): void // Emit to specific room (excluding self) to(room: string): WsResponder // Emit to all (including self) toAll(event: string, data: any): void // Join a room join(room: string): void // Leave a room leave(room: string): void // Disconnect disconnect(close?: boolean): void } ``` **Example:** ```javascript module.exports = async (ctx, trigger, responder) => { // Send to self responder.emit('notification', { text: 'Welcome!' }) // Broadcast to everyone except self responder.broadcast('user:joined', { userId: ctx.userId }) // Send to specific room responder.to('admins').emit('alert', { message: 'New user' }) // Send to everyone including self responder.toAll('system', { text: 'Server announcement' }) // Room management responder.join('vip-room') responder.leave('general') } ``` --- ## Async Tasks Background tasks that run after the steps complete: ```javascript // ws/chat/send/@message/async-tasks/save-to-db.js module.exports = async (ctx) => { await db.messages.create({ userId: ctx.userId, message: ctx.message, room: ctx.room, createdAt: new Date() }) } ``` ```javascript // ws/chat/send/@message/async-tasks/notify-mentions.js module.exports = async (ctx) => { const mentions = extractMentions(ctx.message) for (const userId of mentions) { await sendPushNotification(userId, `${ctx.username} mentioned you`) } } ``` Async tasks receive only `ctx` (no trigger or responder). --- ## Feature Configuration Optional `index.js` for advanced configuration: ```javascript // ws/chat/@connect/index.js module.exports = { // Context initialization contextInitializer: async (ctx, trigger) => { ctx.userId = trigger.socket.handshake.auth.userId ctx.connectedAt = Date.now() }, // Error handling onError: async (error, ctx, trigger, responder) => { console.error(`[WS Error] ${error.message}`) responder.emit('error', { message: error.message, code: error.code || 'UNKNOWN_ERROR' }) } } ``` > Note: In numflow, Feature configuration uses plain object export in `index.js`. No wrapper function needed. --- ## Complete Example: Chat Application ### Folder Structure ``` ws/ chat/ @connect/ steps/ 100-authenticate.js 200-join-rooms.js @disconnect/ steps/ 100-leave-rooms.js 200-notify.js send/ @message/ steps/ 100-validate.js 200-broadcast.js async-tasks/ save-message.js join/ @message/ steps/ 100-join-room.js leave/ @message/ steps/ 100-leave-room.js ``` ### Server Setup ```javascript const numflow = require('numflow') const { createServer } = require('http') const { Server } = require('socket.io') const { createWsHandler } = require('numflow') const app = numflow() const server = createServer(app.handler) const io = new Server(server) async function main() { const wsHandler = await createWsHandler('./ws') io.on('connection', wsHandler) server.listen(3000, () => { console.log('Chat server running on port 3000') }) } main() ``` ### Step Implementation ```javascript // ws/chat/@connect/steps/100-authenticate.js module.exports = async (ctx, trigger, responder) => { const token = trigger.socket.handshake.auth.token const user = await verifyToken(token) if (!user) { responder.emit('error', { message: 'Invalid token' }) responder.disconnect() ctx.__stop = true return } ctx.userId = user.id ctx.username = user.name } ``` ```javascript // ws/chat/@connect/steps/200-join-rooms.js module.exports = async (ctx, trigger, responder) => { const rooms = await getUserRooms(ctx.userId) for (const room of rooms) { responder.join(room) } ctx.rooms = rooms responder.emit('connected', { userId: ctx.userId, rooms: ctx.rooms }) } ``` ```javascript // ws/chat/send/@message/steps/100-validate.js module.exports = async (ctx, trigger, responder) => { const { room, message } = trigger.data if (!room || !message) { throw new Error('Room and message are required') } if (!ctx.rooms.includes(room)) { throw new Error('Not a member of this room') } ctx.room = room ctx.message = message } ``` ```javascript // ws/chat/send/@message/steps/200-broadcast.js module.exports = async (ctx, trigger, responder) => { responder.to(ctx.room).emit('chat:message', { userId: ctx.userId, username: ctx.username, message: ctx.message, timestamp: Date.now() }) responder.emit('chat:sent', { success: true }) } ``` ### Client Usage ```javascript const socket = io('http://localhost:3000', { auth: { token: 'user-jwt-token' } }) socket.on('connected', (data) => { console.log('Connected!', data.rooms) }) socket.on('chat:message', (data) => { console.log(`${data.username}: ${data.message}`) }) // Send message socket.emit('chat:send', { room: 'general', message: 'Hello everyone!' }) // Join room socket.emit('chat:join', { room: 'random' }) ``` --- ## Best Practices ### 1. Authenticate in @connect Always authenticate users in the `@connect` step: ```javascript // ws/chat/@connect/steps/100-authenticate.js module.exports = async (ctx, trigger, responder) => { const token = trigger.socket.handshake.auth.token if (!token) { responder.emit('error', { message: 'No token provided' }) responder.disconnect() ctx.__stop = true return } const user = await verifyToken(token) if (!user) { responder.emit('error', { message: 'Invalid token' }) responder.disconnect() ctx.__stop = true return } ctx.user = user } ``` ### 2. Cleanup in @disconnect Clean up resources when user disconnects: ```javascript // ws/chat/@disconnect/steps/100-cleanup.js module.exports = async (ctx, trigger, responder) => { for (const room of ctx.rooms || []) { responder.to(room).emit('user:left', { userId: ctx.userId, username: ctx.username }) } await updateUserStatus(ctx.userId, 'offline') } ``` ### 3. Use Context for Connection State Context persists for the entire connection: ```javascript // Store state in @connect ctx.userId = user.id ctx.rooms = [] ctx.lastActivity = Date.now() // Access in any @message step console.log(ctx.userId) // Still available! ``` ### 4. Error Handling Handle errors gracefully with feature-level or global onError: ```javascript // ws/chat/@connect/index.js module.exports = { onError: async (error, ctx, trigger, responder) => { console.error(`[${ctx.userId || 'unknown'}] ${error.message}`) responder.emit('error', { message: error.message, code: error.code }) if (error.critical) { responder.disconnect() } } } ``` ### 5. Keep Steps Small and Focused Each step should do one thing well, just like HTTP features: ``` steps/ 100-authenticate.js <- Verify user 200-join-rooms.js <- Room management 300-send-welcome.js <- Notify user ``` --- ## TypeScript Support Full TypeScript support is available: ```typescript import { WsContext, WsTrigger, WsResponder } from 'numflow' interface ChatContext extends WsContext { userId: string username: string rooms: string[] } export default async function step( ctx: ChatContext, trigger: WsTrigger, responder: WsResponder ): Promise { responder.emit('welcome', { user: ctx.username }) } ``` --- ## FAQ ### Q: Can I use WebSocket Feature-First with traditional HTTP routes? **A:** Yes! Mix and match: ```javascript const numflow = require('numflow') const { createServer } = require('http') const { Server } = require('socket.io') const { createWsHandler } = require('numflow') const app = numflow() // Traditional HTTP routes app.get('/api/health', (req, res) => { res.json({ status: 'ok' }) }) // HTTP Feature-First routes app.registerFeatures('./features') // WebSocket Feature-First const server = createServer(app.handler) const io = new Server(server) async function main() { const wsHandler = await createWsHandler('./ws') io.on('connection', wsHandler) server.listen(3000) } main() ``` ### Q: How is WebSocket context different from HTTP context? **A:** HTTP context is per-request (created and destroyed per request). WebSocket context is **per-connection** (persists for the lifetime of the socket connection). Data set during `@connect` is available in all subsequent `@message` and `@disconnect` events. ### Q: What happens if a step throws an error? **A:** The error is caught and routed to the feature-specific `onError` handler (if defined in `index.js`), then to the global `onError` handler (if provided in `createWsHandler` options), and finally to a default handler that emits an `error` event to the client. ### Q: Can I use rooms? **A:** Yes! Use `responder.join(room)`, `responder.leave(room)`, and `responder.to(room).emit(event, data)` for room management. ### Q: How do I test WebSocket features? **A:** Steps are just functions. Test them directly: ```javascript const step = require('./ws/chat/send/@message/steps/100-validate') test('validates message', async () => { const ctx = { rooms: ['general'] } const trigger = { data: { room: 'general', message: 'Hello' } } const responder = {} await step(ctx, trigger, responder) expect(ctx.message).toBe('Hello') }) ``` --- ## See Also - **[WebSocket API Reference](../api/websocket.md)** - Complete API documentation - **[Feature-First Guide](./feature-first.md)** - HTTP Feature-First architecture - **[Architecture](../ARCHITECTURE.md)** - System design principles --- *Last updated: 2026-02-06*