arcway 0.1.0

package/server/testing/index.js

@@ -0,0 +1,263 @@
+import knex from 'knex';
+import { MigrationSource } from '../db/index.js';
+import path from 'node:path';
+function createEventStub() {
+  const calls = [];
+  return {
+    calls,
+    emit: async (eventName, payload) => {
+      calls.push({ event: eventName, payload });
+    },
+  };
+}
+function createQueueStub() {
+  const pushed = [];
+  const removed = [];
+  const items = [];
+  let nextId = 1;
+  return {
+    pushed,
+    removed,
+    async push(topic, item) {
+      pushed.push({ topic, item });
+      items.push({ id: nextId++, topic, data: item });
+    },
+    async pop(topic, count = 1) {
+      const matching = items.filter((i) => i.topic === topic).slice(0, count);
+      for (const m of matching) {
+        items.splice(items.indexOf(m), 1);
+      }
+      return matching.map((m) => ({ id: m.id, data: m.data }));
+    },
+    async remove(ids) {
+      removed.push(...ids);
+    },
+  };
+}
+function createCacheStub() {
+  const store = new Map();
+  const stub = {
+    store,
+    async get(key) {
+      return store.get(key) ?? null;
+    },
+    async set(key, value) {
+      store.set(key, value);
+    },
+    async delete(key) {
+      store.delete(key);
+    },
+    async wrap(key, fn, _ttlMs) {
+      const cached = store.get(key);
+      if (cached !== void 0) return cached;
+      const value = await fn();
+      store.set(key, value);
+      return value;
+    },
+  };
+  return stub;
+}
+function createFilesStub() {
+  const store = new Map();
+  return {
+    store,
+    async write(filePath, data) {
+      store.set(filePath, Buffer.isBuffer(data) ? data : Buffer.from(data));
+    },
+    async read(filePath) {
+      return store.get(filePath) ?? null;
+    },
+    async delete(filePath) {
+      store.delete(filePath);
+    },
+    async list(prefix) {
+      const keys = Array.from(store.keys());
+      if (!prefix) return keys;
+      return keys.filter((k) => k.startsWith(prefix));
+    },
+    async exists(filePath) {
+      return store.has(filePath);
+    },
+  };
+}
+function createMailStub() {
+  const sent = [];
+  const queued = [];
+  return {
+    sent,
+    queued,
+    async send(message) {
+      sent.push(message);
+      const recipients = Array.isArray(message.to) ? message.to : [message.to];
+      return {
+        accepted: recipients,
+        rejected: [],
+        messageId: `test-${Date.now()}-${Math.random().toString(36).slice(2, 8)}@local`,
+      };
+    },
+    async queue(message) {
+      queued.push({ message });
+    },
+  };
+}
+function createLoggerStub() {
+  const messages = [];
+  return {
+    messages,
+    debug(message, data) {
+      messages.push({ level: 'debug', message, data });
+    },
+    info(message, data) {
+      messages.push({ level: 'info', message, data });
+    },
+    warn(message, data) {
+      messages.push({ level: 'warn', message, data });
+    },
+    error(message, data) {
+      messages.push({ level: 'error', message, data });
+    },
+  };
+}
+async function createTestContext(domainName, options) {
+  const resolvedClient = options?.dbClient ?? 'better-sqlite3';
+  const db = knex({
+    client: resolvedClient,
+    connection: options?.dbConnection ?? { filename: ':memory:' },
+    useNullAsDefault: true,
+  });
+  if (options?.rootDir) {
+    const migrationsDir = path.join(options.rootDir, 'migrations');
+    await db.migrate.latest({ migrationSource: new MigrationSource(migrationsDir) });
+  } else if (options?.migrationsDir) {
+    await db.migrate.latest({
+      migrationSource: new MigrationSource(options.migrationsDir),
+    });
+  }
+  const scopedDb = db;
+  const ctx = {
+    domain: domainName,
+    db: scopedDb,
+    events: options?.events ?? createEventStub(),
+    queue: options?.queue ?? createQueueStub(),
+    cache: options?.cache ?? createCacheStub(),
+    files: options?.files ?? createFilesStub(),
+    mail: options?.mail ?? createMailStub(),
+    log: options?.log ?? createLoggerStub(),
+  };
+  return {
+    ctx,
+    db,
+    cleanup: async () => {
+      await db.destroy();
+    },
+  };
+}
+import http from 'node:http';
+import boot from '../boot/index.js';
+import { buildContext } from '../context.js';
+async function testBoot(options) {
+  const configOverrides = {
+    database: { client: 'better-sqlite3', connection: { filename: ':memory:' } },
+    server: { port: 0 },
+    logger: { level: 'error' },
+    mcp: { enabled: false },
+    ...options.configOverrides,
+  };
+  const app = await boot({
+    mode: 'development',
+    rootDir: options.rootDir,
+    configOverrides,
+  });
+  const baseUrl = `http://127.0.0.1:${app.port}`;
+  const appContext = {
+    db: app.db,
+    events: app.eventBus,
+    queue: { push: async () => {}, pop: async () => [], remove: async () => {} },
+    cache: {
+      get: async () => null,
+      set: async () => {},
+      delete: async () => {},
+      wrap: async (_k, fn) => fn(),
+    },
+    files: {
+      write: async () => {},
+      read: async () => null,
+      delete: async () => {},
+      list: async () => [],
+      exists: async () => false,
+    },
+    mail: { send: async () => ({ accepted: [], rejected: [] }), queue: async () => {} },
+    log: { debug() {}, info() {}, warn() {}, error() {} },
+  };
+  async function request(method, urlPath, opts) {
+    const url = new URL(urlPath, baseUrl);
+    const reqHeaders = {
+      ...opts?.headers,
+    };
+    let bodyStr;
+    if (opts?.body !== void 0) {
+      bodyStr = JSON.stringify(opts.body);
+      reqHeaders['content-type'] = reqHeaders['content-type'] ?? 'application/json';
+      reqHeaders['content-length'] = String(Buffer.byteLength(bodyStr));
+    }
+    return new Promise((resolve, reject) => {
+      const req = http.request(
+        url,
+        { method: method.toUpperCase(), headers: reqHeaders },
+        (res) => {
+          const chunks = [];
+          res.on('data', (chunk) => chunks.push(chunk));
+          res.on('end', () => {
+            const text = Buffer.concat(chunks).toString('utf-8');
+            let body = text;
+            const ct = res.headers['content-type'] ?? '';
+            if (ct.includes('application/json')) {
+              try {
+                body = JSON.parse(text);
+              } catch {}
+            }
+            const headers = {};
+            for (const [key, value] of Object.entries(res.headers)) {
+              if (typeof value === 'string') headers[key] = value;
+              else if (Array.isArray(value)) headers[key] = value.join(', ');
+            }
+            resolve({
+              status: res.statusCode ?? 0,
+              headers,
+              body,
+              text,
+            });
+          });
+          res.on('error', reject);
+        },
+      );
+      req.on('error', reject);
+      if (bodyStr) req.write(bodyStr);
+      req.end();
+    });
+  }
+  return {
+    db: app.db,
+    port: app.port,
+    app,
+    request,
+    run: async (fn) => fn(buildContext(appContext, {})),
+    shutdown: app.shutdown,
+  };
+}
+const Arcway = {
+  /** Boot an Arcway application for integration testing. */
+  test: testBoot,
+};
+const Solo = Arcway;
+export {
+  Arcway,
+  Solo,
+  createCacheStub,
+  createEventStub,
+  createFilesStub,
+  createLoggerStub,
+  createMailStub,
+  createQueueStub,
+  createTestContext,
+};

