arcway 0.1.0

package/server/queue/index.js

@@ -0,0 +1,61 @@
+import KnexQueueDriver from './drivers/knex.js';
+import RedisQueueDriver from './drivers/redis.js';
+
+class Queue {
+  _driver;
+  _log;
+  _namespace;
+  _cooldownMs;
+
+  constructor(config, { db, redis, log } = {}) {
+    this._log = log;
+    this._namespace = config?.namespace ?? '';
+    this._cooldownMs = config?.lockCooldownMs ?? 5 * 60 * 1000;
+
+    if (config?.driver === 'redis') {
+      this._driver = new RedisQueueDriver(redis.client, redis.keyPrefix);
+      log?.info('Queue driver: redis');
+    } else {
+      this._driver = new KnexQueueDriver(db, config?.tableName);
+      log?.info('Queue driver: knex');
+    }
+  }
+
+  async init() {
+    await this._driver.init();
+  }
+
+  async push(topic, item) {
+    await this._driver.push(this._namespace, topic, JSON.stringify(item));
+  }
+
+  async pop(topic, count = 1) {
+    const rows = await this._driver.pop(this._namespace, topic, count, this._cooldownMs);
+    return rows.map((r) => {
+      let data;
+      try {
+        data = JSON.parse(r.payload);
+      } catch {
+        this._log?.warn('Queue pop: corrupt JSON payload, using raw string', { id: r.id });
+        data = r.payload;
+      }
+      return { id: r.id, data };
+    });
+  }
+
+  async remove(ids) {
+    await this._driver.remove(this._namespace, ids);
+  }
+
+  /** Return a namespaced child that shares the same driver. */
+  withNamespace(namespace) {
+    const child = Object.create(Queue.prototype);
+    child._driver = this._driver;
+    child._log = this._log;
+    child._namespace = namespace;
+    child._cooldownMs = this._cooldownMs;
+    return child;
+  }
+}
+
+export default Queue;

package/server/rate-limit/consume.js

@@ -0,0 +1,21 @@
+import { RateLimiterRes } from 'rate-limiter-flexible';
+async function consumeAndConvert(limiter, key) {
+  try {
+    const res = await limiter.consume(key, 1);
+    return {
+      allowed: true,
+      remaining: res.remainingPoints,
+      resetMs: res.msBeforeNext,
+    };
+  } catch (err) {
+    if (err instanceof RateLimiterRes) {
+      return {
+        allowed: false,
+        remaining: 0,
+        resetMs: err.msBeforeNext,
+      };
+    }
+    throw err;
+  }
+}
+export { consumeAndConvert };

package/server/rate-limit/drivers/memory.js

@@ -0,0 +1,24 @@
+import { RateLimiterMemory } from 'rate-limiter-flexible';
+import { consumeAndConvert } from '../consume.js';
+class MemoryRateLimitStore {
+  limiters = new Map();
+  getLimiter(max, windowMs) {
+    const configKey = `${max}:${windowMs}`;
+    let limiter = this.limiters.get(configKey);
+    if (!limiter) {
+      limiter = new RateLimiterMemory({
+        points: max,
+        duration: Math.ceil(windowMs / 1e3),
+      });
+      this.limiters.set(configKey, limiter);
+    }
+    return limiter;
+  }
+  async check(key, max, windowMs) {
+    return consumeAndConvert(this.getLimiter(max, windowMs), key);
+  }
+  destroy() {
+    this.limiters.clear();
+  }
+}
+export default MemoryRateLimitStore;

package/server/rate-limit/drivers/redis.js

@@ -0,0 +1,32 @@
+import { RateLimiterRedis } from 'rate-limiter-flexible';
+import { consumeAndConvert } from '../consume.js';
+class RedisRateLimitStore {
+  client;
+  prefix;
+  limiters = new Map();
+  constructor(client, keyPrefix = 'arcway:') {
+    this.client = client;
+    this.prefix = `${keyPrefix}rl:`;
+  }
+  getLimiter(max, windowMs) {
+    const configKey = `${max}:${windowMs}`;
+    let limiter = this.limiters.get(configKey);
+    if (!limiter) {
+      limiter = new RateLimiterRedis({
+        storeClient: this.client,
+        keyPrefix: this.prefix,
+        points: max,
+        duration: Math.ceil(windowMs / 1e3),
+      });
+      this.limiters.set(configKey, limiter);
+    }
+    return limiter;
+  }
+  async check(key, max, windowMs) {
+    return consumeAndConvert(this.getLimiter(max, windowMs), key);
+  }
+  destroy() {
+    this.limiters.clear();
+  }
+}
+export default RedisRateLimitStore;

