arcway 0.1.0

package/server/router/middleware.js

@@ -0,0 +1,91 @@
+import path from 'node:path';
+import { discoverModules } from '../discovery.js';
+import { validateRequestSchema } from '../validation.js';
+function isMiddlewareConfig(value) {
+  return (
+    typeof value === 'object' &&
+    value !== null &&
+    'handler' in value &&
+    typeof value.handler === 'function'
+  );
+}
+function wrapMiddlewareConfig(config) {
+  const { schema, handler } = config;
+  if (!schema) return handler;
+  return async (ctx) => {
+    const validated = validateRequestSchema(schema, ctx.req.query, ctx.req.body);
+    if (validated.error) {
+      return { status: 400, error: validated.error };
+    }
+    ctx.req.query = validated.query;
+    ctx.req.body = validated.body;
+    return handler(ctx);
+  };
+}
+async function discoverMiddleware(apiDir) {
+  const middleware = [];
+  const entries = await discoverModules(apiDir, {
+    recursive: true,
+    skipUnderscore: false,
+    filter: (name) => name === '_middleware.js',
+    label: 'middleware',
+  });
+  for (const { filePath, relativePath, module } of entries) {
+    const parts = relativePath.split(path.sep);
+    const dirParts = parts.slice(0, -1);
+    let pathPrefix = '/';
+    if (dirParts.length > 0) {
+      const converted = dirParts.map((p) => p.replace(/\[([^\]]+)\]/g, ':$1'));
+      pathPrefix = '/' + converted.join('/');
+    }
+    {
+      const exported = module.default;
+      if (!exported) {
+        throw new Error(
+          `Middleware file "${filePath}" must have a default export (MiddlewareConfig or array of MiddlewareConfig)`,
+        );
+      }
+      const items = Array.isArray(exported) ? exported : [exported];
+      const fns = [];
+      for (let i = 0; i < items.length; i++) {
+        const item = items[i];
+        if (isMiddlewareConfig(item)) {
+          fns.push(wrapMiddlewareConfig(item));
+        } else {
+          throw new Error(
+            `Middleware file "${filePath}" default export${items.length > 1 ? `[${i}]` : ''} must be a MiddlewareConfig object with a handler function. Got ${typeof item}.`,
+          );
+        }
+      }
+      middleware.push({ pathPrefix, fns });
+    }
+  }
+  middleware.sort((a, b) => a.pathPrefix.length - b.pathPrefix.length);
+  return middleware;
+}
+function getMiddlewareForRoute(allMiddleware, routePattern) {
+  const matching = [];
+  for (const mw of allMiddleware) {
+    if (mw.pathPrefix === '/') {
+      matching.push(...mw.fns);
+    } else if (routePattern === mw.pathPrefix || routePattern.startsWith(mw.pathPrefix + '/')) {
+      matching.push(...mw.fns);
+    }
+  }
+  return matching;
+}
+function buildMiddlewareChain(middlewareFns, handler) {
+  if (middlewareFns.length === 0) {
+    return async (ctx) => handler(ctx);
+  }
+  return async (ctx) => {
+    for (const mw of middlewareFns) {
+      const result = await mw(ctx);
+      if (result !== void 0 && result !== null) {
+        return result;
+      }
+    }
+    return handler(ctx);
+  };
+}
+export { buildMiddlewareChain, discoverMiddleware, getMiddlewareForRoute };

package/server/router/routes.js