package/server/validation.js

@@ -0,0 +1,41 @@
+import { ArkErrors } from 'arktype';
+function isArkErrors(value) {
+  return (
+    Array.isArray(value) && typeof value.summary === 'string' && typeof value.throw === 'function'
+  );
+}
+function validate(schema, data) {
+  const result = schema(data);
+  if (isArkErrors(result)) {
+    const fieldErrors = {};
+    for (const err of result) {
+      const key = err.path.join('.') || '_root';
+      if (!fieldErrors[key]) fieldErrors[key] = [];
+      fieldErrors[key].push(err.message);
+    }
+    return { success: false, errors: { fieldErrors } };
+  }
+  return { success: true, data: result };
+}
+/**
+ * Validate query and body against a schema object { query?, body? }.
+ * Returns { error } on failure, or { query, body } with coerced values on success.
+ */
+function validateRequestSchema(schema, query, body) {
+  if (schema?.query) {
+    const result = validate(schema.query, query);
+    if (!result.success) {
+      return { error: { code: 'VALIDATION_ERROR', message: 'Invalid query parameters', details: result.errors } };
+    }
+    query = result.data;
+  }
+  if (schema?.body) {
+    const result = validate(schema.body, body);
+    if (!result.success) {
+      return { error: { code: 'VALIDATION_ERROR', message: 'Invalid request body', details: result.errors } };
+    }
+    body = result.data;
+  }
+  return { query, body };
+}
+export { ArkErrors, validate, validateRequestSchema };