package/server/rate-limit/index.js

@@ -0,0 +1,33 @@
+import { ErrorCodes } from '../constants.js';
+function defaultKeyFn(req) {
+  const forwarded = req.headers['x-forwarded-for'];
+  if (forwarded) return forwarded.split(',')[0].trim();
+  return req.headers['x-real-ip'] ?? 'unknown';
+}
+function createRateLimitMiddleware(options, store) {
+  const { max, message } = options;
+  const windowMs = options.windowMs ?? 60000;
+  const keyFn = options.keyFn ?? defaultKeyFn;
+  return async (ctx) => {
+    const key = keyFn(ctx.req);
+    const result = await store.check(key, max, windowMs);
+    if (!result.allowed) {
+      const resetTimestamp = Math.ceil((Date.now() + result.resetMs) / 1e3);
+      const retryAfterSec = Math.ceil(result.resetMs / 1e3);
+      return {
+        status: 429,
+        error: {
+          code: ErrorCodes.RATE_LIMITED,
+          message: message ?? 'Too many requests, please try again later',
+        },
+        headers: {
+          'X-RateLimit-Limit': String(max),
+          'X-RateLimit-Remaining': '0',
+          'X-RateLimit-Reset': String(resetTimestamp),
+          'Retry-After': String(retryAfterSec),
+        },
+      };
+    }
+  };
+}
+export { createRateLimitMiddleware };

package/server/redis/index.js

@@ -0,0 +1,67 @@
+import IORedis from 'ioredis';
+import IORedisMock from 'ioredis-mock';
+
+class Redis {
+  _client = null;
+  _config;
+  _log;
+  _inMemory = false;
+
+  constructor(config, { log } = {}) {
+    this._config = config;
+    this._log = log;
+  }
+
+  get connected() {
+    return this._client !== null;
+  }
+
+  /** Whether this instance is backed by an in-memory mock. */
+  get inMemory() {
+    return this._inMemory;
+  }
+
+  async connect() {
+    if (this._config.url) {
+      this._client = new IORedis(this._config.url);
+      try {
+        await this._client.ping();
+        this._log?.info('Redis connected');
+      } catch (err) {
+        await this._client.disconnect();
+        this._client = null;
+        throw new Error(`Redis connection failed: ${err}`);
+      }
+    } else {
+      this._client = new IORedisMock();
+      this._inMemory = true;
+      this._log?.info('Redis: in-memory (ioredis-mock)');
+    }
+
+    return this;
+  }
+
+  /** Create an additional client with the same config (e.g. for pub/sub). */
+  createClient() {
+    if (this._inMemory) return new IORedisMock();
+    return new IORedis(this._config.url);
+  }
+
+  get client() {
+    return this._client;
+  }
+
+  get keyPrefix() {
+    return this._config.keyPrefix ?? 'arcway:';
+  }
+
+  async disconnect() {
+    if (this._client) {
+      await this._client.disconnect();
+      this._client = null;
+      this._log?.info('Redis disconnected');
+    }
+  }
+}
+
+export default Redis;

package/server/ring-buffer.js

@@ -0,0 +1,44 @@
+class RingBuffer {
+  buffer;
+  head = 0;
+  count = 0;
+  capacity;
+  constructor(capacity) {
+    this.capacity = capacity;
+    this.buffer = new Array(capacity);
+  }
+  /** Add an entry. Overwrites the oldest entry when at capacity. */
+  push(entry) {
+    this.buffer[this.head] = entry;
+    this.head = (this.head + 1) % this.capacity;
+    if (this.count < this.capacity) this.count++;
+  }
+  /** Return all entries in insertion order (oldest first). */
+  toArray() {
+    const start = this.count < this.capacity ? 0 : this.head;
+    const result = [];
+    for (let i = 0; i < this.count; i++) {
+      result.push(this.buffer[(start + i) % this.capacity]);
+    }
+    return result;
+  }
+  /** Find the first entry matching a predicate. */
+  find(predicate) {
+    const start = this.count < this.capacity ? 0 : this.head;
+    for (let i = 0; i < this.count; i++) {
+      const entry = this.buffer[(start + i) % this.capacity];
+      if (predicate(entry)) return entry;
+    }
+    return void 0;
+  }
+  /** Number of entries currently stored. */
+  get size() {
+    return this.count;
+  }
+  /** Remove all entries. */
+  clear() {
+    this.head = 0;
+    this.count = 0;
+  }
+}
+export default RingBuffer;

