@emeryld/rrroutes-server 2.1.5 → 2.1.7

package/README.md

@@ -1,53 +1,305 @@
+<!--
+Summary:
+- Added full quick start for binding finalized contracts to Express with typed controllers, ctx builders, derived upload middleware, and output validation.
+- Documented debug options, per-route overrides, partial/complete registration helpers, missing-controller warnings, and socket server helpers (typed events, heartbeat, room hooks).
+- Missing: cluster/multi-process Socket.IO deployment notes and an end-to-end auth example (ctx + room allow/deny) to add later.
+-->
+
 # @emeryld/rrroutes-server
 
-Express bindings for RRRoutes contracts. This package maps finalized leaves to an Express router, validating params/query/body/output with Zod, wiring ctx-aware middleware, and warning about missing controllers.
+Express/Socket.IO bindings for RRRoutes contracts. Map finalized leaves to an Express router with Zod-validated params/query/body/output, typed controller maps, ctx-aware middleware, optional upload derivation, and structured debug logging. Socket helpers add validated events, heartbeat, room hooks, and lifecycle debugging.
 
 ## Installation
 
 ```sh
-pnpm add @emeryld/rrroutes-server express
+pnpm add @emeryld/rrroutes-server express socket.io
 # or
-npm install @emeryld/rrroutes-server express
+npm install @emeryld/rrroutes-server express socket.io
 ```
 
-The server package depends on `@emeryld/rrroutes-contract` and `zod` internally.
+This package peers with `@emeryld/rrroutes-contract` and bundles `zod`.
 
-## Usage
+## Quick start: HTTP routes
 
 ```ts
 import express from 'express';
-import { createRRRoute } from '@emeryld/rrroutes-server';
-import { registry } from '../routes';
-import { controllers } from './controllers';
+import { finalize, resource } from '@emeryld/rrroutes-contract';
+import { createRRRoute, defineControllers } from '@emeryld/rrroutes-server';
+import multer from 'multer';
+import { z } from 'zod';
+
+// 1) Build & finalize contracts (usually elsewhere in your app)
+const leaves = resource('/api')
+  .sub('profiles', (r) =>
+    r
+      .get({
+        outputSchema: z.array(z.object({ id: z.string().uuid(), name: z.string() })),
+        description: 'List profiles',
+      })
+      .routeParameter('profileId', z.string().uuid(), (p) =>
+        p
+          .patch({
+            bodySchema: z.object({ name: z.string().min(1) }),
+            outputSchema: z.object({ id: z.string().uuid(), name: z.string() }),
+          })
+          .sub('avatar', (a) =>
+            a
+              .put({
+                bodyFiles: [{ name: 'avatar', maxCount: 1 }], // derive upload middleware
+                bodySchema: z.object({ avatar: z.instanceof(Blob) }),
+                outputSchema: z.object({ ok: z.literal(true) }),
+              })
+              .done(),
+          )
+          .done(),
+      )
+      .done(),
+  )
+  .done();
 
-const router = express.Router();
+const registry = finalize(leaves);
 
-const server = createRRRoute(router, {
-  baseUrl: '/api',
-  buildCtx: async (req) => ({ user: await loadUser(req) }),
+// 2) Wire Express with ctx + derived upload middleware
+const upload = multer({ storage: multer.memoryStorage() });
+const app = express();
+const server = createRRRoute(app, {
+  buildCtx: async (req) => ({ user: await loadUser(req), routesLogger: console }), // ctx lives on res.locals[CTX_SYMBOL]
+  globalMiddleware: {
+    before: [
+      ({ ctx, next }) => {
+        if (!ctx.user) throw new Error('unauthorized');
+        next();
+      },
+    ],
+  },
   fromCfg: {
+    upload: (files) => (files && files.length > 0 ? [upload.fields(files)] : []),
+  },
+  validateOutput: true, // parse handler returns with outputSchema (default true)
+  debug: { request: true, handler: true, verbose: true, logger: (e) => console.debug(e) },
+});
+
+// 3) Author controllers with enforced keys/types
+const controllers = defineControllers<typeof registry, { user: { id: string } }>()({
+  'GET /api/profiles': {
+    handler: async ({ ctx }) => {
+      return fetchProfilesFor(ctx.user.id);
+    },
+  },
+  'PATCH /api/profiles/:profileId': {
+    before: [({ ctx, params, next }) => (params.profileId === ctx.user.id ? next() : next(new Error('Forbidden')))],
+    handler: async ({ params, body }) => {
+      return updateProfile(params.profileId, body);
+    },
+  },
+  'PUT /api/profiles/:profileId/avatar': {
+    handler: async ({ req, params }) => {
+      const avatar = (req.files as any)?.avatar?.[0];
+      await storeAvatar(params.profileId, avatar?.buffer);
+      return { ok: true };
+    },
   },
 });
 
 server.registerControllers(registry, controllers);
-server.warnMissingControllers(registry, console);
+server.warnMissingControllers(registry, console); // warns in dev about unhandled leaves
 
-`buildCtx` can optionally include `routesLogger` to route handler debug events to a per-request logger.
+app.listen(3000);
 ```
 
