arcway 0.2.0 → 0.3.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "arcway",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "A convention-based framework for building modular monoliths with strict domain boundaries.",
   "license": "MIT",
   "type": "module",

package/server/boot/index.js

@@ -19,6 +19,9 @@ import { createViteDevRouter } from '../pages/vite-dev.js';
 import { resolvePagesOutDir } from '../pages/out-dir.js';
 import { collectRuntimeMeta } from '../meta.js';
 import { createPluginManager } from '../plugins/manager.js';
+import { CallbackDispatcher, CallbackRegistry } from '../callbacks/index.js';
+import { CallbackStore } from '../callbacks/store.js';
+import { discoverRootCallbacks } from '../callbacks/discovery.js';
 import path from 'node:path';
 
 async function boot(options) {
@@ -28,10 +31,19 @@ async function boot(options) {
   const envFiles = loadEnvFiles(rootDir, mode);
   const config = await makeConfig(rootDir, { overrides: options.configOverrides, mode });
 
-  const plugins = await createPluginManager(config.plugins, { runLifecycle: false });
+  const plugins = await createPluginManager(config.plugins, {
+    runLifecycle: false,
+    bundle: mode === 'development',
+  });
 
   const infrastructure = await createInfrastructure(config, { runMigrations: true });
   const { db, redis, queue, cache, files, mail, events, log } = infrastructure;
+  const callbackStore = new CallbackStore(db);
+  await callbackStore.init();
+  const callbacks = new CallbackRegistry({
+    store: callbackStore,
+    secret: config.vault?.values?.callback,
+  });
   const meta = await collectRuntimeMeta(rootDir);
 
   if (envFiles.length > 0) log.info('Env files loaded', { envFiles });
@@ -55,6 +67,7 @@ async function boot(options) {
     fileWatcher,
     meta,
     vault: config.vault,
+    callbacks,
   };
 
   plugins.log = log;
@@ -95,6 +108,7 @@ async function boot(options) {
     log,
     meta,
     vault: config.vault,
+    callbacks,
     workerPool,
     plugins,
   });
@@ -110,6 +124,7 @@ async function boot(options) {
     sessionConfig: config.session,
   });
   await apiRouter.init();
+  if (fileWatcher) plugins.watch(fileWatcher, { jobRunner });
 
   const pagesRouter = new PagesRouter(config, { rootDir, log, mode, fileWatcher, appContext });
   await pagesRouter.init();
@@ -124,7 +139,17 @@ async function boot(options) {
     db,
     redisClients: [{ name: 'redis', client: redis?.client }],
   };