package/server/watcher.js

@@ -0,0 +1,34 @@
+import { watch } from 'chokidar';
+import path from 'node:path';
+function startWatcher(options) {
+  const dirs = options.dirs ?? ['api', 'lib', 'listeners', 'jobs'];
+  const extensions = new Set(options.extensions ?? ['.js']);
+  const debounceMs = options.debounceMs ?? 300;
+  const watchPaths = dirs.map((dir) => path.join(options.rootDir, dir));
+  let debounceTimer = null;
+  let pendingFile = null;
+  const watcher = watch(watchPaths, {
+    ignoreInitial: true,
+    persistent: true,
+  });
+  if (options.onReady) {
+    watcher.once('ready', options.onReady);
+  }
+  watcher.on('all', (_event, filePath) => {
+    const ext = path.extname(filePath);
+    if (!extensions.has(ext)) return;
+    pendingFile = filePath;
+    if (debounceTimer) clearTimeout(debounceTimer);
+    debounceTimer = setTimeout(() => {
+      if (pendingFile) {
+        options.onChange(pendingFile);
+        pendingFile = null;
+      }
+    }, debounceMs);
+  });
+  return () => {
+    if (debounceTimer) clearTimeout(debounceTimer);
+    watcher.close();
+  };
+}
+export { startWatcher };

package/server/web-server.js

