arcway 0.1.12 → 0.1.14

package/README.md

@@ -120,7 +120,7 @@ export default {
   server: {
     port: 3000,
     shutdownTimeoutMs: 10_000,
-    maxBodySize: 1_048_576, // 1 MB
+    maxBodySize: 26_214_400, // 25 MB
   },
   api: {
     pathPrefix: '',        // Prefix all API routes (e.g., '/api')

package/client/head.js

@@ -137,4 +137,4 @@ function renderHeadToString(headData) {
   return parts.join('\n');
 }
 
-export { Head, clearSSRHeadData, extractHeadChildren, renderHeadToString, setSSRHeadData };
+export { Head, clearSSRHeadData, renderHeadToString, setSSRHeadData };

package/client/provider.js

@@ -3,7 +3,7 @@ import { WsManager } from './ws.js';
 
 const SOLO_CTX_KEY = '__provider_context__';
 const WS_CTX_KEY = '__ws_context__';
-const DEFAULT_CONFIG = { pathPrefix: '' };
+const DEFAULT_CONFIG = { pathPrefix: '/api' };
 
 const ApiContext = (globalThis[SOLO_CTX_KEY] ??= createContext(DEFAULT_CONFIG));
 const WsContext = (globalThis[WS_CTX_KEY] ??= createContext(null));
@@ -18,8 +18,25 @@ function useWsManager() {
 
 const useSoloContext = useApiContext;
 
-function ApiProvider({ children, pathPrefix = '', headers, wsUrl }) {
-  const config = useMemo(() => ({ pathPrefix, headers, wsUrl }), [pathPrefix, headers, wsUrl]);
+function toWsProtocol(loc, wsPath) {
+  const proto = loc.protocol === 'https:' ? 'wss:' : 'ws:';
+  return `${proto}//${loc.host}${wsPath}`;
+}
+
+function resolveWsUrl(input) {
+  if (typeof window === 'undefined') return null;
+  if (!input) return toWsProtocol(window.location, '/ws');
+  if (/^wss?:\/\//.test(input)) return input;
+  if (input.startsWith('/')) return toWsProtocol(window.location, input);
+  return input;
+}
+
+function ApiProvider({ children, pathPrefix = '/api', headers, wsUrl }) {
+  const resolvedWsUrl = useMemo(() => resolveWsUrl(wsUrl), [wsUrl]);
+  const config = useMemo(
+    () => ({ pathPrefix, headers, wsUrl: resolvedWsUrl }),
+    [pathPrefix, headers, resolvedWsUrl],
+  );
 
   const wsManagerRef = useRef(null);
   const wsManager = useMemo(() => {
@@ -27,11 +44,11 @@ function ApiProvider({ children, pathPrefix = '', headers, wsUrl }) {
       wsManagerRef.current.disconnect();
       wsManagerRef.current = null;
     }
-    if (!wsUrl || typeof window === 'undefined') return null;
-    const manager = new WsManager({ url: wsUrl });
+    if (!resolvedWsUrl) return null;
+    const manager = new WsManager({ url: resolvedWsUrl });
     wsManagerRef.current = manager;
     return manager;
-  }, [wsUrl]);
+  }, [resolvedWsUrl]);
 
   useEffect(() => {
     if (wsManager) {
@@ -50,4 +67,12 @@ function ApiProvider({ children, pathPrefix = '', headers, wsUrl }) {
 const Provider = ApiProvider;
 const SoloProvider = ApiProvider;
 
-export { ApiProvider, Provider, SoloProvider, useApiContext, useSoloContext, useWsManager };
+export {
+  ApiProvider,
+  Provider,
+  SoloProvider,
+  resolveWsUrl,
+  useApiContext,
+  useSoloContext,
+  useWsManager,
+};

package/client/router.js

@@ -51,7 +51,9 @@ function useRouter() {
         if (typeof window !== 'undefined') window.location.reload();
       },
     }),
-    [ctx.pathname, ctx.params, ctx.navigate],
+    // queryVersion bumps on every query-only navigation or same-path popstate,
+    // so memoised consumers (notably `useSearchParams`) re-read the URL.
+    [ctx.pathname, ctx.params, ctx.navigate, ctx.queryVersion],
   );
 }
 
@@ -86,6 +88,10 @@ function Router({
   });
   const [isNavigating, setIsNavigating] = useState(false);
   const [isPending, startTransition] = useTransition();
+  // Bumped on query-only navigations (both push/replace and popstate) so that
+  // `useRouter`/`useSearchParams` consumers re-render even though pathname and
+  // params are unchanged.
+  const [queryVersion, setQueryVersion] = useState(0);
   const manifestRef = useRef(null);
 
   useEffect(() => {
@@ -114,7 +120,28 @@ function Router({
     async (to, options) => {
       const scroll = options?.scroll !== false;
       const replace = options?.replace === true;
-      if (to === pathname) return;
+
+      // `matchClientRoute` only knows how to match pathnames, so any query
+      // string has to be stripped before the lookup. Splitting also lets us
+      // special-case same-path/different-query navigations as a history-only
+      // update — no bundle loading, no scroll reset, no full reload.
+      const qIdx = to.indexOf('?');
+      const pathOnly = qIdx === -1 ? to : to.slice(0, qIdx);
+      const search = qIdx === -1 ? '' : to.slice(qIdx);
+      const currentSearch =
+        typeof window !== 'undefined' ? window.location.search : '';
+
+      if (pathOnly === pathname && search === currentSearch) return;
+
+      if (pathOnly === pathname) {
+        if (replace) {
+          window.history.replaceState(null, '', to);
+        } else {
+          window.history.pushState(null, '', to);
+        }
+        setQueryVersion((v) => v + 1);
+        return;
+      }
 
       const manifest = manifestRef.current;
       if (!manifest) {
@@ -122,7 +149,7 @@ function Router({
         return;
       }
 
-      const matched = matchClientRoute(manifest, to);
+      const matched = matchClientRoute(manifest, pathOnly);
       if (!matched) {
         window.location.href = to;
         return;
@@ -137,7 +164,7 @@ function Router({
 
       const targetLoadings = await loadLoadingComponents(matched.route);
       if (targetLoadings.length > 0) {
-        setPathname(to);
+        setPathname(pathOnly);
         setPageState((prev) => ({
           ...prev,
           loadings: targetLoadings,
@@ -146,13 +173,14 @@ function Router({
       }
 
       try {
-        const loaded = await loadPage(manifest, to);
+        const loaded = await loadPage(manifest, pathOnly);
         if (!loaded) {
           window.location.href = to;
           return;
         }
 
-        applyLoaded(loaded, to);
+        applyLoaded(loaded, pathOnly);
+        if (search !== currentSearch) setQueryVersion((v) => v + 1);
 
         if (scroll) {
           window.scrollTo(0, 0);
@@ -168,11 +196,20 @@ function Router({
   useEffect(() => {
     async function onPopState() {
       const newPath = window.location.pathname;
+
+      // Same-path back/forward is a query-only history step (or identical URL);
+      // skip the page load and just force re-render of search-param readers.
+      if (newPath === pathname) {
+        setQueryVersion((v) => v + 1);
+        return;
+      }
+
       const manifest = manifestRef.current;
 
       if (!manifest) {
         setPathname(newPath);
         setPageState((prev) => ({ ...prev, params: {} }));
+        setQueryVersion((v) => v + 1);
         return;
       }
 
@@ -180,6 +217,7 @@ function Router({
         const loaded = await loadPage(manifest, newPath);
         if (loaded) {
           applyLoaded(loaded, newPath);
+          setQueryVersion((v) => v + 1);
         } else {
           window.location.reload();
         }
@@ -190,7 +228,7 @@ function Router({
 
     window.addEventListener('popstate', onPopState);
     return () => window.removeEventListener('popstate', onPopState);
-  }, [applyLoaded]);
+  }, [pathname, applyLoaded]);
 
   const { component: PageComponent, layouts, loadings, params } = pageState;
 
@@ -228,6 +266,7 @@ function Router({
         pathname,
         params,
         navigate: navigateToPage,
+        queryVersion,
       },
     },
     content,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "arcway",
-  "version": "0.1.12",
+  "version": "0.1.14",
   "description": "A convention-based framework for building modular monoliths with strict domain boundaries.",
   "license": "MIT",
   "type": "module",
@@ -30,6 +30,9 @@
   },
   "scripts": {
     "test": "vitest run --project=unit",
+    "test:watch": "VITEST_MAX_WORKERS=2 vitest --project=unit",
+    "test:serial": "VITEST_MAX_WORKERS=1 vitest run --project=unit",
+    "test:coverage": "vitest run --project=unit --coverage",
     "test:storybook": "TMPDIR=~/tmp PLAYWRIGHT_BROWSERS_PATH=~/.cache/playwright vitest run --project=storybook",
     "test:all": "TMPDIR=~/tmp PLAYWRIGHT_BROWSERS_PATH=~/.cache/playwright vitest run",
     "format": "prettier --write 'server/**/*.js' 'client/**/*.js' 'tests/**/*.js'",

package/server/boot/index.js

@@ -1,16 +1,10 @@
 import { makeConfig } from '../config/loader.js';
-import { createDB } from '../db/index.js';
-import Redis from '../redis/index.js';
-import Events from '../events/index.js';
+import { createInfrastructure, destroyInfrastructure } from './infrastructure.js';
 import { EventHandler } from '../events/handler.js';
 import { JobRunner } from '../jobs/runner.js';
-import Logger from '../logger/index.js';
+import { WorkerPool } from '../jobs/worker-pool.js';
 import { loadEnvFiles } from '../env.js';
 import { McpRouter } from '../mcp/index.js';
-import Queue from '../queue/index.js';
-import Cache from '../cache/index.js';
-import Files from '../files/index.js';
-import { Mail } from '../mail/index.js';
 import WebServer from '../web-server.js';
 import { FileWatcher } from '../filewatcher/index.js';
 import { ApiRouter } from '../router/api-router.js';
@@ -27,30 +21,13 @@ async function boot(options) {
   const envFiles = loadEnvFiles(rootDir, mode);
   const config = await makeConfig(rootDir, { overrides: options.configOverrides, mode });
 
-  const log = new Logger(config.logger);
+  const infrastructure = await createInfrastructure(config, { runMigrations: true });
+  const { db, redis, queue, cache, files, mail, events, log } = infrastructure;
+
   const mcpRouter = new McpRouter(config.mcp, { log });
 
   if (envFiles.length > 0) log.info('Env files loaded', { envFiles });
 
-  const db = await createDB(config.database, { log });
-  await db.runMigrations();
-
-  const redis = new Redis(config.redis, { log });
-  await redis.connect();
-
-  const queue = new Queue(config.queue, { db, redis, log });
-  await queue.init();
-
-  const cache = new Cache(config.cache, { redis, log });
-  await cache.init();
-
-  const files = new Files(config.files, { log });
-  await files.init();
-
-  const mail = new Mail(config.mail, { db, log, queue });
-
-  const events = new Events(config.events, { redis, log });
-
   const eventHandler = new EventHandler(config.events, {
     events,
     log,
@@ -58,7 +35,28 @@ async function boot(options) {
   });
   await eventHandler.init();
 
-  const jobRunner = new JobRunner(config.jobs, { db, queue, cache, files, mail, events, log });
+  // Workers rebuild their own infrastructure from a JSON-safe config snapshot,
+  // so anything non-serializable on the main-thread config (streams, functions)
+  // must not ride through workerData. makeConfig already yields plain objects.
+  const workerPool =
+    config.jobs?.workerPoolSize > 0
+      ? new WorkerPool({
+          size: config.jobs.workerPoolSize,
+          workerData: { config },
+          defaultTimeoutMs: config.jobs?.staleTimeoutMs ?? null,
+        })
+      : null;
+
+  const jobRunner = new JobRunner(config.jobs, {
+    db,
+    queue,
+    cache,
+    files,
+    mail,
+    events,
+    log,
+    workerPool,
+  });
   await jobRunner.init();
 
   const fileWatcher = new FileWatcher(rootDir, { log });
@@ -115,13 +113,12 @@ async function boot(options) {
 
   const shutdown = async () => {
     await jobRunner.shutdown();
+    if (workerPool) await workerPool.shutdown();
     await pagesRouter.close();
     await apiRouter.close();
     await webServer.close();
     await fileWatcher.close();
-    await events.disconnect();
-    await redis.disconnect();
-    await db.destroy();
+    await destroyInfrastructure(infrastructure);
     await mcpRouter.cleanup(rootDir);
   };
 

package/server/boot/infrastructure.js

@@ -0,0 +1,47 @@
+import { createDB } from '../db/index.js';
+import Redis from '../redis/index.js';
+import Queue from '../queue/index.js';
+import Cache from '../cache/index.js';
+import Files from '../files/index.js';
+import { Mail } from '../mail/index.js';
+import Events from '../events/index.js';
+import Logger from '../logger/index.js';
+
+// Shared service construction for both the main-thread boot path and per-job
+// worker threads (see server/jobs/worker-entry.js). Workers call this with
+// `runMigrations: false` — only the main process should touch schema.
+async function createInfrastructure(config, { runMigrations = false } = {}) {
+  const log = new Logger(config.logger);
+
+  const db = await createDB(config.database, { log });
+  if (runMigrations) await db.runMigrations();
+
+  const redis = new Redis(config.redis, { log });
+  await redis.connect();
+
+  const queue = new Queue(config.queue, { db, redis, log });
+  await queue.init();
+
+  const cache = new Cache(config.cache, { redis, log });
+  await cache.init();
+
+  const files = new Files(config.files, { log });
+  await files.init();
+
+  const mail = new Mail(config.mail, { db, log, queue });
+
+  const events = new Events(config.events, { redis, log });
+
+  return { db, redis, queue, cache, files, mail, events, log };
+}
+
+async function destroyInfrastructure(services) {
+  if (!services) return;
+  // Order matches boot/index.js teardown: events → redis → db. Mail/queue/
+  // cache/files share redis/db and do not own independent connections.
+  await services.events?.disconnect?.();
+  await services.redis?.disconnect?.();
+  await services.db?.destroy?.();
+}
+
+export { createInfrastructure, destroyInfrastructure };

package/server/config/modules/jobs.js

@@ -1,5 +1,14 @@
+import os from 'node:os';
 import path from 'node:path';
 
+// Leave one core free for the main thread (dispatch/polling/HTTP). 0 disables
+// worker threads entirely and runs handlers inline on the main thread.
+function defaultWorkerPoolSize() {
+  const cores =
+    typeof os.availableParallelism === 'function' ? os.availableParallelism() : os.cpus().length;
+  return Math.max(1, cores - 1);
+}
+
 const DEFAULTS = {
   enabled: true,
   backoffMs: 1000,
@@ -14,6 +23,7 @@ function resolve(config, { rootDir } = {}) {
   if (jobs.dir && !path.isAbsolute(jobs.dir)) {
     jobs.dir = path.resolve(rootDir, jobs.dir);
   }
+  if (jobs.workerPoolSize === undefined) jobs.workerPoolSize = defaultWorkerPoolSize();
   return { ...config, jobs };
 }
 

package/server/config/modules/server.js

@@ -1,7 +1,7 @@
 const DEFAULTS = {
   host: '0.0.0.0',
   port: 3000,
-  maxBodySize: 1024 * 1024,
+  maxBodySize: 25 * 1024 * 1024,
   shutdownTimeoutMs: 10000,
   trustProxy: false,
 };

package/server/context.js

@@ -64,4 +64,4 @@ function buildContext(appContext, extras) {
   return ctx;
 }
 
-export { buildContext, trackDb };
+export { buildContext };

package/server/graphql/index.js

@@ -2,9 +2,7 @@ import { discoverGraphQL } from './discovery.js';
 import { mergeGraphQLSchemas, mergeGraphQLResolvers } from './merge.js';
 import { createLoaderFactory } from './loaders.js';
 import { createGraphQLHandler } from './handler.js';
-import { attachGraphQLSubscriptions } from './subscriptions.js';
 export {
-  attachGraphQLSubscriptions,
   createGraphQLHandler,
   createLoaderFactory,
   discoverGraphQL,

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

@@ -1,7 +1,7 @@
-import { buildContext } from '../../context.js';
 import { validateEnqueue, toError, calculateBackoff } from '../queue.js';
 import { checkDbThroughput } from '../throughput.js';
 import LeaseManager from './lease.js';
+import { runHandler } from './run-handler.js';
 const DEFAULT_STALE_TIMEOUT_MS = 5 * 60 * 1e3;
 class KnexJobQueue {
   db;
@@ -11,12 +11,14 @@ class KnexJobQueue {
   registered = new Map();
   _size = 0;
   leaseManager;
+  workerPool;
   constructor(db, options) {
     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 });
+    this.workerPool = options?.workerPool ?? null;
   }
   /** Create the jobs table if it doesn't exist. Must be called before use. */
   async init() {
@@ -39,9 +41,9 @@ class KnexJobQueue {
     await this.leaseManager.init();
     await this.syncSize();
   }
-  register(domain, definition, store) {
+  register(domain, definition, store, filePath) {
     const qualifiedName = `${domain}/${definition.name}`;
-    this.registered.set(qualifiedName, { domain, definition, store });
+    this.registered.set(qualifiedName, { domain, definition, store, filePath });
   }
   async enqueue(qualifiedName, payload, options) {
     const { reg, validatedPayload, maxRetries, delay } = validateEnqueue(
@@ -163,8 +165,7 @@ class KnexJobQueue {
 
     try {
       console.log(`[job] ${qualifiedName} attempt ${attempt}/${maxAttempts}`);
-      const ctx = buildContext(reg.store, { payload });
-      await reg.definition.handler(ctx);
+      await runHandler(reg, payload, this.workerPool);
       console.log(`[job] ${qualifiedName} completed`);
       await this._updateJob(jobId, { status: 'completed', attempt });
       this._size--;

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

@@ -1,7 +1,7 @@
-import { buildContext } from '../../context.js';
 import { validateEnqueue, toError, calculateBackoff } from '../queue.js';
 import { MemoryThroughputTracker } from '../throughput.js';
 import LeaseManager from './lease.js';
+import { runHandler } from './run-handler.js';
 
 class JobDispatcher {
   queue = [];
@@ -9,15 +9,17 @@ class JobDispatcher {
   backoffMs;
   throughputTracker = new MemoryThroughputTracker();
   leaseManager;
+  workerPool;
 
   constructor(options) {
     this.backoffMs = options?.backoffMs ?? 1000;
     this.leaseManager = new LeaseManager(null);
+    this.workerPool = options?.workerPool ?? null;
   }
 
-  register(domain, definition, store) {
+  register(domain, definition, store, filePath) {
     const qualifiedName = `${domain}/${definition.name}`;
-    this.registered.set(qualifiedName, { domain, definition, store });
+    this.registered.set(qualifiedName, { domain, definition, store, filePath });
   }
 
   async enqueue(qualifiedName, payload, options) {
@@ -89,8 +91,7 @@ class JobDispatcher {
 
     try {
       console.log(`[job] ${qualifiedName} attempt ${job.attempt}/${maxAttempts}`);
-      const ctx = buildContext(reg.store, { payload: job.payload });
-      await reg.definition.handler(ctx);
+      await runHandler(reg, job.payload, this.workerPool);
       job.status = 'completed';
       console.log(`[job] ${qualifiedName} completed`);
       this.throughputTracker.record(qualifiedName);

package/server/jobs/drivers/run-handler.js

@@ -0,0 +1,22 @@
+import { buildContext } from '../../context.js';
+
+// Dispatch a job handler either inline (main thread, legacy / tests / continuous
+// jobs) or through the WorkerPool. The worker builds its own ctx from the
+// workerData config snapshot and calls handler(ctx) — see worker-entry.js.
+// We only route through the pool when both a pool *and* a filePath are
+// available; system jobs register without a filePath and stay inline on
+// purpose (they use namespaced services that don't round-trip through
+// workerData).
+async function runHandler(reg, payload, workerPool) {
+  if (workerPool && reg.filePath) {
+    await workerPool.run(
+      { handlerPath: reg.filePath, payload, withContext: true },
+      { timeoutMs: reg.definition.staleTimeout },
+    );
+    return;
+  }
+  const ctx = buildContext(reg.store, { payload });
+  await reg.definition.handler(ctx);
+}
+
+export { runHandler };

package/server/jobs/runner.js

@@ -21,7 +21,13 @@ async function discoverJobs(jobsDir) {
     if (!job.name) {
       job.name = relativePath.replace(/\\/g, '/').replace(/\.js$/, '');
     }
-    jobs.push({ definition: job, fileName: name, cooldownMs: job.cooldownMs, staleTimeout: job.staleTimeout });
+    jobs.push({
+      definition: job,
+      fileName: name,
+      filePath,
+      cooldownMs: job.cooldownMs,
+      staleTimeout: job.staleTimeout,
+    });
   }
   return jobs;
 }
@@ -39,10 +45,14 @@ class JobRunner {
   _stopped = false;
   _lastEnqueuedMinute = new Map();
 
-  constructor(config, { db, queue, cache, files, mail, events, log } = {}) {
+  constructor(config, { db, queue, cache, files, mail, events, log, workerPool } = {}) {
     this._config = config;
     this._log = log;
-    this._dispatcher = new JobDispatcher({ backoffMs: config?.backoffMs, staleTimeoutMs: config?.staleTimeoutMs });
+    this._dispatcher = new JobDispatcher({
+      backoffMs: config?.backoffMs,
+      staleTimeoutMs: config?.staleTimeoutMs,
+      workerPool,
+    });
     this._appContext = { db, queue, cache, files, mail, events, log };
   }
 
@@ -62,10 +72,11 @@ class JobRunner {
     const jobsDir = this._config?.dir;
     if (!jobsDir) return;
 
-    // Discover and register user jobs
+    // Discover and register user jobs. `filePath` is captured so the
+    // dispatcher can dynamic-import the handler inside a worker thread.
     const discovered = await discoverJobs(jobsDir);
-    for (const { definition, fileName } of discovered) {
-      this._dispatcher.register('app', definition, this._appContext);
+    for (const { definition, fileName, filePath } of discovered) {
+      this._dispatcher.register('app', definition, this._appContext, filePath);
       this._jobs.push({
         jobName: definition.name,
         fileName,