-  const systemRouter = new SystemRouter({ healthDeps });
+  const callbackHandlers = await discoverRootCallbacks(rootDir);
+  const pluginCallbacks = (await plugins.discoverCallbacks?.()) ?? new Map();
+  for (const [name, callback] of pluginCallbacks) callbackHandlers.set(name, callback);
+  const callbackDispatcher = new CallbackDispatcher({
+    appContext,
+    callbacks: callbackHandlers,
+    registry: callbacks,
+    sessionConfig: config.session,
+    log,
+  });
+  const systemRouter = new SystemRouter({ healthDeps, callbackDispatcher });
 
   const staticRouter = new StaticRouter({
     outDir: pagesOutDir,
@@ -166,6 +191,7 @@ async function boot(options) {
     if (workerPool) await workerPool.shutdown();
     await pagesRouter.close();
     await apiRouter.close();
+    if (fileWatcher) plugins.unwatch(fileWatcher);
     if (viteRouter) await viteRouter.close();
     await webServer.close();
     if (fileWatcher) await fileWatcher.close();

package/server/build.js

@@ -28,7 +28,6 @@ async function validateServerModules(config) {
   if (config?.api?.enabled !== false && config?.api?.dir) {
     await discoverRoutes(config.api.dir);
     await discoverMiddleware(config.api.dir);
-    await plugins.discoverRoutes();
   }
 
   if (config?.events?.dir) {

package/server/callbacks/cleanup-job.js

@@ -0,0 +1,12 @@
+import { CallbackStore } from './store.js';
+
+const cleanupCallbacksJob = {
+  name: 'cleanup-callbacks',
+  schedule: '*/15 * * * *',
+  handler: async (ctx) => {
+    const store = new CallbackStore(ctx.db);
+    await store.cleanup();
+  },
+};
+
+export { cleanupCallbacksJob };

package/server/callbacks/discovery.js

@@ -0,0 +1,33 @@
+import path from 'node:path';
+import { discoverModules } from '../discovery.js';
+
+function callbackName(relativePath) {
+  return relativePath.replace(/\\/g, '/').replace(/\.js$/, '');
+}
+
+function buildCallbacksFromModules(entries, { prefix = '' } = {}) {
+  const callbacks = new Map();
+  for (const entry of entries) {
+    const handler = entry.module.default ?? entry.module.handler;
+    if (typeof handler !== 'function') {
+      throw new Error(`Callback at ${entry.filePath} must export a handler function`);
+    }
+    const name = `${prefix}${callbackName(entry.relativePath)}`;
+    callbacks.set(name, { name, filePath: entry.filePath, handler });
+  }
+  return callbacks;
+}
+
+async function discoverCallbacks(callbacksDir) {
+  const entries = await discoverModules(callbacksDir, {
+    recursive: true,
+    label: 'callback file',
+  });
+  return buildCallbacksFromModules(entries);
+}
+
+async function discoverRootCallbacks(rootDir) {
+  return discoverCallbacks(path.join(rootDir, 'callbacks'));
+}
+
+export { buildCallbacksFromModules, discoverCallbacks, discoverRootCallbacks };

package/server/callbacks/index.js

@@ -0,0 +1,173 @@
+import { serializeResponse, sendJson } from '../router/http-helpers.js';
+import { buildSessionClearCookie, buildSessionSetCookie, sealSession } from '../session/index.js';
+import { buildContext } from '../context.js';
+import { CallbackRateLimiter } from './rate-limit.js';
+import { sealCallbackToken, unsealCallbackToken } from './tokens.js';
+
+function getCallbackToken(req, params) {
+  const state = req.query?.state ?? params.query?.get?.('state');
+  if (state) return state;
+  const pathToken = params.path && params.path !== '/' ? params.path.replace(/^\/+/, '') : '';
+  return pathToken ? decodeURIComponent(pathToken) : null;
+}
+
+function buildReqInfo(req) {
+  return {
+    id: req.id,
+    ip: req.ip,
+    method: req.method ?? 'GET',
+    path: (req.url ?? '/').split('?')[0],
+    query: req.query ?? {},
+    body: req.body,
+    rawBody: req.rawBody,
+    headers: req.flatHeaders ?? {},
+    cookies: req.cookies ?? {},
+    session: req.session,
+  };
+}
+
+class CallbackRegistry {
+  constructor({ store, secret }) {
+    this.store = store;
+    this.secret = secret;
+  }
+
+  bind(ctx) {
+    return {
+      register: async ({ handler, payload, oneTime = true, ttl } = {}) => {
+        if (!this.secret) throw new Error('Callback key is required');
+        const boundToSession =
+          oneTime !== false ? (ctx.req?.session?.id ?? ctx.req?.session?.userId ?? null) : null;
+        const row = await this.store.register({
+          handler,
+          payload,
+          oneTime,
+          ttl,
+          boundToSession,
+        });
+        return sealCallbackToken({ id: row.id, expiresAt: row.expiresAt }, this.secret);
+      },
+    };
+  }
+}
+
+class CallbackDispatcher {
+  constructor({ appContext, callbacks, registry, sessionConfig, log, rateLimiter } = {}) {
+    this.appContext = appContext;
+    this.callbacks = callbacks ?? new Map();
+    this.registry = registry;
+    this.sessionConfig = sessionConfig ?? null;
+    this.log = log;
+    this.rateLimiter = rateLimiter ?? new CallbackRateLimiter();
+  }
+
+  async handle(req, res, params) {
+    const rate = this.rateLimiter.check(req.ip);
+    if (!rate.allowed) {
+      sendJson(
+        res,
+        429,
+        { error: { code: 'RATE_LIMITED', message: 'Callback rate limit exceeded' } },
+        {
+          'X-RateLimit-Remaining': '0',
+          'X-RateLimit-Reset': String(rate.resetAt),
+          'Retry-After': String(Math.max(1, rate.resetAt - Math.ceil(Date.now() / 1000))),
+        },
+      );
+      return;
+    }
+
+    const token = getCallbackToken(req, params);
+    if (!token) {
+      sendJson(res, 400, {
+        error: { code: 'CALLBACK_TOKEN_REQUIRED', message: 'Callback token is required' },
+      });
+      return;
+    }
+
+    let sealed;
+    try {
+      sealed = await unsealCallbackToken(token, this.registry.secret);
+    } catch {
+      sendJson(res, 400, {
+        error: { code: 'INVALID_CALLBACK_TOKEN', message: 'Invalid callback token' },
+      });
+      return;
+    }
+
+    const row = await this.registry.store.consume(sealed.id);
+    if (!row) {
+      sendJson(res, 410, {
+        error: { code: 'CALLBACK_EXPIRED_OR_USED', message: 'Callback expired or already used' },
+      });
+      return;
+    }
+
+    if (row.boundToSession) {
+      const sessionId = req.session?.id ?? req.session?.userId ?? null;
+      if (sessionId !== row.boundToSession) {
+        sendJson(res, 403, {
+          error: { code: 'CALLBACK_SESSION_MISMATCH', message: 'Callback session mismatch' },
+        });
+        return;
+      }
+    }
+
+    const target = this.callbacks.get(row.target);
+    if (!target) {
+      sendJson(res, 404, {
+        error: { code: 'CALLBACK_HANDLER_NOT_FOUND', message: 'Callback handler not found' },
+      });
+      return;
+    }
+
+    const ctx = buildContext(
+      {
+        ...this.appContext,
+        log: this.log?.extend ? this.log.extend({ requestId: req.id }) : this.appContext.log,
+      },
+      {
+        req: buildReqInfo(req),
+        callback: { payload: row.payload, target: row.target, id: row.id },
+      },
+    );
+
+    let response;
+    try {
+      response = await target.handler(ctx);
+    } catch (err) {
+      this.log?.error?.('Callback handler error', { target: row.target, error: String(err) });
+      sendJson(res, 500, {
+        error: { code: 'CALLBACK_HANDLER_ERROR', message: 'Callback handler error' },
+      });
+      return;
+    }
+
+    const responseHeaders = { ...(response?.headers ?? {}) };
+    if (response?.redirect) {
+      res.writeHead(response.status ?? 302, { ...responseHeaders, Location: response.redirect });
+      res.end();
+      return;
+    }
+    if (response?.session !== void 0) {
+      if (!this.sessionConfig) {
+        throw new Error('Callback handler returned session but no session is configured');
+      }
+      responseHeaders['Set-Cookie'] =
+        response.session === null
+          ? buildSessionClearCookie(this.sessionConfig)
+          : buildSessionSetCookie(
+              await sealSession(response.session, this.sessionConfig),
+              this.sessionConfig,
+            );
+    }
+    await serializeResponse(
+      res,
+      response ?? { data: null },
+      responseHeaders,
+      response?.status ?? 200,
+    );
+  }
+}
+
+export { CallbackDispatcher, CallbackRegistry };

package/server/callbacks/rate-limit.js

@@ -0,0 +1,32 @@
+const DEFAULT_CALLBACK_RATE_LIMIT = Object.freeze({
+  max: 30,
+  windowMs: 60_000,
+});
+
+class CallbackRateLimiter {
+  constructor({
+    max = DEFAULT_CALLBACK_RATE_LIMIT.max,
+    windowMs = DEFAULT_CALLBACK_RATE_LIMIT.windowMs,
+  } = {}) {
+    this.max = max;
+    this.windowMs = windowMs;
+    this.buckets = new Map();
+  }
+
+  check(ip = 'unknown', now = Date.now()) {
+    const key = String(ip || 'unknown');
+    let bucket = this.buckets.get(key);
+    if (!bucket || bucket.resetAt <= now) {
+      bucket = { count: 0, resetAt: now + this.windowMs };
+      this.buckets.set(key, bucket);
+    }
+    bucket.count += 1;
+    return {
+      allowed: bucket.count <= this.max,
+      remaining: Math.max(0, this.max - bucket.count),
+      resetAt: Math.ceil(bucket.resetAt / 1000),
+    };
+  }
+}
+
+export { CallbackRateLimiter, DEFAULT_CALLBACK_RATE_LIMIT };

package/server/callbacks/store.js

@@ -0,0 +1,121 @@
+import { randomUUID } from 'node:crypto';
+
+const CALLBACK_TABLE = 'arcway_callbacks';
+const DEFAULT_CALLBACK_TTL_SECONDS = 600;
+const DEFAULT_CLEANUP_GRACE_SECONDS = 3600;
+
+function toIso(value) {
+  return new Date(value).toISOString();
+}
+
+function serializePayload(payload) {
+  return JSON.stringify(payload ?? null);
+}
+
+function parseRow(row) {
+  if (!row) return null;
+  return {
+    id: row.id,
+    target: row.target,
+    payload: JSON.parse(row.payload),
+    oneTime: Boolean(row.one_time),
+    used: Boolean(row.used),
+    boundToSession: row.bound_to_session ?? null,
+    expiresAt: row.expires_at,
+  };
+}
+
+class CallbackStore {
+  constructor(db, { tableName = CALLBACK_TABLE } = {}) {
+    this.db = db;
+    this.tableName = tableName;
+  }
+
+  async init() {
+    if (!this.db) return;
+    const exists = await this.db.schema.hasTable(this.tableName);
+    if (exists) return;
+    await this.db.schema.createTable(this.tableName, (table) => {
+      table.string('id').primary();
+      table.string('target').notNullable().index();
+      table.text('payload').notNullable();
+      table.boolean('one_time').notNullable().defaultTo(true);
+      table.boolean('used').notNullable().defaultTo(false).index();
+      table.string('bound_to_session').nullable().index();
+      table.timestamp('expires_at').notNullable().index();
+      table.timestamp('created_at').defaultTo(this.db.fn.now());
+      table.timestamp('updated_at').defaultTo(this.db.fn.now());
+    });
+  }
+
+  async register({ handler, payload, oneTime = true, ttl, boundToSession }) {
+    if (!this.db) throw new Error('Callback registration requires a database');
+    if (!handler || typeof handler !== 'string') {
+      throw new Error('Callback handler must be a non-empty string');
+    }
+    const ttlSeconds = ttl ?? DEFAULT_CALLBACK_TTL_SECONDS;
+    if (!Number.isFinite(ttlSeconds) || ttlSeconds <= 0) {
+      throw new Error('Callback ttl must be a positive number of seconds');
+    }
+
+    const now = Date.now();
+    const row = {
+      id: randomUUID(),
+      target: handler,
+      payload: serializePayload(payload),
+      one_time: oneTime !== false,
+      used: false,
+      bound_to_session: boundToSession ?? null,
+      expires_at: toIso(now + ttlSeconds * 1000),
+      created_at: toIso(now),
+      updated_at: toIso(now),
+    };
+    await this.db(this.tableName).insert(row);
+    return parseRow(row);
+  }
+
+  async claim(id, now = new Date()) {
+    const nowIso = toIso(now);
+    return this.db.transaction(async (trx) => {
+      const updated = await trx(this.tableName)
+        .where('id', id)
+        .andWhere('one_time', true)
+        .andWhere('used', false)
+        .andWhere('expires_at', '>', nowIso)
+        .update({ used: true, updated_at: nowIso });
+      if (updated === 0) return null;
+      const row = await trx(this.tableName).where('id', id).first();
+      return parseRow(row);
+    });
+  }
+
+  async getActive(id, now = new Date()) {
+    const row = await this.db(this.tableName)
+      .where('id', id)
+      .andWhere('one_time', false)
+      .andWhere('expires_at', '>', toIso(now))
+      .first();
+    if (!row || row.used) return null;
+    return parseRow(row);
+  }
+
+  async consume(id, now = new Date()) {
+    const claimed = await this.claim(id, now);
+    if (claimed) return claimed;
+    return this.getActive(id, now);
+  }
+
+  async cleanup({ graceSeconds = DEFAULT_CLEANUP_GRACE_SECONDS } = {}) {
+    const now = Date.now();
+    const expiredCutoff = toIso(now);
+    const usedCutoff = toIso(now - graceSeconds * 1000);
+    return this.db(this.tableName)
+      .where('expires_at', '<=', expiredCutoff)
+      .orWhere(function () {
+        this.where('used', true).andWhere('updated_at', '<=', usedCutoff);
+      })
+      .delete();
+  }
+}
+
+export { CALLBACK_TABLE, CallbackStore };

package/server/callbacks/tokens.js

@@ -0,0 +1,44 @@
+import { sealData, unsealData } from 'iron-session';
+
+function requireCallbackKey(secret) {
+  if (!secret) {
+    throw new Error('Callback key is required');
+  }
+  return secret;
+}
+
+async function sealCallbackToken({ id, expiresAt }, secret) {
+  const exp = new Date(expiresAt).getTime();
+  if (!id || !Number.isFinite(exp)) {
+    throw new Error('Callback token requires id and expiresAt');
+  }
+  return sealData(
+    { id, exp },
+    {
+      password: requireCallbackKey(secret),
+      ttl: 0,
+    },
+  );
+}
+
+async function unsealCallbackToken(token, secret, now = Date.now()) {
+  let data;
+  try {
+    data = await unsealData(token, {
+      password: requireCallbackKey(secret),
+      ttl: 0,
+    });
+  } catch {
+    throw new Error('Invalid callback token');
+  }
+
+  if (!data || typeof data !== 'object' || typeof data.id !== 'string') {
+    throw new Error('Invalid callback token');
+  }
+  if (!Number.isFinite(data.exp) || data.exp <= now) {
+    throw new Error('Callback token expired');
+  }
+  return { id: data.id, exp: data.exp };
+}
+
+export { sealCallbackToken, unsealCallbackToken };

package/server/context.js

@@ -1,4 +1,5 @@
 import * as vault from './lib/vault/index.js';
+import { createJwtCodec } from './lib/vault/jwt.js';
 import { wsBroadcastToPath, wsSendToSocket } from './ws/registry.js';
 
 function trackDb(db) {
@@ -114,9 +115,11 @@ function normalizeMeta(meta) {
 
 function buildVaultToolkit(vaultConfig) {
   if (!vaultConfig?.masterSecret) return vault;
+  const jwtCodec = createJwtCodec(vaultConfig.values?.jwt);
 
   return {
     ...vault,
+    ...jwtCodec,
     deriveKey: (label) => vault.deriveKey(vaultConfig.masterSecret, label),
     deriveKeyPair: (label, opts) => vault.deriveKeyPair(vaultConfig.masterSecret, label, opts),
   };
@@ -151,6 +154,7 @@ function buildContext(appContext, extras) {
     _dbStats: tracked.stats,
     ...normalizedExtras,
   };
+  ctx.callbacks = appContext.callbacks?.bind?.(ctx);
   ctx.plugins = appContext.plugins?.buildContextProxy?.(ctx);
   return ctx;
 }

package/server/jobs/runner.js

@@ -5,8 +5,7 @@ import { toError, calculateBackoff } from './queue.js';
 import JobDispatcher from './drivers/memory-queue.js';
 import { SYSTEM_JOB_DOMAIN, registerSystemJobs } from '../system-jobs/index.js';
 
-async function discoverJobs(jobsDir) {
-  const entries = await discoverModules(jobsDir, { recursive: true, label: 'job file' });
+function buildJobsFromModules(entries) {
   const jobs = [];
   for (const { name, filePath, relativePath, module } of entries) {
     const job = module.default;
@@ -31,6 +30,11 @@ async function discoverJobs(jobsDir) {
   return jobs;
 }
 
+async function discoverJobs(jobsDir) {
+  const entries = await discoverModules(jobsDir, { recursive: true, label: 'job file' });
+  return buildJobsFromModules(entries);
+}
+
 class JobRunner {
   _dispatcher;
   _config;
@@ -42,11 +46,25 @@ class JobRunner {
   _timer = null;
   _started = false;
   _stopped = false;
+  _runGeneration = 0;
   _lastEnqueuedMinute = new Map();
 
   constructor(
     config,
-    { db, queue, cache, files, mail, events, log, meta, vault, workerPool, plugins } = {},
+    {
+      db,
+      queue,
+      cache,
+      files,
+      mail,
+      events,
+      log,
+      meta,
+      vault,
+      callbacks,
+      workerPool,
+      plugins,
+    } = {},
   ) {
     this._config = config;
     this._log = log;
@@ -55,7 +73,19 @@ class JobRunner {
       staleTimeoutMs: config?.staleTimeoutMs,
       workerPool,
     });
-    this._appContext = { db, queue, cache, files, mail, events, log, meta, vault, plugins };
+    this._appContext = {
+      db,
+      queue,
+      cache,
+      files,
+      mail,
+      events,
+      log,
+      meta,
+      vault,
+      callbacks,
+      plugins,
+    };
   }
 
   get dispatcher() {
@@ -135,10 +165,23 @@ class JobRunner {
     }
   }
 
+  async reload() {
+    const wasStarted = this._started;
+    this.stop();
+    this._jobs = [];
+    this._cronEntries = [];
+    this._continuousJobs = [];
+    this._lastEnqueuedMinute = new Map();
+    this._dispatcher.registered.clear();
+    await this.init();
+    if (wasStarted) this.start();
+  }
+
   start(intervalMs) {
     if (this._started) return;
     this._started = true;
     this._stopped = false;
+    const generation = ++this._runGeneration;
     const pollMs = intervalMs ?? this._config?.pollIntervalMs ?? 60000;
     this._timer = setInterval(() => {
       this.tick().catch((err) => {
@@ -146,7 +189,7 @@ class JobRunner {
       });
     }, pollMs);
     for (const entry of this._continuousJobs) {
-      this._runContinuousLoop(entry);
+      this._runContinuousLoop(entry, generation);
     }
 
     const parts = [];
@@ -158,6 +201,7 @@ class JobRunner {
   stop() {
     this._stopped = true;
     this._started = false;
+    this._runGeneration++;
     if (this._timer) {
       clearInterval(this._timer);
       this._timer = null;
@@ -188,12 +232,12 @@ class JobRunner {
     await this._dispatcher.process();
   }
 
-  async _runContinuousLoop(entry) {
+  async _runContinuousLoop(entry, generation) {
     const backoffMs = this._config?.backoffMs ?? 1000;
     const cooldownMs = entry.cooldownMs ?? this._config?.cooldownMs ?? 1000;
     let consecutiveErrors = 0;
     console.log(`[job-runner] continuous: ${entry.qualifiedName} started`);
-    while (!this._stopped) {
+    while (!this._stopped && generation === this._runGeneration) {
       try {
         const start = Date.now();
         const ctx = buildContext(entry.appContext, { payload: void 0 });
@@ -206,7 +250,7 @@ class JobRunner {
         if (cooldownMs > 0 && elapsed < cooldownMs) {
           const remaining = cooldownMs - elapsed;
           const deadline = Date.now() + remaining;
-          while (!this._stopped && Date.now() < deadline) {
+          while (!this._stopped && generation === this._runGeneration && Date.now() < deadline) {
             await new Promise((r) => setTimeout(r, Math.min(100, deadline - Date.now())));
           }
         }
@@ -219,7 +263,7 @@ class JobRunner {
           error.message,
         );
         const deadline = Date.now() + delay;
-        while (!this._stopped && Date.now() < deadline) {
+        while (!this._stopped && generation === this._runGeneration && Date.now() < deadline) {
           await new Promise((r) => setTimeout(r, Math.min(100, deadline - Date.now())));
         }
       }
@@ -228,4 +272,4 @@ class JobRunner {
   }
 }
 
-export { JobRunner, discoverJobs };
+export { JobRunner, buildJobsFromModules, discoverJobs };