add-socket-event

Add a socket event

Socket wiring lives in services/socket.js; per-event logic lives in feature actions invoked with a context object (to avoid the circular dependency). Read README "Socket Architecture".

Plan the event contract, authorization, rooms, payload, persistence/commit ordering, failure behavior, and tests and get sign-off before scaffolding or edits. Confirm the owning feature has complete structure with yarn repair <Feature> --dry-run, then yarn repair <Feature>.

Concepts

• SOCKET_ROOMS and SOCKET_EVENTS are constants in services/socket.js, ALL_CAPS_WITH_UNDERSCORES. Events are named FEATURE_ACTION (e.g. ORDER_CREATED).
• Two room kinds: broadcast rooms — a fixed name everyone of a type joins (GLOBAL, ADMIN); instance rooms — ROOM_TYPE${socketWrapper(id)} → USER<uuid>, CHANNEL<uuid> (socketWrapper wraps the id in <>).
• Socket.IO runs with a Redis adapter, so io.to(room).emit(...) reaches clients across all Node processes — never track sockets in a local variable.
• Never import services/socket inside an action it calls — use the injected context { io, SOCKET_ROOMS, SOCKET_EVENTS, socketWrapper }. HTTP actions that emit use socket.getIO() (never import io directly — it's null at require-time).

Steps

1. Scaffold the action when needed with yarn gen <Feature> -a V1<Action>; never hand-create it. Add the event name to SOCKET_EVENTS (and a room to SOCKET_ROOMS if needed) in services/socket.js.

2. Inbound (client → server): add a handler inside connect(socket):

   socket.on(SOCKET_EVENTS.<EVENT>, async (data, callback) => {
     try {
       const result = await V1<Action>({ ...data, userId: socket.user.id }, { io, SOCKET_ROOMS, SOCKET_EVENTS, socketWrapper });
       return callback(null, result);
     } catch (error) { return callback(error); }
   });
   

   The action validates with Joi and throws on failure (socket actions throw, like tasks). Import the action at the top of socket.js (that's why actions can't import socket back).