arcway 0.1.0

package/server/ws/realtime.js

@@ -0,0 +1,318 @@
+import { WebSocketServer, WebSocket } from 'ws';
+import { randomUUID } from 'node:crypto';
+import { matchRoute } from '../router/routes.js';
+import { getMiddlewareForRoute, buildMiddlewareChain } from '../router/middleware.js';
+import { parseCookiesFromHeader, resolveSession, flattenHeaders } from '../session/helpers.js';
+import { toErrorMessage } from '../helpers.js';
+import { buildContext } from '../context.js';
+import { registerWsServer, unregisterWsServer } from './registry.js';
+function createRealtimeServer(options) {
+  const {
+    server,
+    routes,
+    middleware,
+    appContext,
+    session: sessionConfig,
+    log,
+    path: wsPath = '/ws',
+  } = options;
+  const wss = new WebSocketServer({ noServer: true });
+  const clients = new Map();
+  const clientsBySocketId = new Map();
+  function buildCtx(reqInfo) {
+    const requestLog = {
+      debug(message, data) {
+        appContext.log.debug(message, { ...data, requestId: reqInfo.requestId });
+      },
+      info(message, data) {
+        appContext.log.info(message, { ...data, requestId: reqInfo.requestId });
+      },
+      warn(message, data) {
+        appContext.log.warn(message, { ...data, requestId: reqInfo.requestId });
+      },
+      error(message, data) {
+        appContext.log.error(message, { ...data, requestId: reqInfo.requestId });
+      },
+    };
+    return buildContext({ ...appContext, log: requestLog }, { req: reqInfo });
+  }
+  function sendToClient(ws, msg) {
+    if (ws.readyState === WebSocket.OPEN) {
+      ws.send(JSON.stringify(msg));
+    }
+  }
+  function sendToSocket(socketId, path, response) {
+    const client = clientsBySocketId.get(socketId);
+    if (!client) return;
+    sendToClient(client.ws, {
+      path,
+      data: response.data,
+      error: response.error,
+      status: response.status,
+    });
+  }
+  function broadcastToPath(path, response) {
+    const msg = {
+      path,
+      data: response.data,
+      error: response.error,
+      status: response.status,
+    };
+    for (const client of clients.values()) {
+      if (client.subscriptions.has(path)) {
+        sendToClient(client.ws, msg);
+      }
+    }
+  }
+  function buildRequestInfo(client, wsMsg, params) {
+    const mergedQuery = {
+      ...(wsMsg.query ?? {}),
+      ...params,
+    };
+    return {
+      requestId: randomUUID(),
+      method: wsMsg.method,
+      path: wsMsg.path,
+      query: mergedQuery,
+      body: wsMsg.body,
+      headers: client.headers,
+      cookies: client.cookies,
+      session: client.session,
+      socketId: client.socketId,
+    };
+  }
+  async function runHandler(route, reqInfo) {
+    const middlewareFns = getMiddlewareForRoute(middleware, route.pattern);
+    const chainedHandler = buildMiddlewareChain(middlewareFns, route.config.handler);
+    const ctx = buildCtx(reqInfo);
+    try {
+      return await chainedHandler(ctx);
+    } catch (err) {
+      log.error(`WS handler error in ${route.method} ${route.pattern}`, {
+        error: toErrorMessage(err),
+      });
+      return {
+        status: 500,
+        error: { code: 'HANDLER_ERROR', message: 'An internal error occurred' },
+      };
+    }
+  }
+  async function handleSubscribe(client, wsMsg) {
+    const path = wsMsg.path;
+    if (client.subscriptions.has(path)) {
+      sendToClient(client.ws, {
+        path,
+        error: { code: 'ALREADY_SUBSCRIBED', message: 'Already subscribed to this path' },
+      });
+      return;
+    }
+    const matched = matchRoute(routes, 'GET', path);
+    if (!matched) {
+      sendToClient(client.ws, {
+        path,
+        error: { code: 'NOT_FOUND', message: `No GET route matches ${path}` },
+        status: 404,
+      });
+      return;
+    }
+    const { route, params } = matched;
+    if (!route.wsEnabled || typeof route.config.ws !== 'function') {
+      sendToClient(client.ws, {
+        path,
+        error: {
+          code: 'WS_NOT_SUPPORTED',
+          message: 'This route does not support WebSocket subscriptions',
+        },
+        status: 400,
+      });
+      return;
+    }
+    const reqInfo = buildRequestInfo(client, { ...wsMsg, method: 'GET' }, params);
+    const ctx = buildCtx(reqInfo);
+    let cleanup;
+    try {
+      cleanup = await route.config.ws(ctx);
+    } catch (err) {
+      log.error(`WS subscribe error for ${path}`, {
+        error: toErrorMessage(err),
+      });
+      sendToClient(client.ws, {
+        path,
+        error: { code: 'SUBSCRIBE_ERROR', message: 'Subscription setup failed' },
+        status: 500,
+      });
+      return;
+    }
+    client.subscriptions.set(path, {
+      routePattern: route.pattern,
+      cleanup: cleanup ?? void 0,
+      req: reqInfo,
+    });
+    const response = await runHandler(route, reqInfo);
+    sendToClient(client.ws, { path, ...response, id: wsMsg.id });
+  }
+  async function handleUnsubscribe(client, wsMsg) {
+    const path = wsMsg.path;
+    const sub = client.subscriptions.get(path);
+    if (!sub) {
+      sendToClient(client.ws, {
+        path,
+        error: { code: 'NOT_SUBSCRIBED', message: 'Not subscribed to this path' },
+      });
+      return;
+    }
+    if (sub.cleanup) {
+      try {
+        await sub.cleanup();
+      } catch (err) {
+        log.error(`WS unsubscribe cleanup error for ${path}`, {
+          error: toErrorMessage(err),
+        });
+      }
+    }
+    client.subscriptions.delete(path);
+  }
+  async function handleMethodCall(client, wsMsg) {
+    const { path, method } = wsMsg;
+    const matched = matchRoute(routes, method, path);
+    if (!matched) {
+      sendToClient(client.ws, {
+        path,
+        error: { code: 'NOT_FOUND', message: `No ${method} route matches ${path}` },
+        status: 404,
+        id: wsMsg.id,
+      });
+      return;
+    }
+    const { route, params } = matched;
+    const reqInfo = buildRequestInfo(client, wsMsg, params);
+    const response = await runHandler(route, reqInfo);
+    sendToClient(client.ws, { path, ...response, id: wsMsg.id });
+    if (!response.error) {
+      const msg = { path, data: response.data, status: response.status };
+      for (const c of clients.values()) {
+        if (c !== client && c.subscriptions.has(path)) {
+          sendToClient(c.ws, msg);
+        }
+      }
+    }
+  }
+  async function cleanupClient(client) {
+    for (const [path, sub] of client.subscriptions) {
+      if (sub.cleanup) {
+        try {
+          await sub.cleanup();
+        } catch (err) {
+          log.error(`WS cleanup error for ${path}`, {
+            error: toErrorMessage(err),
+          });
+        }
+      }
+    }
+    client.subscriptions.clear();
+    clients.delete(client.ws);
+    clientsBySocketId.delete(client.socketId);
+  }
+  server.on('upgrade', async (req, socket, head) => {
+    const url = new URL(req.url ?? '/', `http://${req.headers.host ?? 'localhost'}`);
+    if (url.pathname !== wsPath) return;
+    const cookies = parseCookiesFromHeader(req.headers.cookie ?? '');
+    const session = await resolveSession(cookies, sessionConfig);
+    const headers = flattenHeaders(req.headers);
+    wss.handleUpgrade(req, socket, head, (ws) => {
+      wss.emit('connection', ws, { session, headers, cookies });
+    });
+  });
+  wss.on('connection', (ws, extra) => {
+    const socketId = randomUUID();
+    const client = {
+      ws,
+      socketId,
+      subscriptions: new Map(),
+      session: extra.session,
+      headers: extra.headers,
+      cookies: extra.cookies,
+      isAlive: true,
+    };
+    clients.set(ws, client);
+    clientsBySocketId.set(socketId, client);
+    sendToClient(ws, { path: wsPath, data: { socketId }, status: 200 });
+    ws.on('pong', () => {
+      client.isAlive = true;
+    });
+    ws.on('message', async (raw) => {
+      let parsed;
+      try {
+        parsed = JSON.parse(typeof raw === 'string' ? raw : raw.toString('utf-8'));
+      } catch {
+        sendToClient(ws, { path: '', error: { code: 'INVALID_JSON', message: 'Invalid JSON' } });
+        return;
+      }
+      if (!parsed.path || !parsed.method) {
+        sendToClient(ws, {
+          path: '',
+          error: {
+            code: 'INVALID_MESSAGE',
+            message: 'Message must have "path" and "method" fields',
+          },
+        });
+        return;
+      }
+      const method = parsed.method.toUpperCase();
+      if (method === 'SUBSCRIBE') {
+        await handleSubscribe(client, { ...parsed, method });
+      } else if (method === 'UNSUBSCRIBE') {
+        await handleUnsubscribe(client, { ...parsed, method });
+      } else if (['GET', 'POST', 'PUT', 'PATCH', 'DELETE'].includes(method)) {
+        await handleMethodCall(client, { ...parsed, method });
+      } else {
+        sendToClient(ws, {
+          path: parsed.path,
+          error: { code: 'INVALID_METHOD', message: `Unsupported method: ${method}` },
+        });
+      }
+    });
+    ws.on('close', () => {
+      cleanupClient(client).catch((err) => {
+        log.error('WS client cleanup error on disconnect', { error: String(err) });
+      });
+    });
+    ws.on('error', (err) => {
+      log.error('WebSocket connection error', { error: String(err), socketId });
+    });
+  });
+  registerWsServer({ sendToSocket, broadcastToPath });
+  const pingIntervalMs = options.pingIntervalMs ?? 3e4;
+  let pingInterval;
+  if (pingIntervalMs > 0) {
+    pingInterval = setInterval(() => {
+      for (const client of clients.values()) {
+        if (!client.isAlive) {
+          log.debug('Terminating unresponsive WebSocket client', { socketId: client.socketId });
+          client.ws.terminate();
+          continue;
+        }
+        client.isAlive = false;
+        client.ws.ping();
+      }
+    }, pingIntervalMs);
+  }
+  return {
+    wss,
+    sendToSocket,
+    broadcastToPath,
+    close() {
+      unregisterWsServer();
+      if (pingInterval) clearInterval(pingInterval);
+      const cleanupPromises = [];
+      for (const client of clients.values()) {
+        cleanupPromises.push(cleanupClient(client));
+        client.ws.close(1001, 'Server shutting down');
+      }
+      Promise.allSettled(cleanupPromises).then(() => {
+        wss.close();
+      });
+    },
+  };
+}
+export { createRealtimeServer };

