arcway 0.3.2 → 0.4.1

package/package.json

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

package/server/bin/commands/start.js

@@ -1,10 +1,16 @@
 import boot from '#server/boot.js';
+import { loadEnvFiles } from '#server/env.js';
 
 async function startServer(mode) {
   if (mode === 'production') {
     process.env.NODE_ENV = 'production';
   }
 
+  // Load .env files so `arcway dev` / `arcway start` pick up local config
+  // (.env, .env.local, .env.<mode>, .env.<mode>.local). Real process env wins —
+  // dotenv never overrides already-set variables.
+  loadEnvFiles(process.cwd(), mode);
+
   const app = await boot({ mode, rootDir: process.cwd() });
   app.logger.info('Arcway framework ready', { mode, port: app.port });
 
@@ -24,7 +30,10 @@ async function startServer(mode) {
 }
 
 function register(program) {
-  program.command('start').description('Start production server').action(() => startServer('production'));
+  program
+    .command('start')
+    .description('Start production server')
+    .action(() => startServer('production'));
 }
 
 export { startServer };

package/server/boot/index.js

@@ -124,6 +124,7 @@ async function boot(options) {
     sessionConfig: config.session,
   });
   await apiRouter.init();
+  appContext.api = apiRouter;
   if (fileWatcher) plugins.watch(fileWatcher, { jobRunner });
 
   const pagesRouter = new PagesRouter(config, { rootDir, log, mode, fileWatcher, appContext });

package/server/context.js

@@ -156,6 +156,7 @@ function buildContext(appContext, extras) {
   };
   ctx.callbacks = appContext.callbacks?.bind?.(ctx);
   ctx.plugins = appContext.plugins?.buildContextProxy?.(ctx);
+  ctx.api = appContext.api?.buildContextApi?.(ctx) ?? null;
   return ctx;
 }
 

package/server/lib/vault/ids.js

@@ -1,9 +1,15 @@
 import { randomUUID } from 'node:crypto';
-import { nanoid } from 'nanoid';
+import { customAlphabet, nanoid } from 'nanoid';
+
+const LOWERCASE_BASE32_ALPHABET = 'abcdefghijklmnopqrstuvwxyz234567';
+const lowercaseBase32 = customAlphabet(LOWERCASE_BASE32_ALPHABET);
 function generateUUID() {
   return randomUUID();
 }
 function generateNanoId(size) {
   return nanoid(size);
 }
-export { generateNanoId, generateUUID };
+function generateBase32Id(size = 16) {
+  return lowercaseBase32(size);
+}
+export { generateBase32Id, generateNanoId, generateUUID };

package/server/lib/vault/index.js

@@ -1,5 +1,5 @@
 import { hashPassword, verifyPassword } from './password.js';