@@ -0,0 +1,132 @@
+import { discoverModules } from '../discovery.js';
+const HTTP_METHODS = ['GET', 'POST', 'PUT', 'PATCH', 'DELETE'];
+function filePathToPattern(relativePath) {
+  let route = relativePath.replace(/\\/g, '/');
+  route = route.replace(/\.jsx?$/, '');
+  route = route.replace(/\[\[\.\.\.([^\]]+)\]\]/g, '*$1?');
+  route = route.replace(/\[\.\.\.([^\]]+)\]/g, '*$1');
+  route = route.replace(/\[([^\]]+)\]/g, ':$1');
+  route = route.replace(/\/index$/, '');
+  if (route === 'index') {
+    route = '';
+  }
+  return '/' + route;
+}
+function sortBySpecificity(items) {
+  items.sort((a, b) => {
+    const aCatchAll = a.catchAllParam ? 1 : 0;
+    const bCatchAll = b.catchAllParam ? 1 : 0;
+    if (aCatchAll !== bCatchAll) return aCatchAll - bCatchAll;
+    const aParams = a.paramNames.length;
+    const bParams = b.paramNames.length;
+    if (aParams !== bParams) return aParams - bParams;
+    return a.pattern.localeCompare(b.pattern);
+  });
+}
+function matchPattern(items, pathname) {
+  for (const item of items) {
+    const m = item.regex.exec(pathname);
+    if (!m) continue;
+    const params = {};
+    try {
+      for (let i = 0; i < item.paramNames.length; i++) {
+        const name = item.paramNames[i];
+        const raw = m[i + 1];
+        if (name === item.catchAllParam) {
+          params[name] = raw ? raw.split('/').map(decodeURIComponent) : [];
+        } else {
+          params[name] = decodeURIComponent(raw);
+        }
+      }
+    } catch {
+      continue;
+    }
+    return { match: item, params };
+  }
+  return null;
+}
+function compilePattern(pattern) {
+  const paramNames = [];
+  let catchAllParam;
+  let isOptionalCatchAll = false;
+  const regexStr = pattern.replace(
+    /\/:([^/]+)|\/\*(\w+)\?|\/\*(\w+)/g,
+    (match, singleParam, optCatchAll, reqCatchAll) => {
+      if (singleParam) {
+        paramNames.push(singleParam);
+        return '/([^/]+)';
+      }
+      if (optCatchAll) {
+        paramNames.push(optCatchAll);
+        catchAllParam = optCatchAll;
+        isOptionalCatchAll = true;
+        return '(?:/(.+))?';
+      }
+      if (reqCatchAll) {
+        paramNames.push(reqCatchAll);
+        catchAllParam = reqCatchAll;
+        return '/(.+)';
+      }
+      return match;
+    },
+  );
+  const regex = new RegExp(`^${regexStr}/?$`);
+  return { regex, paramNames, catchAllParam, isOptionalCatchAll };
+}
+async function discoverRoutes(apiDir) {
+  const entries = await discoverModules(apiDir, { recursive: true, label: 'route file' });
+  const routes = [];
+  for (const { filePath, relativePath, module } of entries) {
+    const urlPattern = filePathToPattern(relativePath);
+    const { regex, paramNames, catchAllParam } = compilePattern(urlPattern);
+    for (const method of HTTP_METHODS) {
+      const config = module[method];
+      if (!config) continue;
+      if (typeof config.handler !== 'function') {
+        throw new Error(
+          `Route ${method} ${urlPattern} (${filePath}) must export a handler function`,
+        );
+      }
+      routes.push({
+        method,
+        pattern: urlPattern,
+        regex,
+        paramNames,
+        ...(catchAllParam ? { catchAllParam } : {}),
+        config,
+        ...(method === 'GET' && typeof config.ws === 'function' ? { wsEnabled: true } : {}),
+      });
+    }
+  }
+  sortBySpecificity(routes);
+  return routes;
+}
+function matchRoute(routes, method, pathname) {
+  const upperMethod = method.toUpperCase();
+  const methodRoutes = routes.filter((r) => r.method === upperMethod);
+  const result = matchPattern(methodRoutes, pathname);
+  if (!result) return null;
+  return { route: result.match, params: result.params };
+}
+function matchRoutesByPath(routes, pathname) {
+  const matched = new Map();
+  let params = null;
+  for (const method of HTTP_METHODS) {
+    const result = matchRoute(routes, method, pathname);
+    if (result) {
+      matched.set(method, result.route);
+      if (!params) params = result.params;
+    }
+  }
+  if (matched.size === 0 || !params) return null;
+  return { routes: matched, params };
+}
+export {
+  compilePattern,
+  discoverRoutes,
+  filePathToPattern,
+  matchPattern,
+  matchRoute,
+  matchRoutesByPath,
+  sortBySpecificity,
+};