@@ -0,0 +1,231 @@
+import { randomUUID } from 'node:crypto';
+import { createHttpServer, listen, closeServer } from './server.js';
+import { buildCorsHeaders, buildPreflightHeaders } from './router/cors.js';
+import { parseCookies, resolveSession, flattenHeaders } from './session/helpers.js';
+import { sealSession, buildSessionSetCookie, buildSessionClearCookie } from './session/index.js';
+import { ErrorCodes } from './constants.js';
+import { toErrorMessage } from './helpers.js';
+
+function readBody(req, maxBodySize) {
+  return new Promise((resolve, reject) => {
+    const chunks = [];
+    let totalBytes = 0;
+    function cleanup() {
+      req.removeListener('data', onData);
+      req.removeListener('end', onEnd);
+      req.removeListener('error', onError);
+    }
+    function onData(chunk) {
+      totalBytes += chunk.length;
+      if (totalBytes > maxBodySize) {
+        cleanup();
+        req.destroy();
+        reject(new Error(ErrorCodes.BODY_TOO_LARGE));
+        return;
+      }
+      chunks.push(chunk);
+    }
+    function onEnd() {
+      cleanup();
+      resolve(Buffer.concat(chunks).toString('utf-8'));
+    }
+    function onError(err) {
+      cleanup();
+      reject(err);
+    }
+    req.on('data', onData);
+    req.on('end', onEnd);
+    req.on('error', onError);
+  });
+}
+
+function parseQuery(url) {
+  const idx = url.indexOf('?');
+  if (idx === -1) return {};
+  const params = new URLSearchParams(url.slice(idx + 1));
+  const result = {};
+  for (const [key, value] of params) {
+    result[key] = value;
+  }
+  return result;
+}
+
+class WebServer {
+  config;
+  log;
+  handlers = [];
+  server = null;
+  port = 0;
+
+  constructor(config, { log } = {}) {
+    this.config = config;
+    this.log = log;
+  }
+
+  use(handler, prefix) {
+    this.handlers.push({ prefix: prefix ?? null, handler });
+  }
+
+  async listen() {
+    const { config, log } = this;
+    const host = config.server.host;
+    const port = config.server.port;
+    const corsConfig = config.server?.cors;
+    const sessionConfig = config.session;
+    const maxBodySize = config.server?.maxBodySize ?? 1024 * 1024;
+
+    if (sessionConfig) {
+      log.info(`Session enabled: cookie="${sessionConfig.cookieName}", ttl=${sessionConfig.ttl}s`);
+      if (corsConfig && corsConfig.origin === '*' && !corsConfig.credentials) {
+        log.warn(
+          'CORS is set to allow all origins (origin: "*") but session cookies are enabled. Browsers will not send cookies with wildcard CORS. Set cors.origin to your frontend URL and cors.credentials to true, or use cors: { origin: "http://localhost:5173", credentials: true }.',
+        );
+      }
+    }
+
+    const requestHandler = (req, res) => {
+      // ── Request ID ──
+      const incomingId = req.headers['x-request-id'];
+      const requestId = (Array.isArray(incomingId) ? incomingId[0] : incomingId) ?? randomUUID();
+      res.setHeader('X-Request-Id', requestId);
+      req.requestId = requestId;
+
+      // ── CORS ──
+      if (corsConfig) {
+        const requestOrigin = req.headers['origin'];
+        const corsHeaders = buildCorsHeaders(corsConfig, requestOrigin);
+        for (const [key, value] of Object.entries(corsHeaders)) {
+          res.setHeader(key, value);
+        }
+      }
+      if (req.method === 'OPTIONS' && corsConfig) {
+        const preflightHeaders = buildPreflightHeaders(corsConfig);
+        for (const [key, value] of Object.entries(preflightHeaders)) {
+          res.setHeader(key, value);
+        }
+        res.writeHead(204);
+        res.end();
+        return;
+      }
+
+      // ── Parse request ──
+      this._enrichRequest(req, sessionConfig, maxBodySize)
+        .then(() => this._dispatch(req, res))
+        .catch((err) => {
+          if (res.headersSent) return;
+          const msg = toErrorMessage(err);
+          if (msg === ErrorCodes.BODY_TOO_LARGE) {
+            res.writeHead(413, { 'Content-Type': 'application/json' });
+            res.end(JSON.stringify({ error: { code: ErrorCodes.BODY_TOO_LARGE, message: 'Request body exceeds maximum size' } }));
+            return;
+          }
+          if (msg === ErrorCodes.INVALID_JSON) {
+            res.writeHead(400, { 'Content-Type': 'application/json' });
+            res.end(JSON.stringify({ error: { code: ErrorCodes.INVALID_JSON, message: 'Request body is not valid JSON' } }));
+            return;
+          }
+          log.error('Unhandled error in request handler', { error: msg, requestId });
+          res.writeHead(500, { 'Content-Type': 'application/json' });
+          res.end(JSON.stringify({ error: { code: 'INTERNAL_ERROR', message: 'An unexpected error occurred' } }));
+        });
+    };
+
+    this.server = createHttpServer(requestHandler);
+
+    // ── WebSocket upgrade ──
+    this.server.on('upgrade', async (req, socket, head) => {
+      const url = req.url ?? '/';
+      const cookies = parseCookies(req);
+      const session = sessionConfig
+        ? await resolveSession(cookies, sessionConfig)
+        : null;
+      req.cookies = cookies;
+      req.session = session;
+      req.flatHeaders = flattenHeaders(req.headers);
+
+      for (const { prefix, handler } of this.handlers) {
+        if (prefix && !url.startsWith(prefix)) continue;
+        if (typeof handler.handleUpgrade === 'function') {
+          handler.handleUpgrade(req, socket, head, session);
+          return;
+        }
+      }
+      socket.destroy();
+    });
+
+    log.info('Starting HTTP server...');
+    await listen(this.server, port, host);
+    this.port = this.server.address().port;
+    log.info(`Listening on ${host}:${this.port}`);
+  }
+
+  async _enrichRequest(req, sessionConfig, maxBodySize) {
+    const method = req.method ?? 'GET';
+
+    // Cookies + session
+    req.cookies = parseCookies(req);
+    req.session = sessionConfig
+      ? await resolveSession(req.cookies, sessionConfig)
+      : null;
+
+    // Headers (flattened for consistent access)
+    req.flatHeaders = flattenHeaders(req.headers);
+
+    // Query string
+    req.query = parseQuery(req.url ?? '/');
+
+    // Body (POST/PUT/PATCH only)
+    if (method === 'POST' || method === 'PUT' || method === 'PATCH') {
+      const rawBody = await readBody(req, maxBodySize);
+      if (rawBody.length > 0) {
+        const contentType = req.headers['content-type'] ?? '';
+        if (contentType.includes('application/json')) {
+          try {
+            req.body = JSON.parse(rawBody);
+          } catch {
+            throw new Error(ErrorCodes.INVALID_JSON);
+          }
+        } else {
+          req.body = rawBody;
+        }
+      }
+    }
+  }
+
+  async _dispatch(req, res) {
+    const url = req.url ?? '/';
+    for (const { prefix, handler } of this.handlers) {
+      if (prefix && !url.startsWith(prefix)) continue;
+      const handled = typeof handler.handle === 'function'
+        ? await handler.handle(req, res)
+        : await handler(req, res);
+      if (handled) return;
+    }
+    res.writeHead(404, { 'Content-Type': 'application/json' });
+    res.end(JSON.stringify({ error: { code: 'NOT_FOUND', message: 'Not found' } }));
+  }
+
+  async close() {
+    // Close WS handlers before shutting down the HTTP server
+    for (const { handler } of this.handlers) {
+      if (typeof handler.handleUpgrade === 'function' && typeof handler.close === 'function') {
+        try { handler.close(); } catch {}
+      }
+    }
+    if (this.server) {
+      const shutdownTimeoutMs = this.config.server?.shutdownTimeoutMs ?? 5000;
+      await Promise.race([
+        closeServer(this.server),
+        new Promise((resolve) =>
+          setTimeout(() => {
+            this.log.warn(`Shutdown timeout (${shutdownTimeoutMs}ms) exceeded, forcing close`);
+            resolve();
+          }, shutdownTimeoutMs),
+        ),
+      ]);
+      this.log.info('HTTP server closed');
+    }
+  }
+}
+
+export default WebServer;