-## Scripts
+## Detailed usage (HTTP)
 
-```sh
-pnpm install
-pnpm --filter @emeryld/rrroutes-server build
-pnpm --filter @emeryld/rrroutes-server test
+### Controller maps and typing
+
+```ts
+import { defineControllers, bindExpressRoutes } from '@emeryld/rrroutes-server';
+
+const controllers = defineControllers<typeof registry, Ctx>()({
+  'POST /v1/articles': { handler: async ({ body, ctx }) => createArticle(ctx.user.id, body) },
+});
+
+// register only the controllers provided (missing keys are ignored)
+bindExpressRoutes(app, registry, controllers, {
+  buildCtx: () => ({ user: { id: '123' } }),
+});
+
+// or enforce every key is present at compile time
+bindExpressRoutes(app, registry, controllers as { [K in keyof typeof registry.byKey]: any }, { buildCtx });
 ```
 
-## Publishing
+- `defineControllers<Registry, Ctx>()(map)` keeps literal `"METHOD /path"` keys accurate and infers params/query/body/output types per leaf.
+- `registerControllers` accepts partial maps (missing routes are skipped); `bindAll` enforces completeness at compile time.
+- `warnMissingControllers(router, registry, logger)` inspects the Express stack and warns for any leaf without a handler.
 
-```sh
-cd packages/server
-npm publish --access public
+### Middleware order and ctx usage
+
+Order: `buildCtx` → `global.before` → `fromCfg` (derived) → `route.before` → handler → `route.after` → `global.after`.
+
+```ts
+import { getCtx, CtxRequestHandler } from '@emeryld/rrroutes-server';
+
+const audit: CtxRequestHandler<Ctx> = ({ ctx, req, next }) => {
+  ctx.routesLogger?.info?.('audit', { user: ctx.user?.id, path: req.path });
+  next();
+};
+
+const server = createRRRoute(app, {
+  buildCtx: (req, res) => ({ user: res.locals.user, routesLogger: console }),
+  globalMiddleware: { before: [audit] },
+});
+
+// Inside any Express middleware (even outside route.before/after), use getCtx to retrieve typed ctx:
+app.use((req, res, next) => {
+  const ctx = getCtx<Ctx>(res);
+  ctx?.routesLogger?.debug?.('in arbitrary middleware');
+  next();
+});
+```
+
+- `CtxRequestHandler` receives `{ req, res, next, ctx }` with your typed ctx.
+- `route.after` middlewares run **only when the handler calls `next()`** (useful for fall-through auth or response post-processing).
+
+### Derived middleware from route cfg (uploads)
+
+Use `fromCfg.upload` to attach middleware when a leaf declares `bodyFiles`.
+
+```ts
+import multer from 'multer';
+import { FileField } from '@emeryld/rrroutes-contract';
+
+const upload = multer({ storage: multer.memoryStorage() });
+
+const server = createRRRoute(app, {
+  buildCtx,
+  fromCfg: {
+    upload: (files: FileField[] | undefined) => (files?.length ? [upload.fields(files)] : []),
+  },
+});
+```
+
+### Output validation and custom responders
+
+- `validateOutput: true` parses handler return values with the leaf `outputSchema`. Set to `false` to skip.
+- Override `send` to change response behavior (e.g., `res.status(201).json(data)`).
+
+```ts
+const server = createRRRoute(app, {
+  buildCtx,
+  send: (res, data) => res.status(201).json({ data }),
+});
+```
+
+### Debug logging
+
+Global debug options:
+
+```ts
+const server = createRRRoute(app, {
+  buildCtx,
+  debug: {
+    request: true, // register/request/handler/buildCtx event toggles
+    handler: true,
+    verbose: true, // include params/query/body/output/errors
+    only: ['users:list'], // filter by RouteDef.debug?.debugName
+    logger: (event) => console.log('[route-debug]', event),
+  },
+});
+```
+
+Per-route overrides:
+
+```ts
+server.register(registry.byKey['GET /api/profiles'], {
+  debug: { handler: true, debugName: 'profiles:list' },
+  handler: async () => [],
+});
+```
+
+Context logger passthrough: if `buildCtx` provides `routesLogger`, handler debug events also flow to that logger (useful for request-scoped loggers).
+
+### Recipes
+
+- **Combine registries:** build leaves per domain, spread before `finalize([...usersLeaves, ...projectsLeaves])`, then register once.
+- **Fail fast on missing controllers:** call `assertAllControllersPresent(router, registry, controllers)` pattern by invoking `registerControllers(registry, controllers, true as any)` or running `warnMissingControllers` during startup.
+- **Operator-specific middleware:** attach `route.before` per controller (e.g., role checks) and keep `global.before` minimal (auth/session parsing).
+
+## Socket server (typed events, heartbeat, rooms)
+
+`@emeryld/rrroutes-server` also ships a typed Socket.IO wrapper that pairs with `defineSocketEvents` from the contract package.
+
+```ts
+import { Server } from 'socket.io';
+import { defineSocketEvents } from '@emeryld/rrroutes-contract';
+import { createSocketConnections, createConnectionLoggingMiddleware } from '@emeryld/rrroutes-server';
+import { z } from 'zod';
+
+const { config, events } = defineSocketEvents(
+  {
+    joinMetaMessage: z.object({ room: z.string() }),
+    leaveMetaMessage: z.object({ room: z.string() }),
+    pingPayload: z.object({ sentAt: z.string() }),
+    pongPayload: z.object({ sentAt: z.string(), sinceMs: z.number().optional() }),
+  },
+  {
+    'chat:message': { message: z.object({ roomId: z.string(), text: z.string(), userId: z.string() }) },
+  },
+);
+
+const io = new Server(3000, { cors: { origin: '*', credentials: true } });
+io.use(createConnectionLoggingMiddleware({ includeHeaders: false }));
+
+const sockets = createSocketConnections(io, events, {
+  config,
+  heartbeat: { enabled: true }, // enables sys:ping/sys:pong using config schemas
+  sys: {
+    'sys:connect': async ({ socket, complete }) => {
+      socket.data.user = await loadUserFromHandshake(socket.handshake);
+      await complete(); // attach built-ins (ping/pong, join/leave)
+    },
+    'sys:ping': async ({ socket, ping }) => ({
+      sentAt: ping.sentAt,
+      sinceMs: Date.now() - Date.parse(ping.sentAt),
+    }),
+  },
+  debug: {
+    register: true,
+    handler: true,
+    emit: true,
+    verbose: true,
+    logger: (e) => console.debug('[socket-debug]', e),
+  },
+});
+
+// Validate inbound payloads + emit envelopes
+sockets.on('chat:message', async (payload, ctx) => {
+  await saveMessage(payload, ctx.user);
+  // broadcast to room participants
+  sockets.emit('chat:message', payload, payload.roomId);
+});
+
+// Graceful shutdown
+process.on('SIGTERM', () => sockets.destroy());
 ```
 
