arcway 0.1.26 → 0.1.28

package/server/plugins/manifest.js

@@ -0,0 +1,94 @@
+const ID_PATTERN = /^[a-z][a-z0-9-]*$/;
+const KINDS = new Set(['core', 'feature']);
+const SCOPES = new Set(['global', 'workspace']);
+
+function assertPlainObject(value, label) {
+  if (!value || typeof value !== 'object' || Array.isArray(value)) {
+    throw new Error(`${label} must be an object`);
+  }
+}
+
+function normalizeStringArray(value, label) {
+  if (value === undefined) return [];
+  if (!Array.isArray(value) || value.some((item) => typeof item !== 'string' || item === '')) {
+    throw new Error(`${label} must be an array of non-empty strings`);
+  }
+  return [...value];
+}
+
+function normalizeRequires(value) {
+  if (value === undefined) return {};
+  assertPlainObject(value, 'plugin requires');
+  return { ...value };
+}
+
+function normalizeContributes(value) {
+  if (value === undefined) return {};
+  assertPlainObject(value, 'plugin contributes');
+  return {
+    ...value,
+    tools: value.tools ?? [],
+    routes: value.routes ?? [],
+    jobs: value.jobs ?? [],
+    migrations: value.migrations,
+    ui: value.ui,
+  };
+}
+
+function normalizeLifecycle(value) {
+  if (value === undefined) return {};
+  assertPlainObject(value, 'plugin lifecycle');
+  for (const name of ['onLoad', 'onEnable', 'onDisable']) {
+    if (
+      value[name] !== undefined &&
+      typeof value[name] !== 'function' &&
+      typeof value[name] !== 'string'
+    ) {
+      throw new Error(`plugin lifecycle.${name} must be a function or module export name`);
+    }
+  }
+  return { ...value };
+}
+
+function validateManifest(rawManifest, { packageName } = {}) {
+  assertPlainObject(rawManifest, 'plugin manifest');
+
+  const manifest = {
+    id: rawManifest.id ?? packageName,
+    name: rawManifest.name ?? rawManifest.id ?? packageName,
+    version: rawManifest.version,
+    kind: rawManifest.kind ?? 'feature',
+    scope: rawManifest.scope ?? 'workspace',
+    defaultEnabled: rawManifest.defaultEnabled === true,
+    provides: normalizeStringArray(rawManifest.provides, 'plugin provides'),
+    requires: normalizeRequires(rawManifest.requires),
+    contributes: normalizeContributes(rawManifest.contributes),
+    lifecycle: normalizeLifecycle(rawManifest.lifecycle),
+  };
+
+  if (typeof manifest.id !== 'string' || !ID_PATTERN.test(manifest.id)) {
+    throw new Error('plugin id must be lowercase kebab-case');
+  }
+  if (typeof manifest.name !== 'string' || manifest.name === '') {
+    throw new Error(`plugin ${manifest.id} name must be a non-empty string`);
+  }
+  if (typeof manifest.version !== 'string' || manifest.version === '') {
+    throw new Error(`plugin ${manifest.id} version must be a non-empty string`);
+  }
+  if (!KINDS.has(manifest.kind)) {
+    throw new Error(`plugin ${manifest.id} kind must be core or feature`);
+  }
+  if (!SCOPES.has(manifest.scope)) {
+    throw new Error(`plugin ${manifest.id} scope must be global or workspace`);
+  }
+
+  return manifest;
+}
+
+function requiredCapabilities(requires) {
+  return Object.entries(requires ?? {})
+    .filter(([, requirement]) => requirement !== false && requirement !== null)
+    .map(([capability]) => capability);
+}
+
+export { requiredCapabilities, validateManifest };

package/server/router/api-router.js