package/server/ws/discovery.js

@@ -0,0 +1,54 @@
+import path from 'node:path';
+import fs from 'node:fs';
+import { loadModule } from '../module-loader.js';
+async function discoverWebSocketHandlers(rootDir) {
+  const result = [];
+  const candidate = path.join(rootDir, 'ws.js');
+  if (!fs.existsSync(candidate)) return result;
+  const mod = await loadModule(candidate, import.meta.url);
+  const handler = mod.default;
+  if (!handler || typeof handler !== 'object') {
+    throw new Error(`ws.js must export a default WebSocketHandler object, got ${typeof handler}`);
+  }
+  if (handler.onConnect && typeof handler.onConnect !== 'function') {
+    throw new Error('ws.js: onConnect must be a function');
+  }
+  if (handler.onClose && typeof handler.onClose !== 'function') {
+    throw new Error('ws.js: onClose must be a function');
+  }
+  if (handler.messages) {
+    if (typeof handler.messages !== 'object') {
+      throw new Error('ws.js: messages must be an object');
+    }
+    for (const [type, fn] of Object.entries(handler.messages)) {
+      if (typeof fn !== 'function') {
+        throw new Error(`ws.js: messages["${type}"] must be a function, got ${typeof fn}`);
+      }
+    }
+  }
+  result.push({ handler });
+  return result;
+}
+function mergeWebSocketHandlers(entries) {
+  const onConnect = [];
+  const onClose = [];
+  const messages = new Map();
+  for (const { handler } of entries) {
+    if (handler.onConnect) {
+      onConnect.push({ fn: handler.onConnect });
+    }
+    if (handler.onClose) {
+      onClose.push({ fn: handler.onClose });
+    }
+    if (handler.messages) {
+      for (const [type, fn] of Object.entries(handler.messages)) {
+        if (messages.has(type)) {
+          throw new Error(`WebSocket message type "${type}" is registered multiple times`);
+        }
+        messages.set(type, { fn });
+      }
+    }
+  }
+  return { onConnect, onClose, messages };
+}
+export { discoverWebSocketHandlers, mergeWebSocketHandlers };

package/server/ws/index.js

@@ -0,0 +1,14 @@
+import { discoverWebSocketHandlers, mergeWebSocketHandlers } from './discovery.js';
+import { createWebSocketServer } from './server.js';
+import { createRealtimeServer } from './realtime.js';
+import { WsRouter } from './ws-router.js';
+import { wsSendToSocket, wsBroadcastToPath } from './registry.js';
+export {
+  createRealtimeServer,
+  createWebSocketServer,
+  discoverWebSocketHandlers,
+  mergeWebSocketHandlers,
+  WsRouter,
+  wsBroadcastToPath,
+  wsSendToSocket,
+};