arcway 0.3.2 → 0.4.0

package/package.json

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

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/router/api-router.js

@@ -71,6 +71,76 @@ 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;

package/server/router/routes.js

@@ -68,6 +68,38 @@ function buildRoutesFromModules(entries, { prefix = '', plugin } = {}) {
         }
         config._parsedRateLimit = parseRateLimit(rl.limit);
       }
+      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}) description must be a string`,
+          );
+        }
+        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,
         pattern: urlPattern,