@@ -39,6 +39,7 @@ class ApiRouter {
   _appContext;
   _sessionConfig;
   _redis;
+  _pluginManager;
   _routes = [];
   _middleware = [];
   _prefix = '';
@@ -53,6 +54,7 @@ class ApiRouter {
     this._appContext = appContext ?? null;
     this._sessionConfig = sessionConfig ?? null;
     this._redis = appContext?.redis ?? null;
+    this._pluginManager = appContext?.plugins ?? null;
   }
 
   get routes() {
@@ -101,6 +103,7 @@ class ApiRouter {
     const chainedHandler = buildMiddlewareChain(middlewareFns, route.config.handler);
     const ctx = this._buildCtx(reqInfo);
     try {
+      if (route.plugin) this._pluginManager?.injectCapabilities(ctx, route.plugin.requires);
       return await chainedHandler(ctx);
     } catch (err) {
       this._log.error(`Handler error in ${route.method} ${route.pattern}`, {
@@ -133,7 +136,10 @@ class ApiRouter {
     );
   }
 
-  _emitCanonicalLog(ctx, { method, path, route, status, startTime, middlewareNames, error, session }) {
+  _emitCanonicalLog(
+    ctx,
+    { method, path, route, status, startTime, middlewareNames, error, session },
+  ) {
     const durationMs = Date.now() - startTime;
     const dbStats = ctx._dbStats ?? { queries: 0, durationMs: 0 };
     const extra = ctx.log.getCanonicalContext?.() ?? {};
@@ -204,17 +210,22 @@ class ApiRouter {
       });
       if (!rl.allowed) {
         const retryAfter = Math.max(1, rl.resetAt - Math.ceil(Date.now() / 1000));
-        sendJson(res, 429, {
-          error: {
-            code: ErrorCodes.RATE_LIMITED,
-            message: `Rate limit exceeded. Try again in ${retryAfter} seconds.`,
+        sendJson(
+          res,
+          429,
+          {
+            error: {
+              code: ErrorCodes.RATE_LIMITED,
+              message: `Rate limit exceeded. Try again in ${retryAfter} seconds.`,
+            },
+          },
+          {
+            'X-RateLimit-Limit': String(max),
+            'X-RateLimit-Remaining': '0',
+            'X-RateLimit-Reset': String(rl.resetAt),
+            'Retry-After': String(retryAfter),
           },
-        }, {
-          'X-RateLimit-Limit': String(max),
-          'X-RateLimit-Remaining': '0',
-          'X-RateLimit-Reset': String(rl.resetAt),
-          'Retry-After': String(retryAfter),
-        });
+        );
         return true;
       }
       res.setHeader('X-RateLimit-Limit', String(max));
@@ -254,6 +265,7 @@ class ApiRouter {
 
     let response;
     try {
+      if (route.plugin) this._pluginManager?.injectCapabilities(ctx, route.plugin.requires);
       response = await chainedHandler(ctx);
     } catch (err) {
       const errorMsg = toErrorMessage(err);
@@ -265,8 +277,14 @@ class ApiRouter {
             : String(err)
           : 'An internal error occurred';
       this._emitCanonicalLog(ctx, {
-        method, path: pathname, route: route.pattern, status: 500,
-        startTime, middlewareNames, error: errorMsg, session: reqInfo.session,
+        method,
+        path: pathname,
+        route: route.pattern,
+        status: 500,
+        startTime,
+        middlewareNames,
+        error: errorMsg,
+        session: reqInfo.session,
       });
       sendJson(res, 500, {
         error: { code: ErrorCodes.HANDLER_ERROR, message: errorMessage },
@@ -294,8 +312,13 @@ class ApiRouter {
     const statusCode = response.status ?? (response.error ? 400 : 200);
     await serializeResponse(res, response, responseHeaders, statusCode);
     this._emitCanonicalLog(ctx, {
-      method, path: pathname, route: route.pattern, status: statusCode,
-      startTime, middlewareNames, session: response.session !== void 0 ? response.session : reqInfo.session,
+      method,
+      path: pathname,
+      route: route.pattern,
+      status: statusCode,
+      startTime,
+      middlewareNames,
+      session: response.session !== void 0 ? response.session : reqInfo.session,
     });
 
     return true;
@@ -331,10 +354,12 @@ class ApiRouter {
   }
 
   async _discover() {
-    const [routes, middleware] = await Promise.all([
+    const [routes, middleware, pluginRoutes] = await Promise.all([
       discoverRoutes(this._config.dir),
       discoverMiddleware(this._config.dir),
+      this._pluginManager?.discoverRoutes?.() ?? [],
     ]);
+    routes.push(...pluginRoutes);
 
     applyPrefix(routes, middleware, this._prefix);
 

package/server/router/routes.js

@@ -36,11 +36,21 @@ function matchPattern(items, pathname) {
   return null;
 }
 const compilePattern = compileRoutePattern;
-async function discoverRoutes(apiDir) {
+function normalizeRoutePrefix(rawPrefix) {
+  if (!rawPrefix) return '';
+  return ('/' + rawPrefix.replace(/^\/+|\/+$/g, '')).replace(/^\/$/, '');
+}
+function prefixRoutePattern(pattern, prefix) {
+  const normalized = normalizeRoutePrefix(prefix);
+  if (!normalized) return pattern;
+  if (pattern === '/') return normalized;
+  return normalized + pattern;
+}
+async function discoverRoutes(apiDir, { prefix = '', plugin } = {}) {
   const entries = await discoverModules(apiDir, { recursive: true, label: 'route file' });
   const routes = [];
   for (const { filePath, relativePath, module } of entries) {
-    const urlPattern = filePathToPattern(relativePath);
+    const urlPattern = prefixRoutePattern(filePathToPattern(relativePath), prefix);
     const { regex, paramNames, catchAllParam } = compilePattern(urlPattern);
     for (const method of HTTP_METHODS) {
       const config = module[method];
@@ -66,6 +76,7 @@ async function discoverRoutes(apiDir) {
         paramNames,
         ...(catchAllParam ? { catchAllParam } : {}),
         config,
+        ...(plugin ? { plugin } : {}),
         ...(method === 'GET' && typeof config.ws === 'function' ? { wsEnabled: true } : {}),
       });
     }
@@ -100,5 +111,6 @@ export {
   matchPattern,
   matchRoute,
   matchRoutesByPath,
+  prefixRoutePattern,
   sortBySpecificity,
 };

package/server/server.js

@@ -1,12 +1,24 @@
 import { createServer } from 'node:http';
-function createHttpServer(handler) {
+function createHttpServer(handler, logger) {
   const server = createServer(handler);
   const connections = new Set();
   server.on('connection', (socket) => {
     connections.add(socket);
+    // A peer that RSTs an idle keep-alive socket (or one mid/after response)
+    // makes Node emit 'error' on the socket; with no listener that throws an
+    // unhandled error and kills the whole process. ECONNRESET/EPIPE are normal
+    // peer disconnects — swallow them (debug only), never rethrow.
+    socket.on('error', (err) => {
+      logger?.debug?.('client socket error', { code: err?.code });
+    });
     socket.once('close', () => connections.delete(socket));
   });
   server.__trackedConnections = connections;
+  // Malformed request line / oversized headers surface as 'clientError'; destroy
+  // the offending socket instead of letting the HTTP parser crash the process.
+  server.on('clientError', (_err, socket) => {
+    if (socket.writable) socket.destroy();
+  });
   return server;
 }
 function listen(server, port, host = '0.0.0.0') {

package/server/session/index.js

@@ -2,6 +2,7 @@ import { sealData, unsealData } from 'iron-session';
 import { serialize as serializeCookie } from 'cookie';
 import { SESSION_COOKIE_MAX_AGE_SKEW } from '../constants.js';
 import { toErrorMessage } from '../helpers.js';
+import { normalizeDurationSeconds } from '../config/duration.js';
 const MIN_PASSWORD_LENGTH = 32;
 function resolveSessionConfig(config, mode) {
   if (!config.password) {
@@ -27,7 +28,10 @@ function resolveSessionConfig(config, mode) {
   return {
     password: config.password,
     cookieName: config.cookieName ?? 'arcway.session',
-    ttl: config.ttl ?? 14 * 24 * 3600,
+    ttl:
+      config.ttl === undefined
+        ? 14 * 24 * 3600
+        : normalizeDurationSeconds(config.ttl, 'session.ttl'),
     mode: mode ?? 'production',
     cookie: {
       httpOnly: config.cookie?.httpOnly ?? true,

package/server/static/index.js

@@ -4,11 +4,13 @@ import { serveStaticAsset, servePublicFile } from '../pages/static.js';
 
 class StaticRouter {
   outDir;
+  resolveOutDir;
   publicDir;
   hasPublicDir;
 
-  constructor({ outDir, publicDir }) {
+  constructor({ outDir, resolveOutDir, publicDir }) {
     this.outDir = outDir;
+    this.resolveOutDir = resolveOutDir ?? null;
     this.publicDir = publicDir;
     this.hasPublicDir = publicDir ? fs.existsSync(publicDir) : false;
   }
@@ -21,7 +23,8 @@ class StaticRouter {
 
     // Built bundles: /static/client/*
     if (pathname.startsWith('/static/client/')) {
-      return serveStaticAsset(pathname, res, this.outDir, req);
+      const outDir = this.resolveOutDir ? this.resolveOutDir() : this.outDir;
+      return serveStaticAsset(pathname, res, outDir, req);
     }
 
     // Public files: /* (fallback)

package/server/web-server.js

@@ -97,7 +97,7 @@ class WebServer {
         });
     };
 
-    this.server = createHttpServer(requestHandler);
+    this.server = createHttpServer(requestHandler, log);
 
     // ── WebSocket upgrade ──
     this.server.on('upgrade', async (req, socket, head) => {
@@ -141,8 +141,8 @@ class WebServer {
     // Query string
     req.query = parseQuery(req.url ?? '/');
 
-    // Body (POST/PUT/PATCH only)
-    if (method === 'POST' || method === 'PUT' || method === 'PATCH') {
+    // Body (methods that may carry a request payload)
+    if (method === 'POST' || method === 'PUT' || method === 'PATCH' || method === 'DELETE') {
       req.rawBody = await readBody(req, maxBodySize);
       const parsed = parseBody(req.rawBody, req.headers['content-type'] ?? '');
       if (parsed !== undefined) req.body = parsed;

package/server/ws/realtime.js

@@ -6,6 +6,19 @@ import { parseCookiesFromHeader, resolveSession, flattenHeaders } from '../sessi
 import { toErrorMessage } from '../helpers.js';
 import { buildContext } from '../context.js';
 import { registerWsServer, unregisterWsServer } from './registry.js';
+
+function normalizeWsMsg(wsMsg) {
+  const rawPath = wsMsg.path;
+  const url = new URL(rawPath, 'http://localhost');
+  const query = Object.fromEntries(url.searchParams.entries());
+
+  return {
+    ...wsMsg,
+    path: rawPath,
+    pathname: url.pathname,
+    query: { ...query, ...(wsMsg.query ?? {}) },
+  };
+}
 function createRealtimeServer(options) {
   const {
     server,
@@ -72,7 +85,7 @@ function createRealtimeServer(options) {
     return {
       id: randomUUID(),
       method: wsMsg.method,
-      path: wsMsg.path,
+      path: wsMsg.pathname ?? wsMsg.path,
       query: mergedQuery,
       body: wsMsg.body,
       headers: client.headers,
@@ -98,6 +111,7 @@ function createRealtimeServer(options) {
     }
   }
   async function handleSubscribe(client, wsMsg) {
+    wsMsg = wsMsg.pathname ? wsMsg : normalizeWsMsg(wsMsg);
     const path = wsMsg.path;
     if (client.subscriptions.has(path)) {
       sendToClient(client.ws, {
@@ -106,7 +120,7 @@ function createRealtimeServer(options) {
       });
       return;
     }
-    const matched = matchRoute(routes, 'GET', path);
+    const matched = matchRoute(routes, 'GET', wsMsg.pathname);
     if (!matched) {
       sendToClient(client.ws, {
         path,
@@ -173,8 +187,9 @@ function createRealtimeServer(options) {
     client.subscriptions.delete(path);
   }
   async function handleMethodCall(client, wsMsg) {
+    wsMsg = wsMsg.pathname ? wsMsg : normalizeWsMsg(wsMsg);
     const { path, method } = wsMsg;
-    const matched = matchRoute(routes, method, path);
+    const matched = matchRoute(routes, method, wsMsg.pathname);
     if (!matched) {
       sendToClient(client.ws, {
         path,
@@ -258,16 +273,17 @@ function createRealtimeServer(options) {
         });
         return;
       }
-      const method = parsed.method.toUpperCase();
+      const normalized = normalizeWsMsg(parsed);
+      const method = normalized.method.toUpperCase();
       if (method === 'SUBSCRIBE') {
-        await handleSubscribe(client, { ...parsed, method });
+        await handleSubscribe(client, { ...normalized, method });
       } else if (method === 'UNSUBSCRIBE') {
-        await handleUnsubscribe(client, { ...parsed, method });
+        await handleUnsubscribe(client, { ...normalized, method });
       } else if (['GET', 'POST', 'PUT', 'PATCH', 'DELETE'].includes(method)) {
-        await handleMethodCall(client, { ...parsed, method });
+        await handleMethodCall(client, { ...normalized, method });
       } else {
         sendToClient(ws, {
-          path: parsed.path,
+          path: normalized.path,
           error: { code: 'INVALID_METHOD', message: `Unsupported method: ${method}` },
         });
       }

package/server/ws/ws-router.js

@@ -5,6 +5,19 @@ import { parseCookies, resolveSession, flattenHeaders } from '../session/helpers
 import { getMiddlewareForRoute } from '../router/middleware.js';
 import { toErrorMessage } from '../helpers.js';
 
+function normalizeWsMsg(wsMsg) {
+  const rawPath = wsMsg.path;
+  const url = new URL(rawPath, 'http://localhost');
+  const query = Object.fromEntries(url.searchParams.entries());
+
+  return {
+    ...wsMsg,
+    path: rawPath,
+    pathname: url.pathname,
+    query: { ...query, ...(wsMsg.query ?? {}) },
+  };
+}
+
 class WsRouter {
   _apiRouter;
   _log;
@@ -149,16 +162,17 @@ class WsRouter {
       return;
     }
 
-    const method = parsed.method.toUpperCase();
+    const normalized = normalizeWsMsg(parsed);
+    const method = normalized.method.toUpperCase();
     if (method === 'SUBSCRIBE') {
-      await this._handleSubscribe(client, { ...parsed, method });
+      await this._handleSubscribe(client, { ...normalized, method });
     } else if (method === 'UNSUBSCRIBE') {
-      await this._handleUnsubscribe(client, { ...parsed, method });
+      await this._handleUnsubscribe(client, { ...normalized, method });
     } else if (['GET', 'POST', 'PUT', 'PATCH', 'DELETE'].includes(method)) {
-      await this._handleMethodCall(client, { ...parsed, method });
+      await this._handleMethodCall(client, { ...normalized, method });
     } else {
       this._send(client, {
-        path: parsed.path,
+        path: normalized.path,
         error: { code: 'INVALID_METHOD', message: `Unsupported method: ${method}` },
       });
     }
@@ -167,6 +181,7 @@ class WsRouter {
   // ── Subscribe / Unsubscribe ──
 
   async _handleSubscribe(client, wsMsg) {
+    wsMsg = wsMsg.pathname ? wsMsg : normalizeWsMsg(wsMsg);
     const msgPath = wsMsg.path;
     if (client.subscriptions.has(msgPath)) {
       this._send(client, {
@@ -176,7 +191,7 @@ class WsRouter {
       return;
     }
 
-    const matched = this._apiRouter.findRoute('GET', msgPath);
+    const matched = this._apiRouter.findRoute('GET', wsMsg.pathname);
     if (!matched) {
       this._send(client, {
         path: msgPath,
@@ -296,8 +311,9 @@ class WsRouter {
   // ── Method calls (GET/POST/PUT/PATCH/DELETE) ──
 
   async _handleMethodCall(client, wsMsg) {
+    wsMsg = wsMsg.pathname ? wsMsg : normalizeWsMsg(wsMsg);
     const { path: msgPath, method } = wsMsg;
-    const matched = this._apiRouter.findRoute(method, msgPath);
+    const matched = this._apiRouter.findRoute(method, wsMsg.pathname);
 
     if (!matched) {
       this._send(client, {
@@ -330,7 +346,7 @@ class WsRouter {
     return {
       id: randomUUID(),
       method: wsMsg.method,
-      path: wsMsg.path,
+      path: wsMsg.pathname ?? wsMsg.path,
       query: { ...(wsMsg.query ?? {}), ...params },
       body: wsMsg.body,
       headers: client.headers,