arcway 0.1.7 → 0.1.8

package/package.json

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

package/server/events/handler.js

@@ -9,12 +9,12 @@ function listenerPathToEvent(relativePath) {
     .replace(/\[\.\.\.([^\]]+)\]/g, '*');
 }
 
-function validateListener(exported, filePath) {
-  if (!exported) throw new Error(`Listener file at ${filePath} must have a default export`);
-  if (typeof exported === 'function') return { handler: exported };
-  if (typeof exported === 'object' && typeof exported.handler === 'function') return exported;
+function validateHandler(item, filePath, index) {
+  const label = index !== undefined ? `[${index}]` : '';
+  if (typeof item === 'function') return item;
+  if (typeof item === 'object' && item !== null && typeof item.handler === 'function') return item.handler;
   throw new Error(
-    `Listener at ${filePath} must export a function or an object with a "handler" function`,
+    `Listener at ${filePath}${label} must be a function or an object with a "handler" function`,
   );
 }
 
@@ -47,15 +47,22 @@ class EventHandler {
       label: 'listener file',
     });
     for (const { filePath, relativePath, module } of entries) {
-      const { handler, event: explicitEvent } = validateListener(module.default, filePath);
-      const event = explicitEvent ?? listenerPathToEvent(relativePath);
+      const exported = module.default;
+      if (!exported) throw new Error(`Listener file at ${filePath} must have a default export`);
+
+      const event = listenerPathToEvent(relativePath);
       if (event.startsWith('system/') || event === 'system') continue;
-      this._events.subscribe(event, (_eventName, payload) => {
-        const ctx = buildContext(this._appContext, { event: { name: _eventName, payload } });
-        handler(ctx);
-      });
-      this._listeners.push({ event, fileName: relativePath });
-      this._log?.info(`  ${relativePath} → ${event}`);
+
+      const items = Array.isArray(exported) ? exported : [exported];
+      for (let i = 0; i < items.length; i++) {
+        const handler = validateHandler(items[i], filePath, items.length > 1 ? i : undefined);
+        this._events.subscribe(event, (_eventName, payload) => {
+          const ctx = buildContext(this._appContext, { event: { name: _eventName, payload } });
+          handler(ctx);
+        });
+        this._listeners.push({ event, fileName: relativePath });
+      }
+      this._log?.info(`  ${relativePath} → ${event}${items.length > 1 ? ` (${items.length} listeners)` : ''}`);
     }
   }
 

package/server/jobs/drivers/knex-queue.js

@@ -2,11 +2,12 @@ import { buildContext } from '../../context.js';
 import { validateEnqueue, toError, calculateBackoff } from '../queue.js';
 import { checkDbThroughput } from '../throughput.js';
 import LeaseManager from './lease.js';