-import { generateUUID, generateNanoId } from './ids.js';
+import { generateBase32Id, generateUUID, generateNanoId } from './ids.js';
 import { encrypt, decrypt } from './encrypt.js';
 import { jwtEncode, jwtDecode } from './jwt.js';
 import {
@@ -29,6 +29,7 @@ export {
   encodeMasterSecret,
   encrypt,
   formatVaultKey,
+  generateBase32Id,
   generateNanoId,
   generateUUID,
   hashPassword,

package/server/pages/ssr.js

@@ -50,7 +50,8 @@ async function loadComponent(bundlePath, cacheKey, componentCache, cacheVersion)
     const Component = mod.default;
     componentCache.set(cacheKey, Component);
     return Component;
-  } catch {
+  } catch (error) {
+    console.error(`[arcway] failed to load component ${cacheKey} from ${bundlePath}:`, error && error.stack ? error.stack : error);
     // Component failed to load (missing file, syntax error) — caller handles null
     return null;
   }

package/server/router/api-router.js

@@ -2,7 +2,7 @@ import { discoverRoutes, matchRoute, compilePattern, sortBySpecificity } from '.
 import { discoverMiddleware, getMiddlewareForRoute, buildMiddlewareChain } from './middleware.js';
 import { sendJson, serializeResponse } from './http-helpers.js';
 import { ErrorCodes } from '../constants.js';
-import { checkRateLimit } from './ratelimit.js';
+import { checkRouteRateLimits } from './ratelimit.js';
 import { sealSession, buildSessionSetCookie, buildSessionClearCookie } from '../session/index.js';
 import { flattenHeaders } from '../session/helpers.js';
 import { validateRequestSchema } from '../validation.js';
@@ -71,17 +71,93 @@ class ApiRouter {
     return matchRoute(this._routes, method, path);
   }
 
+  async forward(
+    { method: fwdMethod, path: fwdPath, params: fwdParams, body: fwdBody, query: fwdQuery },
+    callerCtx,
+  ) {
+    const matched = matchRoute(this._routes, fwdMethod, fwdPath);
+    if (!matched) {
+      return {
+        status: 404,
+        error: { code: ErrorCodes.NOT_FOUND, message: `No route for ${fwdMethod} ${fwdPath}` },
+      };
+    }
+    const { route, params: matchedParams } = matched;
+
+    const mergedQuery = {
+      ...(callerCtx.req?.query ?? {}),
+      ...(fwdQuery ?? {}),
+      ...matchedParams,
+      ...(fwdParams ?? {}),
+    };
+    const reqBody = fwdBody !== undefined ? fwdBody : callerCtx.req?.body;
+    const validated = validateRequestSchema(route.config.schema, mergedQuery, reqBody);
+    if (validated.error) {
+      return { status: 400, error: validated.error };
+    }
+
+    const reqInfo = {
+      id: callerCtx.req?.id,
+      ip: callerCtx.req?.ip ?? '127.0.0.1',
+      method: fwdMethod,
+      path: fwdPath,
+      query: validated.query,
+      body: validated.body,
+      rawBody: callerCtx.req?.rawBody,
+      headers: callerCtx.req?.headers ?? {},
+      cookies: callerCtx.req?.cookies ?? {},
+      session: callerCtx.req?.session,
+    };
+
+    const middlewareFns = getMiddlewareForRoute(this._middleware, route.pattern, fwdMethod);
+    const chainedHandler = buildMiddlewareChain(middlewareFns, route.config.handler);
+    const ctx = this._buildCtx(reqInfo);
+    try {
+      const response = await chainedHandler(ctx);
+      response.status = response.status ?? (response.error ? 400 : 200);
+      return response;
+    } catch (err) {
+      this._log.error(`Forward handler error in ${fwdMethod} ${route.pattern}`, {
+        error: toErrorMessage(err),
+      });
+      const errorMessage =
+        this._mode === 'development'
+          ? err instanceof Error
+            ? err.stack || err.message
+            : String(err)
+          : 'An internal error occurred';
+      return {
+        status: 500,
+        error: { code: ErrorCodes.HANDLER_ERROR, message: errorMessage },
+      };
+    }
+  }
+
+  routesApi() {
+    return this._routes.map((route) => ({
+      method: route.method,
+      pattern: route.pattern,
+      tags: route.config._tags,
+      name: route.config._name,
+      description: route.config._description,
+      mcp: route.config._mcp,
+      schema: route.config.schema,
+    }));
+  }
+
+  buildContextApi(ctx) {
+    return {
+      forward: (args) => this.forward(args, ctx),
+      routes: () => this.routesApi(),
+    };
+  }
+
   async executeRoute(route, reqInfo) {
     if (route.config._parsedRateLimit && this._redis) {
-      const { max, windowSec } = route.config._parsedRateLimit;
-      const rl = await checkRateLimit(this._redis.client, {
-        key: route.config.ratelimit.key,
-        ip: reqInfo.ip,
-        max,
-        windowSec,
-      });
-      if (!rl.allowed) {
-        const retryAfter = Math.max(1, rl.resetAt - Math.ceil(Date.now() / 1000));
+      const checked = await checkRouteRateLimits(this._redis.client, route.config, reqInfo.ip);
+      if (!checked.allowed) {
+        const { policy, result } = checked.selected;
+        const retryAfter = Math.max(1, result.resetAt - Math.ceil(Date.now() / 1000));
         return {
           status: 429,
           error: {
@@ -89,9 +165,9 @@ class ApiRouter {
             message: `Rate limit exceeded. Try again in ${retryAfter} seconds.`,
           },
           headers: {
-            'X-RateLimit-Limit': String(max),
+            'X-RateLimit-Limit': String(policy.max),
             'X-RateLimit-Remaining': '0',
-            'X-RateLimit-Reset': String(rl.resetAt),
+            'X-RateLimit-Reset': String(result.resetAt),
             'Retry-After': String(retryAfter),
           },
         };
@@ -198,15 +274,10 @@ class ApiRouter {
 
     // ── Rate limiting ──
     if (route.config._parsedRateLimit && this._redis) {
-      const { max, windowSec } = route.config._parsedRateLimit;
-      const rl = await checkRateLimit(this._redis.client, {
-        key: route.config.ratelimit.key,
-        ip,
-        max,
-        windowSec,
-      });
-      if (!rl.allowed) {
-        const retryAfter = Math.max(1, rl.resetAt - Math.ceil(Date.now() / 1000));
+      const checked = await checkRouteRateLimits(this._redis.client, route.config, ip);
+      const { policy, result } = checked.selected;
+      if (!checked.allowed) {
+        const retryAfter = Math.max(1, result.resetAt - Math.ceil(Date.now() / 1000));
         sendJson(
           res,
           429,
@@ -217,17 +288,17 @@ class ApiRouter {
             },
           },
           {
-            'X-RateLimit-Limit': String(max),
+            'X-RateLimit-Limit': String(policy.max),
             'X-RateLimit-Remaining': '0',
-            'X-RateLimit-Reset': String(rl.resetAt),
+            'X-RateLimit-Reset': String(result.resetAt),
             'Retry-After': String(retryAfter),
           },
         );
         return true;
       }
-      res.setHeader('X-RateLimit-Limit', String(max));
-      res.setHeader('X-RateLimit-Remaining', String(rl.remaining));
-      res.setHeader('X-RateLimit-Reset', String(rl.resetAt));
+      res.setHeader('X-RateLimit-Limit', String(policy.max));
+      res.setHeader('X-RateLimit-Remaining', String(result.remaining));
+      res.setHeader('X-RateLimit-Reset', String(result.resetAt));
     }
 
     // ── Body parsing control ──

package/server/router/ratelimit.js

@@ -9,11 +9,15 @@ const LIMIT_REGEX = /^(\d+)\s+per\s+(sec|min|hr|day)$/i;
 
 function parseRateLimit(limitStr) {
   if (!limitStr || typeof limitStr !== 'string') {
-    throw new Error(`Invalid rate limit: expected "N per TIMERANGE", got ${JSON.stringify(limitStr)}`);
+    throw new Error(
+      `Invalid rate limit: expected "N per TIMERANGE", got ${JSON.stringify(limitStr)}`,
+    );
   }
   const match = limitStr.match(LIMIT_REGEX);
   if (!match) {
-    throw new Error(`Invalid rate limit: expected "N per TIMERANGE" (sec|min|hr|day), got "${limitStr}"`);
+    throw new Error(
+      `Invalid rate limit: expected "N per TIMERANGE" (sec|min|hr|day), got "${limitStr}"`,
+    );
   }
   const max = parseInt(match[1], 10);
   if (max <= 0) {
@@ -35,7 +39,7 @@ return {count, ttl}
 `;
 
 async function checkRateLimit(redisClient, { key, ip, max, windowSec }) {
-  const redisKey = `rl:${key}:${ip}`;
+  const redisKey = `rl:${key}:${windowSec}:${ip}`;
   const result = await redisClient.eval(LUA_INCR_EXPIRE, 1, redisKey, windowSec);
   const count = result[0];
   const ttl = result[1];
@@ -47,4 +51,36 @@ async function checkRateLimit(redisClient, { key, ip, max, windowSec }) {
   };
 }
 
-export { parseRateLimit, checkRateLimit };
+function configuredPolicies(config) {
+  if (Array.isArray(config._parsedRateLimits)) return config._parsedRateLimits;
+  if (!config._parsedRateLimit) return [];
+  return [{ key: config.ratelimit.key, ...config._parsedRateLimit }];
+}
+
+async function checkRouteRateLimits(redisClient, config, ip) {
+  const policies = configuredPolicies(config);
+  const results = await Promise.all(
+    policies.map(async (policy) => ({
+      policy,
+      result: await checkRateLimit(redisClient, { ...policy, ip }),
+    })),
+  );
+  const denied = results.filter(({ result }) => !result.allowed);
+  const candidates = denied.length > 0 ? denied : results;
+  const selected = candidates.reduce((strictest, candidate) => {
+    if (!strictest) return candidate;
+    if (denied.length > 0) {
+      return candidate.result.resetAt > strictest.result.resetAt ? candidate : strictest;
+    }
+    const candidateRatio = candidate.result.remaining / candidate.policy.max;
+    const strictestRatio = strictest.result.remaining / strictest.policy.max;
+    return candidateRatio < strictestRatio ? candidate : strictest;
+  }, null);
+  return {
+    allowed: denied.length === 0,
+    selected,
+    results,
+  };
+}
+
+export { checkRateLimit, checkRouteRateLimits, parseRateLimit };

package/server/router/routes.js

@@ -60,13 +60,50 @@ function buildRoutesFromModules(entries, { prefix = '', plugin } = {}) {
         );
       }
       if (config.ratelimit) {
-        const rl = config.ratelimit;
-        if (!rl.key || typeof rl.key !== 'string') {
+        const policies = Array.isArray(config.ratelimit) ? config.ratelimit : [config.ratelimit];
+        if (policies.length === 0) {
+          throw new Error(`Route ${method} ${urlPattern} (${filePath}) ratelimit cannot be empty`);
+        }
+        config._parsedRateLimits = policies.map((policy, index) => {
+          if (!policy?.key || typeof policy.key !== 'string') {
+            const suffix = policies.length > 1 ? `[${index}]` : '';
+            throw new Error(
+              `Route ${method} ${urlPattern} (${filePath}) ratelimit${suffix}.key must be a non-empty string`,
+            );
+          }
+          return { key: policy.key, ...parseRateLimit(policy.limit) };
+        });
+        // Preserve the existing internal field for integrations that inspect a
+        // route with one rate-limit policy.
+        config._parsedRateLimit = config._parsedRateLimits[0];
+      }
+      if (config.tags !== undefined) {
+        if (!Array.isArray(config.tags) || !config.tags.every((t) => typeof t === 'string')) {
+          throw new Error(
+            `Route ${method} ${urlPattern} (${filePath}) tags must be an array of strings`,
+          );
+        }
+        config._tags = config.tags;
+      }
+      if (config.name !== undefined) {
+        if (typeof config.name !== 'string') {
+          throw new Error(`Route ${method} ${urlPattern} (${filePath}) name must be a string`);
+        }
+        config._name = config.name;
+      }
+      if (config.description !== undefined) {
+        if (typeof config.description !== 'string') {
           throw new Error(
-            `Route ${method} ${urlPattern} (${filePath}) ratelimit.key must be a non-empty string`,
+            `Route ${method} ${urlPattern} (${filePath}) description must be a string`,
           );
         }
-        config._parsedRateLimit = parseRateLimit(rl.limit);
+        config._description = config.description;
+      }
+      if (config.mcp !== undefined) {
+        if (typeof config.mcp !== 'object' || config.mcp === null) {
+          throw new Error(`Route ${method} ${urlPattern} (${filePath}) mcp must be an object`);
+        }
+        config._mcp = config.mcp;
       }
       routes.push({
         method,