-Double-check `packages/server/package.json` for the version bump and ensure the bundled `dist/` output is up to date before publishing.
+- Payloads are validated on both emit and receive; invalid payloads trigger `<event>:error` with Zod issues.
+- Built-in system events: `sys:connect`, `sys:disconnect`, `sys:ping`, `sys:pong`, `sys:room_join`, `sys:room_leave`.
+- Heartbeat is enabled by default (`heartbeat.enabled !== false`) and uses `config.pingPayload` / `config.pongPayload` schemas.
+- `destroy()` removes listeners, room handlers, and connection hooks—safe for test teardown.
+
+## Edge cases and notes
+
+- `route.after` only runs if the handler calls `next()` (mirrors Express semantics).
+- `compilePath`/param parsing exceptions bubble to Express error handlers; wrap `buildCtx`/middleware in try/catch if you need custom error shapes.
+- When `validateOutput` is true and no `outputSchema` exists, raw handler output is passed through.
+- `fromCfg.upload` runs only when `leaf.cfg.bodyFiles` is a non-empty array.
+- Socket `emit` will throw on invalid payloads; handle errors around broadcast loops.
+
+## Scripts
+
+Run from repo root:
+
+```sh
+pnpm --filter @emeryld/rrroutes-server build    # tsup + d.ts
+pnpm --filter @emeryld/rrroutes-server typecheck
+pnpm --filter @emeryld/rrroutes-server test
+```