package/server/route.js

@@ -0,0 +1,4 @@
+function defineRoute(config) {
+  return config;
+}
+export { defineRoute };

package/server/router/api-router.js

@@ -0,0 +1,317 @@
+import { Readable } from 'node:stream';
+import { pipeline } from 'node:stream/promises';
+import { discoverRoutes, matchRoute, compilePattern } from './routes.js';
+import { discoverMiddleware, getMiddlewareForRoute, buildMiddlewareChain } from './middleware.js';
+import { ErrorCodes } from '../constants.js';
+import { sealSession, buildSessionSetCookie, buildSessionClearCookie } from '../session/index.js';
+import { flattenHeaders } from '../session/helpers.js';
+import { validateRequestSchema } from '../validation.js';
+import { buildContext } from '../context.js';
+import { toErrorMessage } from '../helpers.js';
+
+function normalizePrefix(rawPrefix) {
+  if (rawPrefix === '') return '';
+  return ('/' + rawPrefix.replace(/^\/+|\/+$/g, '')).replace(/^\/$/, '');
+}
+
+function applyPrefix(routes, middleware, prefix) {
+  if (!prefix) return;
+  for (const route of routes) {
+    route.pattern = prefix + route.pattern;
+    const compiled = compilePattern(route.pattern);
+    route.regex = compiled.regex;
+    route.paramNames = compiled.paramNames;
+  }
+  for (const mw of middleware) {
+    if (mw.pathPrefix === '/') {
+      mw.pathPrefix = prefix;
+    } else {
+      mw.pathPrefix = prefix + mw.pathPrefix;
+    }
+  }
+}
+
+function sendJson(res, statusCode, body, headers) {
+  const json = JSON.stringify(body);
+  res.writeHead(statusCode, {
+    'Content-Type': 'application/json',
+    'Content-Length': Buffer.byteLength(json),
+    ...headers,
+  });
+  res.end(json);
+}
+
+const validateRequest = validateRequestSchema;
+
+async function serializeResponse(res, response, responseHeaders, statusCode) {
+  const customContentType = responseHeaders['Content-Type'] || responseHeaders['content-type'];
+  if (!customContentType || customContentType.includes('application/json')) {
+    const responseBody = response.error ? { error: response.error } : { data: response.data };
+    sendJson(res, statusCode, responseBody, responseHeaders);
+    return;
+  }
+
+  const body = response.error
+    ? typeof response.error === 'string'
+      ? response.error
+      : JSON.stringify(response.error)
+    : (response.data ?? '');
+
+  if (Buffer.isBuffer(body)) {
+    res.writeHead(statusCode, { 'Content-Length': body.length, ...responseHeaders });
+    res.end(body);
+    return;
+  }
+  if (body instanceof Readable) {
+    res.writeHead(statusCode, responseHeaders);
+    await pipeline(body, res);
+    return;
+  }
+  if (typeof body === 'object' && body !== null && typeof body.getReader === 'function') {
+    const nodeStream = Readable.fromWeb(body);
+    res.writeHead(statusCode, responseHeaders);
+    await pipeline(nodeStream, res);
+    return;
+  }
+
+  const raw = typeof body === 'string' ? body : String(body);
+  res.writeHead(statusCode, { 'Content-Length': Buffer.byteLength(raw), ...responseHeaders });
+  res.end(raw);
+}
+
+class ApiRouter {
+  _config;
+  _log;
+  _fileWatcher;
+  _appContext;
+  _sessionConfig;
+  _routes = [];
+  _middleware = [];
+  _prefix = '';
+  _reloading = false;
+  _pendingReload = false;
+
+  constructor(config, { log, fileWatcher, appContext, sessionConfig } = {}) {
+    this._config = config;
+    this._log = log;
+    this._fileWatcher = fileWatcher ?? null;
+    this._appContext = appContext ?? null;
+    this._sessionConfig = sessionConfig ?? null;
+  }
+
+  get routes() {
+    return this._routes;
+  }
+
+  get middleware() {
+    return this._middleware;
+  }
+
+  get prefix() {
+    return this._prefix;
+  }
+
+  findRoute(method, path) {
+    return matchRoute(this._routes, method, path);
+  }
+
+  async executeRoute(route, reqInfo) {
+    const middlewareFns = getMiddlewareForRoute(this._middleware, route.pattern);
+    const chainedHandler = buildMiddlewareChain(middlewareFns, route.config.handler);
+    const ctx = this._buildCtx(reqInfo);
+    try {
+      return await chainedHandler(ctx);
+    } catch (err) {
+      this._log.error(`Handler error in ${route.method} ${route.pattern}`, {
+        error: toErrorMessage(err),
+      });
+      return {
+        status: 500,
+        error: { code: ErrorCodes.HANDLER_ERROR, message: 'An internal error occurred' },
+      };
+    }
+  }
+
+  buildCtx(reqInfo) {
+    return this._buildCtx(reqInfo);
+  }
+
+  _buildCtx(reqInfo) {
+    return buildContext(
+      {
+        ...this._appContext,
+        log: this._log.extend({ requestId: reqInfo.requestId }),
+      },
+      { req: reqInfo },
+    );
+  }
+
+  async init() {
+    if (this._config.enabled === false) {
+      this._log?.info('API: disabled');
+      return;
+    }
+    this._prefix = normalizePrefix(this._config.pathPrefix);
+    this._log?.info('Discovering routes...');
+    await this._discover();
+    if (this._fileWatcher) {
+      this._fileWatcher.subscribe('routes', {
+        dirs: ['api'],
+        extensions: ['.js'],
+        debounceMs: 200,
+        onChange: (events) => {
+          for (const e of events) {
+            this._log?.info(
+              `Route ${e.event === 'unlink' ? 'removed' : e.event === 'add' ? 'added' : 'changed'}: ${e.relativePath}`,
+            );
+          }
+          return this._reload();
+        },
+      });
+      this._log?.info('Routes: watching for changes');
+    }
+  }
+
+  async handle(req, res) {
+    const method = req.method ?? 'GET';
+    const pathname = (req.url ?? '/').split('?')[0];
+    const requestId = req.requestId;
+    const startTime = Date.now();
+
+    const matched = matchRoute(this._routes, method, pathname);
+    if (!matched) return false;
+
+    const { route, params } = matched;
+
+    // ── Validation ──
+    const mergedQuery = { ...(req.query ?? {}), ...params };
+    const validated = validateRequest(route.config.schema, mergedQuery, req.body);
+    if (validated.error) {
+      sendJson(res, 400, { error: validated.error });
+      return true;
+    }
+
+    const reqInfo = {
+      requestId,
+      method,
+      path: pathname,
+      query: validated.query,
+      body: validated.body,
+      headers: req.flatHeaders ?? flattenHeaders(req.headers),
+      cookies: req.cookies ?? {},
+      session: req.session,
+    };
+
+    // ── Middleware + handler ──
+    const middlewareFns = getMiddlewareForRoute(this._middleware, route.pattern);
+    const middlewareNames = middlewareFns.map((mw) => mw.name || 'anonymous');
+    const chainedHandler = buildMiddlewareChain(middlewareFns, route.config.handler);
+    const ctx = this._buildCtx(reqInfo);
+
+    let response;
+    try {
+      response = await chainedHandler(ctx);
+    } catch (err) {
+      const errorMsg = toErrorMessage(err);
+      ctx.log.error(`Handler error in ${route.method} ${route.pattern}`, { error: errorMsg });
+      ctx.log.info('request', {
+        method,
+        path: pathname,
+        route: route.pattern,
+        status: 500,
+        durationMs: Date.now() - startTime,
+        middleware: middlewareNames,
+        error: errorMsg,
+      });
+      sendJson(res, 500, {
+        error: { code: ErrorCodes.HANDLER_ERROR, message: 'An internal error occurred' },
+      });
+      return true;
+    }
+
+    // ── Session cookie ──
+    const responseHeaders = { ...response.headers };
+    if (response.session !== void 0) {
+      if (!this._sessionConfig) {
+        throw new Error(
+          `Route handler for ${route.method} ${route.pattern} returned "session" but no session is configured. Add a "session" section with a password to your arcway.config.`,
+        );
+      }
+      if (response.session === null) {
+        responseHeaders['Set-Cookie'] = buildSessionClearCookie(this._sessionConfig);
+      } else {
+        const sealed = await sealSession(response.session, this._sessionConfig);
+        responseHeaders['Set-Cookie'] = buildSessionSetCookie(sealed, this._sessionConfig);
+      }
+    }
+
+    // ── Serialize + send ──
+    const statusCode = response.status ?? (response.error ? 400 : 200);
+    await serializeResponse(res, response, responseHeaders, statusCode);
+    ctx.log.info('request', {
+      method,
+      path: pathname,
+      route: route.pattern,
+      status: statusCode,
+      durationMs: Date.now() - startTime,
+      middleware: middlewareNames,
+    });
+
+    return true;
+  }
+
+  async _reload() {
+    if (this._reloading) {
+      this._pendingReload = true;
+      return;
+    }
+    this._reloading = true;
+    try {
+      const start = Date.now();
+      await this._discover();
+      this._log?.info(
+        `Routes reloaded in ${Date.now() - start}ms (${this._routes.length} routes, ${this._middleware.length} middleware)`,
+      );
+    } catch (err) {
+      this._log?.error('Route reload failed', { error: String(err) });
+    } finally {
+      this._reloading = false;
+      if (this._pendingReload) {
+        this._pendingReload = false;
+        await this._reload();
+      }
+    }
+  }
+
+  async close() {
+    if (this._fileWatcher) {
+      this._fileWatcher.unsubscribe('routes');
+    }
+  }
+
+  async _discover() {
+    const [routes, middleware] = await Promise.all([
+      discoverRoutes(this._config.dir),
+      discoverMiddleware(this._config.dir),
+    ]);
+
+    applyPrefix(routes, middleware, this._prefix);
+
+    this._routes.length = 0;
+    this._routes.push(...routes);
+    this._middleware.length = 0;
+    this._middleware.push(...middleware);
+
+    if (this._prefix) {
+      this._log?.info(`API path prefix: ${this._prefix}`);
+    }
+    for (const route of this._routes) {
+      this._log?.info(`  ${route.method} ${route.pattern}`);
+    }
+    for (const mw of this._middleware) {
+      this._log?.info(`  ${mw.pathPrefix} (${mw.fns.length} fn(s))`);
+    }
+  }
+}
+
+export { ApiRouter, applyPrefix, normalizePrefix };