package/server/server.js

@@ -0,0 +1,35 @@
+import { createServer } from 'node:http';
+function createHttpServer(handler) {
+  const server = createServer(handler);
+  const connections = new Set();
+  server.on('connection', (socket) => {
+    connections.add(socket);
+    socket.once('close', () => connections.delete(socket));
+  });
+  server.__trackedConnections = connections;
+  return server;
+}
+function listen(server, port, host = '0.0.0.0') {
+  return new Promise((resolve, reject) => {
+    server.once('error', reject);
+    server.listen(port, host, () => {
+      server.removeListener('error', reject);
+      resolve();
+    });
+  });
+}
+function closeServer(server) {
+  return new Promise((resolve, reject) => {
+    server.close((err) => {
+      if (err) reject(err);
+      else resolve();
+    });
+    const connections = server.__trackedConnections;
+    if (connections) {
+      for (const socket of connections) {
+        socket.destroy();
+      }
+    }
+  });
+}
+export { closeServer, createHttpServer, listen };

package/server/session/helpers.js

@@ -0,0 +1,21 @@
+import { parse as parseCookieHeader } from 'cookie';
+import { unsealSession } from './index.js';
+function parseCookies(req) {
+  return req.headers['cookie'] ? parseCookieHeader(req.headers['cookie']) : {};
+}
+function parseCookiesFromHeader(cookieHeader) {
+  return cookieHeader ? parseCookieHeader(cookieHeader) : {};
+}
+async function resolveSession(cookies, sessionConfig) {
+  if (!sessionConfig) return {};
+  return unsealSession(cookies[sessionConfig.cookieName], sessionConfig);
+}
+function flattenHeaders(raw) {
+  const result = {};
+  for (const [key, value] of Object.entries(raw)) {
+    if (value === void 0) continue;
+    result[key] = Array.isArray(value) ? value.join(', ') : value;
+  }
+  return result;
+}
+export { flattenHeaders, parseCookies, parseCookiesFromHeader, resolveSession };

package/server/session/index.js