package/server/ws/registry.js

@@ -0,0 +1,17 @@
+const GLOBAL_KEY = Symbol.for('arcway.wsRegistry');
+function registerWsServer(registry) {
+  globalThis[GLOBAL_KEY] = registry;
+}
+function unregisterWsServer() {
+  delete globalThis[GLOBAL_KEY];
+}
+function getRegistry() {
+  return globalThis[GLOBAL_KEY];
+}
+function wsSendToSocket(socketId, path, response) {
+  getRegistry()?.sendToSocket(socketId, path, response);
+}
+function wsBroadcastToPath(path, response) {
+  getRegistry()?.broadcastToPath(path, response);
+}
+export { registerWsServer, unregisterWsServer, wsBroadcastToPath, wsSendToSocket };

package/server/ws/server.js

@@ -0,0 +1,152 @@
+import { WebSocketServer, WebSocket } from 'ws';
+import { randomUUID } from 'node:crypto';
+import { parseCookiesFromHeader, resolveSession, flattenHeaders } from '../session/helpers.js';
+function createWebSocketServer(options) {
+  const {
+    server,
+    onConnect,
+    onClose,
+    messages,
+    session: sessionConfig,
+    log,
+    path: wsPath = '/ws',
+  } = options;
+  const wss = new WebSocketServer({ noServer: true });
+  const clients = new Map();
+  function publish(topic, data) {
+    const payload = JSON.stringify(data);
+    for (const client of clients.values()) {
+      if (client.topics.has(topic) && client.ws.readyState === WebSocket.OPEN) {
+        client.ws.send(payload);
+      }
+    }
+  }
+  function broadcast(data) {
+    const payload = JSON.stringify(data);
+    for (const client of clients.values()) {
+      if (client.ws.readyState === WebSocket.OPEN) {
+        client.ws.send(payload);
+      }
+    }
+  }
+  server.on('upgrade', async (req, socket, head) => {
+    const url = new URL(req.url ?? '/', `http://${req.headers.host ?? 'localhost'}`);
+    if (url.pathname !== wsPath) {
+      return;
+    }
+    const headers = flattenHeaders(req.headers);
+    const cookies = parseCookiesFromHeader(req.headers.cookie ?? '');
+    const session = await resolveSession(cookies, sessionConfig);
+    wss.handleUpgrade(req, socket, head, (ws) => {
+      wss.emit('connection', ws, req, { session, headers, cookies });
+    });
+  });
+  wss.on('connection', async (ws, _req, extra) => {
+    const connectionId = randomUUID();
+    const client = { ws, connectionId, topics: new Set() };
+    clients.set(ws, client);
+    const ctx = {
+      session: extra.session,
+      connectionId,
+      headers: extra.headers,
+      cookies: extra.cookies,
+      send: (data) => {
+        if (ws.readyState === WebSocket.OPEN) {
+          ws.send(JSON.stringify(data));
+        }
+      },
+      close: (code, reason) => {
+        ws.close(code, reason);
+      },
+      subscribe: (topic) => {
+        client.topics.add(topic);
+      },
+      unsubscribe: (topic) => {
+        client.topics.delete(topic);
+      },
+      publish,
+      broadcast,
+      log,
+    };
+    for (const handler of onConnect) {
+      try {
+        const result = handler.fn(ctx);
+        const resolved = result instanceof Promise ? await result : result;
+        if (resolved && typeof resolved === 'object' && 'reject' in resolved && resolved.reject) {
+          const code = resolved.code ?? 4403;
+          const reason = resolved.reason ?? 'Connection rejected';
+          log.info(`WebSocket connection rejected by ${'ws'}`, { connectionId, code, reason });
+          ws.close(code, reason);
+          clients.delete(ws);
+          return;
+        }
+      } catch (err) {
+        log.error(`WebSocket onConnect error (${'ws'})`, { error: String(err) });
+      }
+    }
+    ws.on('message', async (raw) => {
+      let parsed;
+      try {
+        parsed = JSON.parse(typeof raw === 'string' ? raw : raw.toString('utf-8'));
+      } catch {
+        ctx.send({ type: 'error', data: { message: 'Invalid JSON' } });
+        return;
+      }
+      const msgType = parsed?.type;
+      if (typeof msgType !== 'string') {
+        ctx.send({ type: 'error', data: { message: 'Message must have a "type" field' } });
+        return;
+      }
+      if (msgType === 'subscribe' && typeof parsed.topic === 'string') {
+        client.topics.add(parsed.topic);
+        return;
+      }
+      if (msgType === 'unsubscribe' && typeof parsed.topic === 'string') {
+        client.topics.delete(parsed.topic);
+        return;
+      }
+      const handler = messages.get(msgType);
+      if (!handler) {
+        ctx.send({ type: 'error', data: { message: `Unknown message type: "${msgType}"` } });
+        return;
+      }
+      try {
+        await handler.fn(ctx, parsed.data);
+      } catch (err) {
+        log.error(`WebSocket message handler error (${'ws'}/${msgType})`, {
+          error: String(err),
+        });
+        ctx.send({ type: 'error', data: { message: 'Internal server error' } });
+      }
+    });
+    ws.on('close', (code, reason) => {
+      const reasonStr = reason.toString('utf-8');
+      for (const handler of onClose) {
+        try {
+          const result = handler.fn(ctx, code, reasonStr);
+          if (result instanceof Promise) {
+            result.catch((err) =>
+              log.error(`WebSocket onClose error (${'ws'})`, { error: String(err) }),
+            );
+          }
+        } catch (err) {
+          log.error(`WebSocket onClose error (${'ws'})`, { error: String(err) });
+        }
+      }
+      clients.delete(ws);
+    });
+    ws.on('error', (err) => {
+      log.error('WebSocket connection error', { error: String(err), connectionId });
+    });
+  });
+  return {
+    wss,
+    close: () => {
+      for (const client of clients.values()) {
+        client.ws.close(1001, 'Server shutting down');
+      }
+      wss.close();
+    },
+  };
+}
+export { createWebSocketServer };