package/server/router/cors.js

@@ -0,0 +1,31 @@
+function buildCorsHeaders(config, requestOrigin) {
+  const headers = {};
+  if (Array.isArray(config.origin)) {
+    if (requestOrigin && config.origin.includes(requestOrigin)) {
+      headers['Access-Control-Allow-Origin'] = requestOrigin;
+      headers['Vary'] = 'Origin';
+    }
+  } else if (config.origin === '*' && config.credentials) {
+    if (requestOrigin) {
+      headers['Access-Control-Allow-Origin'] = requestOrigin;
+      headers['Vary'] = 'Origin';
+    }
+  } else {
+    headers['Access-Control-Allow-Origin'] = config.origin;
+  }
+  if (config.credentials) {
+    headers['Access-Control-Allow-Credentials'] = 'true';
+  }
+  if (config.exposedHeaders.length > 0) {
+    headers['Access-Control-Expose-Headers'] = config.exposedHeaders.join(', ');
+  }
+  return headers;
+}
+function buildPreflightHeaders(config) {
+  return {
+    'Access-Control-Allow-Methods': config.methods.join(', '),
+    'Access-Control-Allow-Headers': config.allowedHeaders.join(', '),
+    'Access-Control-Max-Age': String(config.maxAge),
+  };
+}
+export { buildCorsHeaders, buildPreflightHeaders };