@@ -0,0 +1,89 @@
+import { sealData, unsealData } from 'iron-session';
+import { serialize as serializeCookie } from 'cookie';
+import { SESSION_COOKIE_MAX_AGE_SKEW } from '../constants.js';
+import { toErrorMessage } from '../helpers.js';
+const MIN_PASSWORD_LENGTH = 32;
+function resolveSessionConfig(config, mode) {
+  if (!config.password) {
+    throw new Error(
+      `Session "password" is required but was not provided (got ${config.password === void 0 ? 'undefined' : String(config.password)}). Set a password of at least 32 characters, e.g. via SESSION_SECRET env variable.`,
+    );
+  }
+  if (typeof config.password === 'string') {
+    if (config.password.length < MIN_PASSWORD_LENGTH) {
+      throw new Error(
+        `Session password must be at least ${MIN_PASSWORD_LENGTH} characters (got ${config.password.length}). Short passwords produce weak encryption.`,
+      );
+    }
+  } else if (typeof config.password === 'object') {
+    for (const [id, pw] of Object.entries(config.password)) {
+      if (typeof pw === 'string' && pw.length < MIN_PASSWORD_LENGTH) {
+        throw new Error(
+          `Session password id=${id} must be at least ${MIN_PASSWORD_LENGTH} characters (got ${pw.length}). Short passwords produce weak encryption.`,
+        );
+      }
+    }
+  }
+  return {
+    password: config.password,
+    cookieName: config.cookieName ?? 'arcway.session',
+    ttl: config.ttl ?? 14 * 24 * 3600,
+    cookie: {
+      httpOnly: config.cookie?.httpOnly ?? true,
+      secure: config.cookie?.secure ?? mode === 'production',
+      sameSite: config.cookie?.sameSite ?? 'lax',
+      path: config.cookie?.path ?? '/',
+      domain: config.cookie?.domain,
+    },
+  };
+}
+async function unsealSession(cookieValue, config) {
+  if (!cookieValue) return {};
+  try {
+    const data = await unsealData(cookieValue, {
+      password: config.password,
+      ttl: config.ttl,
+    });
+    return data && typeof data === 'object' ? data : {};
+  } catch (err) {
+    if (process.env.NODE_ENV !== 'production') {
+      const reason = toErrorMessage(err);
+      console.warn(`[arcway] Failed to unseal session cookie: ${reason}`);
+    }
+    return {};
+  }
+}
+async function sealSession(data, config) {
+  return sealData(data, {
+    password: config.password,
+    ttl: config.ttl,
+  });
+}
+function buildSessionSetCookie(sealedValue, config) {
+  const maxAge = (config.ttl === 0 ? 2147483647 : config.ttl) - SESSION_COOKIE_MAX_AGE_SKEW;
+  return serializeCookie(config.cookieName, sealedValue, {
+    httpOnly: config.cookie.httpOnly,
+    secure: config.cookie.secure,
+    sameSite: config.cookie.sameSite,
+    path: config.cookie.path,
+    domain: config.cookie.domain,
+    maxAge,
+  });
+}
+function buildSessionClearCookie(config) {
+  return serializeCookie(config.cookieName, '', {
+    httpOnly: config.cookie.httpOnly,
+    secure: config.cookie.secure,
+    sameSite: config.cookie.sameSite,
+    path: config.cookie.path,
+    domain: config.cookie.domain,
+    maxAge: 0,
+  });
+}
+export {
+  buildSessionClearCookie,
+  buildSessionSetCookie,
+  resolveSessionConfig,
+  sealSession,
+  unsealSession,
+};

package/server/static/index.js

@@ -0,0 +1,36 @@
+import path from 'node:path';
+import fs from 'node:fs';
+import { serveStaticAsset, servePublicFile } from '../pages/static.js';
+
+class StaticRouter {
+  outDir;
+  publicDir;
+  hasPublicDir;
+
+  constructor({ outDir, publicDir }) {
+    this.outDir = outDir;
+    this.publicDir = publicDir;
+    this.hasPublicDir = publicDir ? fs.existsSync(publicDir) : false;
+  }
+
+  handle(req, res) {
+    const method = req.method ?? 'GET';
+    if (method !== 'GET') return false;
+
+    const pathname = (req.url ?? '/').split('?')[0];
+
+    // Built bundles: /static/client/*
+    if (pathname.startsWith('/static/client/')) {
+      return serveStaticAsset(pathname, res, this.outDir);
+    }
+
+    // Public files: /* (fallback)
+    if (this.hasPublicDir) {
+      return servePublicFile(pathname, res, this.publicDir);
+    }
+
+    return false;
+  }
+}
+
+export { StaticRouter };

package/server/system-jobs/index.js