-const STALE_JOB_TIMEOUT_MS = 5 * 60 * 1e3;
+const DEFAULT_STALE_TIMEOUT_MS = 5 * 60 * 1e3;
 class KnexJobQueue {
   db;
   tableName;
   backoffMs;
+  staleTimeoutMs;
   registered = new Map();
   _size = 0;
   leaseManager;
@@ -14,6 +15,7 @@ class KnexJobQueue {
     this.db = db;
     this.tableName = options?.tableName ?? 'arcway_jobs';
     this.backoffMs = options?.backoffMs ?? 1000;
+    this.staleTimeoutMs = options?.staleTimeoutMs ?? DEFAULT_STALE_TIMEOUT_MS;
     this.leaseManager = new LeaseManager(db, { tableName: options?.leaseTableName });
   }
   /** Create the jobs table if it doesn't exist. Must be called before use. */
@@ -74,10 +76,24 @@ class KnexJobQueue {
   }
 
   async _recoverStaleJobs(now) {
-    const staleCutoff = new Date(now - STALE_JOB_TIMEOUT_MS).toISOString();
-    await this.db(this.tableName)
+    const runningJobs = await this.db(this.tableName)
       .where('status', 'running')
-      .andWhere('updated_at', '<', staleCutoff)
+      .select('id', 'qualified_name', 'updated_at');
+    if (runningJobs.length === 0) return;
+
+    const staleIds = [];
+    for (const row of runningJobs) {
+      const reg = this.registered.get(row.qualified_name);
+      const timeout = reg?.definition.staleTimeout ?? this.staleTimeoutMs;
+      const updatedAt = new Date(row.updated_at).getTime();
+      if (now - updatedAt > timeout) {
+        staleIds.push(row.id);
+      }
+    }
+    if (staleIds.length === 0) return;
+
+    await this.db(this.tableName)
+      .whereIn('id', staleIds)
       .update({ status: 'pending', updated_at: new Date().toISOString() });
   }
 

package/server/jobs/runner.js

@@ -9,18 +9,19 @@ import { SYSTEM_JOB_DOMAIN, registerSystemJobs } from '../system-jobs/index.js';
 async function discoverJobs(jobsDir) {
   const entries = await discoverModules(jobsDir, { recursive: true, label: 'job file' });
   const jobs = [];
-  for (const { name, filePath, module } of entries) {
+  for (const { name, filePath, relativePath, module } of entries) {
     const job = module.default;
     if (!job || typeof job !== 'object') {
       throw new Error(`Job file at ${filePath} must have a default export`);
     }
-    if (!job.name || typeof job.name !== 'string') {
-      throw new Error(`Job at ${filePath} must export a "name" string`);
-    }
     if (typeof job.handler !== 'function') {
       throw new Error(`Job at ${filePath} must export a "handler" function`);
     }
-    jobs.push({ definition: job, fileName: name });
+    // Default job name from file path: billing/send-invoice.js → billing/send-invoice
+    if (!job.name) {
+      job.name = relativePath.replace(/\\/g, '/').replace(/\.js$/, '');
+    }
+    jobs.push({ definition: job, fileName: name, cooldownMs: job.cooldownMs, staleTimeout: job.staleTimeout });
   }
   return jobs;
 }
@@ -41,7 +42,7 @@ class JobRunner {
   constructor(config, { db, queue, cache, files, mail, events, log } = {}) {
     this._config = config;
     this._log = log;
-    this._dispatcher = new JobDispatcher({ backoffMs: config?.backoffMs });
+    this._dispatcher = new JobDispatcher({ backoffMs: config?.backoffMs, staleTimeoutMs: config?.staleTimeoutMs });
     this._appContext = { db, queue, cache, files, mail, events, log };
   }
 
@@ -70,6 +71,8 @@ class JobRunner {
         fileName,
         schedule: definition.schedule,
         handler: definition.handler,
+        cooldownMs: definition.cooldownMs,
+        staleTimeout: definition.staleTimeout,
       });
       this._log?.info(`  ${fileName} \u2192 ${definition.name}`);
     }
@@ -95,6 +98,7 @@ class JobRunner {
         this._continuousJobs.push({
           qualifiedName: `app/${job.jobName}`,
           handler: job.handler,
+          cooldownMs: job.cooldownMs,
           appContext: this._appContext,
         });
       } else if (job.schedule) {
@@ -169,13 +173,23 @@ class JobRunner {
 
   async _runContinuousLoop(entry) {
     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) {
       try {
+        const start = Date.now();
         const ctx = buildContext(entry.appContext, { payload: void 0 });
         await entry.handler(ctx);
         consecutiveErrors = 0;
+        const elapsed = Date.now() - start;
+        if (cooldownMs > 0 && elapsed < cooldownMs) {
+          const remaining = cooldownMs - elapsed;
+          const deadline = Date.now() + remaining;
+          while (!this._stopped && Date.now() < deadline) {
+            await new Promise((r) => setTimeout(r, Math.min(100, deadline - Date.now())));
+          }
+        }
       } catch (err) {
         consecutiveErrors++;
         const error = toError(err);

package/server/router/api-router.js

@@ -116,7 +116,7 @@ class ApiRouter {
   }
 
   async executeRoute(route, reqInfo) {
-    const middlewareFns = getMiddlewareForRoute(this._middleware, route.pattern);
+    const middlewareFns = getMiddlewareForRoute(this._middleware, route.pattern, route.method);
     const chainedHandler = buildMiddlewareChain(middlewareFns, route.config.handler);
     const ctx = this._buildCtx(reqInfo);
     try {
@@ -225,7 +225,7 @@ class ApiRouter {
     };
 
     // ── Middleware + handler ──
-    const middlewareFns = getMiddlewareForRoute(this._middleware, route.pattern);
+    const middlewareFns = getMiddlewareForRoute(this._middleware, route.pattern, method);
     const middlewareNames = middlewareFns.map((mw) => mw.name || 'anonymous');
     const chainedHandler = buildMiddlewareChain(middlewareFns, route.config.handler);
     const ctx = this._buildCtx(reqInfo);

package/server/router/middleware.js

@@ -1,6 +1,9 @@
 import path from 'node:path';
 import { discoverModules } from '../discovery.js';
 import { validateRequestSchema } from '../validation.js';
+
+const HTTP_METHODS = ['GET', 'POST', 'PUT', 'PATCH', 'DELETE'];
+
 function isMiddlewareConfig(value) {
   return (
     typeof value === 'object' &&
@@ -22,6 +25,23 @@ function wrapMiddlewareConfig(config) {
     return handler(ctx);
   };
 }
+
+function parseMiddlewareItems(exported, filePath, label) {
+  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}" ${label}${items.length > 1 ? `[${i}]` : ''} must be a MiddlewareConfig object with a handler function. Got ${typeof item}.`,
+      );
+    }
+  }
+  return fns;
+}
+
 async function discoverMiddleware(apiDir) {
   const middleware = [];
   const entries = await discoverModules(apiDir, {
@@ -38,38 +58,51 @@ async function discoverMiddleware(apiDir) {
       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}.`,
-          );
+
+    const hasDefault = module.default != null;
+    const hasMethodExports = HTTP_METHODS.some((m) => module[m] != null);
+
+    if (!hasDefault && !hasMethodExports) {
+      throw new Error(
+        `Middleware file "${filePath}" must have a default export or method-specific exports (GET, POST, etc.)`,
+      );
+    }
+
+    const entry = { pathPrefix, fns: [] };
+
+    if (hasDefault) {
+      entry.fns = parseMiddlewareItems(module.default, filePath, 'default export');
+    }
+
+    if (hasMethodExports) {
+      entry.methodFns = {};
+      for (const method of HTTP_METHODS) {
+        if (module[method] != null) {
+          entry.methodFns[method] = parseMiddlewareItems(module[method], filePath, `${method} export`);
         }
       }
-      middleware.push({ pathPrefix, fns });
     }
+
+    middleware.push(entry);
   }
   middleware.sort((a, b) => a.pathPrefix.length - b.pathPrefix.length);
   return middleware;
 }
-function getMiddlewareForRoute(allMiddleware, routePattern) {
+function getMiddlewareForRoute(allMiddleware, routePattern, method) {
   const matching = [];
+  const upperMethod = method?.toUpperCase();
   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);
+    const pathMatches = mw.pathPrefix === '/' ||
+      routePattern === mw.pathPrefix ||
+      routePattern.startsWith(mw.pathPrefix + '/');
+    if (!pathMatches) continue;
+
+    // Add default (all-method) middleware
+    matching.push(...mw.fns);
+
+    // Add method-specific middleware
+    if (upperMethod && mw.methodFns?.[upperMethod]) {
+      matching.push(...mw.methodFns[upperMethod]);
     }
   }
   return matching;

package/server/ws/realtime.js

@@ -82,7 +82,7 @@ function createRealtimeServer(options) {
     };
   }
   async function runHandler(route, reqInfo) {
-    const middlewareFns = getMiddlewareForRoute(middleware, route.pattern);
+    const middlewareFns = getMiddlewareForRoute(middleware, route.pattern, 'GET');
     const chainedHandler = buildMiddlewareChain(middlewareFns, route.config.handler);
     const ctx = buildCtx(reqInfo);
     try {