@@ -0,0 +1,50 @@
+const SYSTEM_JOB_DOMAIN = '__system';
+const systemJobRegistry = [
+  // Future system jobs are added here. Examples:
+  //
+  // {
+  //   definition: { name: 'process-mail', handler: processMailHandler, schedule: '* * * * *' },
+  //   shouldRegister: (config) => !!config.mail,
+  //   description: 'Process inbound email via IMAP polling',
+  // },
+];
+function getApplicableSystemJobs(config) {
+  return systemJobRegistry.filter((entry) => entry.shouldRegister(config));
+}
+function registerSystemJobs(config, queue, store) {
+  const applicable = getApplicableSystemJobs(config);
+  const registered = [];
+  for (const entry of applicable) {
+    queue.register(SYSTEM_JOB_DOMAIN, entry.definition, store);
+    registered.push({
+      domainName: SYSTEM_JOB_DOMAIN,
+      jobName: entry.definition.name,
+      schedule: entry.definition.schedule,
+      description: entry.description,
+    });
+  }
+  return registered;
+}
+function validateNoSystemJobCollision(domainNames) {
+  for (const name of domainNames) {
+    if (name === SYSTEM_JOB_DOMAIN || name.startsWith(`${SYSTEM_JOB_DOMAIN}/`)) {
+      throw new Error(
+        `Domain name "${name}" uses the reserved "${SYSTEM_JOB_DOMAIN}" prefix. This prefix is reserved for framework-internal system jobs.`,
+      );
+    }
+  }
+}
+function addSystemJobEntry(entry) {
+  systemJobRegistry.push(entry);
+}
+function _resetSystemJobRegistry() {
+  systemJobRegistry.length = 0;
+}
+export {
+  SYSTEM_JOB_DOMAIN,
+  _resetSystemJobRegistry,
+  addSystemJobEntry,
+  getApplicableSystemJobs,
+  registerSystemJobs,
+  validateNoSystemJobCollision,
+};

package/server/system-routes/index.js

@@ -0,0 +1,84 @@
+import { checkHealth } from '../health.js';
+
+const SYSTEM_PREFIX = '/_system/api';
+
+class SystemRouter {
+  routes = [];
+  _healthDeps = null;
+
+  constructor({ healthDeps } = {}) {
+    this._healthDeps = healthDeps ?? null;
+  }
+
+  register(route) {
+    this.routes.push(route);
+  }
+
+  async handle(req, res) {
+    const url = req.url ?? '';
+    const method = (req.method ?? 'GET').toUpperCase();
+
+    // ── /_system/health ──
+    if (method === 'GET' && url.split('?')[0] === '/_system/health') {
+      return this._handleHealth(res);
+    }
+
+    if (!url.startsWith(SYSTEM_PREFIX)) return false;
+    const fullPath = url.split('?')[0];
+    const routePath = fullPath.slice(SYSTEM_PREFIX.length) || '/';
+
+    for (const route of this.routes) {
+      if (!routePath.startsWith(route.path)) continue;
+      const methods = Array.isArray(route.method) ? route.method : [route.method];
+      const methodMatch = methods.some((m) => m === '*' || m.toUpperCase() === method);
+      if (!methodMatch) continue;
+      const query = new URL(url, 'http://localhost').searchParams;
+      const remainingPath = routePath.slice(route.path.length) || '/';
+      try {
+        await route.handler(req, res, {
+          path: remainingPath,
+          query,
+          method,
+        });
+      } catch (err) {
+        console.error(`[system-route] Error handling ${method} ${fullPath}:`, err);
+        if (!res.headersSent) {
+          res.writeHead(500, { 'Content-Type': 'application/json' });
+          res.end(
+            JSON.stringify({
+              error: { code: 'INTERNAL_ERROR', message: 'System route handler error' },
+            }),
+          );
+        }
+      }
+      return true;
+    }
+    res.writeHead(404, { 'Content-Type': 'application/json' });
+    res.end(
+      JSON.stringify({
+        error: { code: 'NOT_FOUND', message: `System route not found: ${routePath}` },
+      }),
+    );
+    return true;
+  }
+
+  async _handleHealth(res) {
+    if (this._healthDeps) {
+      try {
+        const result = await checkHealth(this._healthDeps);
+        const status = result.status === 'ok' ? 200 : 503;
+        res.writeHead(status, { 'Content-Type': 'application/json' });
+        res.end(JSON.stringify(result));
+      } catch {
+        res.writeHead(503, { 'Content-Type': 'application/json' });
+        res.end(JSON.stringify({ status: 'degraded', components: {} }));
+      }
+    } else {
+      res.writeHead(200, { 'Content-Type': 'application/json' });
+      res.end(JSON.stringify({ status: 'ok', timestamp: new Date().toISOString() }));
+    }
+    return true;
+  }
+}
+
+export { SystemRouter };