arcway 0.1.0

package/server/pages/pages-router.js

@@ -0,0 +1,78 @@
+import { buildPages } from './build.js';
+import { createPagesHandler } from './handler.js';
+import { createPagesWatcher } from './watcher.js';
+
+class PagesRouter {
+  config;
+  rootDir;
+  log;
+  fileWatcher;
+  handler = null;
+  watcher = null;
+
+  constructor(config, { rootDir, log, fileWatcher, appContext }) {
+    this.config = config;
+    this.rootDir = rootDir;
+    this.log = log;
+    this.fileWatcher = fileWatcher ?? null;
+    this.appContext = appContext ?? null;
+  }
+
+  async init() {
+    const { config, rootDir, log, fileWatcher } = this;
+    const isDev = fileWatcher !== null;
+
+    let initialClientMetafile;
+    if (isDev) {
+      try {
+        const result = await buildPages({
+          rootDir,
+          pagesDir: config.pages.dir,
+          fonts: config.pages?.fonts,
+          minify: false,
+          devMode: true,
+        });
+        initialClientMetafile = result.clientMetafile;
+      } catch (err) {
+        log.error('Pages build failed', { error: String(err) });
+      }
+    }
+
+    this.handler = createPagesHandler({
+      rootDir,
+      session: config.session,
+      appContext: this.appContext,
+      devMode: isDev,
+    });
+
+    if (!this.handler) return;
+
+    log.info('Pages: SSR enabled');
+
+    if (isDev) {
+      this.watcher = createPagesWatcher({
+        rootDir,
+        handler: this.handler,
+        log,
+        fonts: config.pages?.fonts,
+        initialClientMetafile,
+        fileWatcher,
+      });
+      log.info('Pages: watching for changes (HMR enabled)');
+    }
+  }
+
+  async handle(req, res) {
+    if (!this.handler) return false;
+    return this.handler.handle(req, res);
+  }
+
+  async close() {
+    if (this.watcher) {
+      await this.watcher.close();
+      this.watcher = null;
+    }
+  }
+}
+
+export { PagesRouter };

package/server/pages/ssr.js

@@ -0,0 +1,276 @@
+import path from 'node:path';
+import { pathToFileURL } from 'node:url';
+import { createRequire } from 'node:module';
+import { setSSRHeadData, clearSSRHeadData, renderHeadToString } from '#client/head.js';
+import { collectPublicEnv, buildEnvScriptTag } from '#client/env.js';
+import { buildHmrScript } from './hmr.js';
+const REACT_INTERNALS_KEY = '__CLIENT_INTERNALS_DO_NOT_USE_OR_WARN_USERS_THEY_CANNOT_UPGRADE';
+function syncReactInternals(projectReactModule) {
+  try {
+    const fwRequire = createRequire(import.meta.url);
+    const fwReact = fwRequire('react');
+    const projectInternals = projectReactModule[REACT_INTERNALS_KEY];
+    const fwInternals = fwReact[REACT_INTERNALS_KEY];
+    if (projectInternals && fwInternals && projectInternals !== fwInternals) {
+      const keys = new Set([
+        ...Object.keys(projectInternals),
+        ...Object.keys(fwInternals),
+      ]);
+      for (const key of keys) {
+        Object.defineProperty(fwInternals, key, {
+          get() {
+            return projectInternals[key];
+          },
+          set(v) {
+            projectInternals[key] = v;
+          },
+          configurable: true,
+        });
+      }
+    }
+  } catch {
+    // React internals sync is best-effort — mismatch is non-fatal
+  }
+}
+async function loadComponent(bundlePath, cacheKey, componentCache, cacheVersion) {
+  if (componentCache.has(cacheKey)) {
+    return componentCache.get(cacheKey);
+  }
+  try {
+    const fileUrl = pathToFileURL(bundlePath).href;
+    const specifier = cacheVersion > 0 ? `${fileUrl}?v=${cacheVersion}` : fileUrl;
+    const mod = await import(specifier);
+    const Component = mod.default;
+    componentCache.set(cacheKey, Component);
+    return Component;
+  } catch {
+    // Component failed to load (missing file, syntax error) — caller handles null
+    return null;
+  }
+}
+const ROUTER_CTX_KEY = '__router_context__';
+const PROVIDER_CTX_KEY = '__provider_context__';
+function wrapWithProviders(createElement, element, pathname, params) {
+  const routerCtx = globalThis[ROUTER_CTX_KEY];
+  if (routerCtx) {
+    const routerValue = {
+      pathname,
+      params,
+      navigate: () => {},
+      // No-op during SSR
+    };
+    element = createElement(routerCtx.Provider, { value: routerValue }, element);
+  }
+  const providerCtx = globalThis[PROVIDER_CTX_KEY];
+  if (providerCtx) {
+    const apiValue = { pathPrefix: '' };
+    element = createElement(providerCtx.Provider, { value: apiValue }, element);
+  }
+  return element;
+}
+function buildCssLinkTag(manifest) {
+  if (!manifest.cssBundle) return '';
+  return `<link rel="stylesheet" href="/static/${manifest.cssBundle}" />`;
+}
+function buildFontPreloadTags(manifest) {
+  return manifest.fontPreloadHtml ?? '';
+}
+function buildLiveReloadScript() {
+  return `<script>
+(function(){var es=new EventSource("/__livereload");es.onmessage=function(e){if(e.data==="reload")window.location.reload()};es.onerror=function(){es.close()}})();
+</script>`;
+}
+function buildScriptTags(route, manifest) {
+  const tags = [];
+  for (const chunk of manifest.sharedChunks) {
+    tags.push(`<script type="module" src="/static/${chunk}"></script>`);
+  }
+  tags.push(`<script type="module" src="/static/${route.clientBundle}"></script>`);
+  return tags.join('\n');
+}
+function buildHtmlShell({ headHtml, fontPreloadTags, cssLinkTag, bodysuffix }) {
+  return {
+    head: `<!DOCTYPE html>
+<html>
+<head>
+<meta charset="utf-8" />
+<meta name="viewport" content="width=device-width, initial-scale=1" />
+${fontPreloadTags}
+${cssLinkTag}
+${headHtml}
+</head>
+<body>
+<div id="__app">`,
+    tail: `</div>
+${bodysuffix ?? ''}
+</body>
+</html>`,
+  };
+}
+async function renderPage(
+  route,
+  params,
+  pathname,
+  manifest,
+  clientManifestJson,
+  outDir,
+  res,
+  componentCache,
+  cacheVersion,
+  react,
+  devMode,
+) {
+  const { createElement, renderToPipeableStream } = react;
+  const bundlePath = path.join(outDir, route.serverBundle);
+  const Component = await loadComponent(
+    bundlePath,
+    `page:${route.pattern}`,
+    componentCache,
+    cacheVersion,
+  );
+  if (!Component || typeof Component !== 'function') {
+    res.writeHead(500, { 'Content-Type': 'text/html' });
+    res.end('<h1>500 - Page component is not a valid React component</h1>');
+    return;
+  }
+  const layoutComponents = [];
+  for (const layoutBundle of route.layoutServerBundles) {
+    const layoutPath = path.join(outDir, layoutBundle);
+    const Layout = await loadComponent(
+      layoutPath,
+      `layout:${layoutBundle}`,
+      componentCache,
+      cacheVersion,
+    );
+    if (Layout && typeof Layout === 'function') {
+      layoutComponents.push(Layout);
+    }
+  }
+  const scriptTags = buildScriptTags(route, manifest);
+  const cssLinkTag = buildCssLinkTag(manifest);
+  const fontPreloadTags = buildFontPreloadTags(manifest);
+  const envScriptTag = buildEnvScriptTag(collectPublicEnv());
+  const hmrTag = devMode ? buildHmrScript() : '';
+  const liveReloadTag = devMode && !hmrTag ? buildLiveReloadScript() : '';
+  const propsJson = JSON.stringify(params).replace(/</g, '\\u003c');
+  const headData = { meta: [], links: [] };
+  setSSRHeadData(headData);
+  let element = createElement(Component, params);
+  for (let i = layoutComponents.length - 1; i >= 0; i--) {
+    element = createElement(layoutComponents[i], null, element);
+  }
+  element = wrapWithProviders(createElement, element, pathname, params);
+  const { PassThrough } = await import('node:stream');
+  const { pipe } = renderToPipeableStream(element, {
+    onAllReady() {
+      if (res.headersSent) return;
+      res.writeHead(200, { 'Content-Type': 'text/html; charset=utf-8' });
+      const headHtml = renderHeadToString(headData);
+      const shell = buildHtmlShell({
+        headHtml,
+        fontPreloadTags,
+        cssLinkTag,
+        bodysuffix: `${envScriptTag}
+<script id="__app_props" type="application/json">${propsJson}</script>
+<script id="__app_manifest" type="application/json">${clientManifestJson}</script>
+${hmrTag}
+${scriptTags}
+${liveReloadTag}`,
+      });
+      res.write(shell.head);
+      const pass = new PassThrough();
+      pass.on('data', (chunk) => res.write(chunk));
+      pass.on('end', () => {
+        res.write(shell.tail);
+        clearSSRHeadData();
+        res.end();
+      });
+      pipe(pass);
+    },
+    onError(err) {
+      clearSSRHeadData();
+      console.error('SSR render error:', err);
+      if (!res.headersSent) {
+        res.writeHead(500, { 'Content-Type': 'text/html' });
+        res.end('<h1>500 - Render Error</h1>');
+      }
+    },
+  });
+}
+async function renderErrorPage(
+  bundlePath,
+  statusCode,
+  props,
+  outDir,
+  res,
+  componentCache,
+  manifest,
+  cacheVersion,
+  react,
+) {
+  const { createElement, renderToPipeableStream } = react;
+  const fullPath = path.join(outDir, bundlePath);
+  const Component = await loadComponent(
+    fullPath,
+    `error:${bundlePath}`,
+    componentCache,
+    cacheVersion,
+  );
+  if (!Component || typeof Component !== 'function') {
+    res.writeHead(statusCode, { 'Content-Type': 'text/html' });
+    res.end(
+      `<h1>${statusCode} - ${statusCode === 404 ? 'Not Found' : 'Internal Server Error'}</h1>`,
+    );
+    return;
+  }
+  const headData = { meta: [], links: [] };
+  setSSRHeadData(headData);
+  const cssLinkTag = buildCssLinkTag(manifest);
+  const fontPreloadTags = buildFontPreloadTags(manifest);
+  const errorPath = props.pathname ?? '/';
+  const element = wrapWithProviders(
+    createElement,
+    createElement(Component, { statusCode, ...props }),
+    errorPath,
+    {},
+  );
+  const { PassThrough } = await import('node:stream');
+  const { pipe } = renderToPipeableStream(element, {
+    onAllReady() {
+      if (res.headersSent) return;
+      const headHtml = renderHeadToString(headData);
+      res.writeHead(statusCode, { 'Content-Type': 'text/html; charset=utf-8' });
+      const shell = buildHtmlShell({ headHtml, fontPreloadTags, cssLinkTag });
+      res.write(shell.head);
+      const pass = new PassThrough();
+      pass.on('data', (chunk) => res.write(chunk));
+      pass.on('end', () => {
+        res.write(shell.tail);
+        clearSSRHeadData();
+        res.end();
+      });
+      pipe(pass);
+    },
+    onError(err) {
+      clearSSRHeadData();
+      console.error('Error page render error:', err);
+      if (!res.headersSent) {
+        res.writeHead(statusCode, { 'Content-Type': 'text/html' });
+        res.end(
+          `<h1>${statusCode} - ${statusCode === 404 ? 'Not Found' : 'Internal Server Error'}</h1>`,
+        );
+      }
+    },
+  });
+}
+export {
+  buildCssLinkTag,
+  buildFontPreloadTags,
+  buildLiveReloadScript,
+  buildScriptTags,
+  loadComponent,
+  renderErrorPage,
+  renderPage,
+  syncReactInternals,
+  wrapWithProviders,
+};

package/server/pages/static.js

@@ -0,0 +1,92 @@
+import path from 'node:path';
+import fs from 'node:fs';
+const MIME_TYPES = {
+  '.html': 'text/html',
+  '.css': 'text/css',
+  '.js': 'application/javascript',
+  '.mjs': 'application/javascript',
+  '.json': 'application/json',
+  '.map': 'application/json',
+  '.png': 'image/png',
+  '.jpg': 'image/jpeg',
+  '.jpeg': 'image/jpeg',
+  '.gif': 'image/gif',
+  '.svg': 'image/svg+xml',
+  '.ico': 'image/x-icon',
+  '.woff': 'font/woff',
+  '.woff2': 'font/woff2',
+  '.ttf': 'font/ttf',
+  '.txt': 'text/plain',
+  '.xml': 'application/xml',
+  '.webp': 'image/webp',
+  '.mp4': 'video/mp4',
+  '.webm': 'video/webm',
+  '.pdf': 'application/pdf',
+};
+function serveStaticAsset(pathname, res, outDir) {
+  const relativePath = pathname.slice('/static/'.length);
+  const normalized = path.normalize(relativePath);
+  if (normalized.startsWith('..') || path.isAbsolute(normalized)) {
+    res.writeHead(403);
+    res.end();
+    return true;
+  }
+  if (!normalized.startsWith('client')) {
+    res.writeHead(404);
+    res.end();
+    return true;
+  }
+  const filePath = path.resolve(outDir, normalized);
+  const resolvedOutDir = path.resolve(outDir);
+  if (!filePath.startsWith(resolvedOutDir + path.sep) && filePath !== resolvedOutDir) {
+    res.writeHead(403);
+    res.end();
+    return true;
+  }
+  if (!fs.existsSync(filePath)) {
+    res.writeHead(404);
+    res.end();
+    return true;
+  }
+  const ext = path.extname(filePath).toLowerCase();
+  const contentType = MIME_TYPES[ext] ?? 'application/octet-stream';
+  const basename = path.basename(normalized);
+  const hasContentHash = /.-[a-zA-Z0-9]+\.\w+$/.test(basename);
+  const cacheControl = hasContentHash
+    ? 'public, max-age=31536000, immutable'
+    : 'public, max-age=3600';
+  res.writeHead(200, {
+    'Content-Type': contentType,
+    'Cache-Control': cacheControl,
+  });
+  const stream = fs.createReadStream(filePath);
+  stream.pipe(res);
+  return true;
+}
+function servePublicFile(pathname, res, publicDir) {
+  const normalized = path.normalize(pathname.slice(1));
+  if (normalized.startsWith('..') || path.isAbsolute(normalized)) {
+    return false;
+  }
+  const filePath = path.resolve(publicDir, normalized);
+  const resolvedPublicDir = path.resolve(publicDir);
+  if (!filePath.startsWith(resolvedPublicDir + path.sep) && filePath !== resolvedPublicDir) {
+    return false;
+  }
+  try {
+    const stat = fs.statSync(filePath);
+    if (!stat.isFile()) return false;
+  } catch {
+    return false;
+  }
+  const ext = path.extname(filePath).toLowerCase();
+  const contentType = MIME_TYPES[ext] ?? 'application/octet-stream';
+  res.writeHead(200, {
+    'Content-Type': contentType,
+    'Cache-Control': 'public, max-age=3600',
+  });
+  const stream = fs.createReadStream(filePath);
+  stream.pipe(res);
+  return true;
+}
+export { MIME_TYPES, servePublicFile, serveStaticAsset };

package/server/pages/watcher.js

@@ -0,0 +1,90 @@
+import path from 'node:path';
+import { buildPages } from './build.js';
+import { diffClientMetafiles } from './hmr.js';
+
+function createPagesWatcher(options) {
+  const { rootDir, handler, log, fonts, fileWatcher } = options;
+  let building = false;
+  let pendingRebuild = false;
+  let pendingStructuralChange = false;
+  let prevClientMetafile = options.initialClientMetafile;
+  const outDir = path.resolve(rootDir, '.build/pages');
+
+  async function rebuild(isStructuralChange) {
+    if (building) {
+      pendingRebuild = true;
+      if (isStructuralChange) pendingStructuralChange = true;
+      return;
+    }
+    building = true;
+    try {
+      const start = Date.now();
+      const result = await buildPages({ rootDir, fonts, minify: false, devMode: true });
+      handler.reload();
+      const elapsed = Date.now() - start;
+      if (handler.emitEvent && prevClientMetafile && result.clientMetafile && !isStructuralChange) {
+        const diff = diffClientMetafiles(prevClientMetafile, result.clientMetafile, outDir);
+        if (diff.needsFullReload) {
+          handler.emitEvent({ type: 'reload' });
+          log.info(`Pages rebuilt in ${elapsed}ms (full reload)`);
+        } else if (diff.changedNavBundles.length > 0) {
+          const manifestJson = handler.getClientManifestJson?.();
+          handler.emitEvent({
+            type: 'hmr-update',
+            modules: diff.changedNavBundles,
+            timestamp: Date.now(),
+            ...(manifestJson ? { manifest: manifestJson } : {}),
+          });
+          log.info(
+            `Pages rebuilt in ${elapsed}ms (HMR: ${diff.changedNavBundles.length} module(s))`,
+          );
+        } else if (diff.changedCssBundle) {
+          handler.emitEvent({
+            type: 'css-update',
+            cssBundle: diff.changedCssBundle,
+            timestamp: Date.now(),
+          });
+          log.info(`Pages rebuilt in ${elapsed}ms (CSS update)`);
+        } else {
+          log.info(`Pages rebuilt in ${elapsed}ms (no client changes)`);
+        }
+      } else {
+        if (handler.emitEvent) {
+          handler.emitEvent({ type: 'reload' });
+        }
+        log.info(`Pages rebuilt in ${elapsed}ms`);
+      }
+      prevClientMetafile = result.clientMetafile;
+    } catch (err) {
+      log.error('Pages rebuild failed', { error: String(err) });
+    } finally {
+      building = false;
+      if (pendingRebuild) {
+        pendingRebuild = false;
+        const structural = pendingStructuralChange;
+        pendingStructuralChange = false;
+        await rebuild(structural);
+      }
+    }
+  }
+
+  fileWatcher.subscribe('pages', {
+    extensions: ['.tsx', '.jsx', '.ts', '.js', '.css'],
+    debounceMs: 150,
+    onChange(events) {
+      const isStructural = events.some((e) => e.event === 'add' || e.event === 'unlink');
+      for (const e of events) {
+        log.info(`Page ${e.event === 'unlink' ? 'removed' : e.event === 'add' ? 'added' : 'changed'}: ${e.relativePath}`);
+      }
+      return rebuild(isStructural);
+    },
+  });
+
+  return {
+    async close() {
+      fileWatcher.unsubscribe('pages');
+    },
+  };
+}
+
+export { createPagesWatcher };

package/server/queue/drivers/knex.js

@@ -0,0 +1,67 @@
+class KnexQueueDriver {
+  tableName;
+  constructor(db, tableName = 'arcway_queue') {
+    this.db = db;
+    this.tableName = tableName;
+  }
+  db;
+  async init() {
+    const exists = await this.db.schema.hasTable(this.tableName);
+    if (!exists) {
+      await this.db.schema.createTable(this.tableName, (table) => {
+        table.increments('id').primary();
+        table.string('namespace').notNullable().index();
+        table.string('topic').notNullable().index();
+        table.text('payload').notNullable();
+        table.string('status').notNullable().defaultTo('available');
+        table.timestamp('locked_at').nullable();
+        table.timestamp('created_at').defaultTo(this.db.fn.now());
+      });
+    }
+  }
+  async push(namespace, topic, payload) {
+    await this.db(this.tableName).insert({
+      namespace,
+      topic,
+      payload,
+      status: 'available',
+    });
+  }
+  async pop(namespace, topic, count, lockCooldownMs) {
+    const cutoff = new Date(Date.now() - lockCooldownMs).toISOString();
+    const now = new Date().toISOString();
+    return this.db.transaction(async (trx) => {
+      const subquery = trx(this.tableName)
+        .where('namespace', namespace)
+        .andWhere('topic', topic)
+        .andWhere(function () {
+          this.where('status', 'available').orWhere(function () {
+            this.where('status', 'locked').andWhere('locked_at', '<', cutoff);
+          });
+        })
+        .orderBy('id', 'asc')
+        .limit(count)
+        .select('id');
+      const updatedCount = await trx(this.tableName)
+        .whereIn('id', subquery)
+        .update({ status: 'locked', locked_at: now });
+      if (updatedCount === 0) {
+        return [];
+      }
+      const rows = await trx(this.tableName)
+        .where('namespace', namespace)
+        .andWhere('topic', topic)
+        .andWhere('status', 'locked')
+        .andWhere('locked_at', now)
+        .orderBy('id', 'asc')
+        .limit(count)
+        .select('id', 'payload');
+      return rows.map((r) => ({ id: r.id, payload: r.payload }));
+    });
+  }
+  async remove(namespace, ids) {
+    if (ids.length === 0) return;
+    await this.db(this.tableName).where('namespace', namespace).whereIn('id', ids).delete();
+  }
+}
+export default KnexQueueDriver;

package/server/queue/drivers/redis.js

@@ -0,0 +1,91 @@
+import { REDIS_SCAN_COUNT } from '../../constants.js';
+const REQUEUE_EXPIRED_LUA = `
+  local expired = redis.call('ZRANGEBYSCORE', KEYS[1], '-inf', ARGV[1])
+  for i, member in ipairs(expired) do
+    redis.call('LPUSH', KEYS[2], member)
+    redis.call('ZREM', KEYS[1], member)
+  end
+  return #expired
+`;
+const POP_AND_LOCK_LUA = `
+  local raw = redis.call('LPOP', KEYS[1])
+  if raw then
+    redis.call('ZADD', KEYS[2], ARGV[1], raw)
+  end
+  return raw
+`;
+class RedisQueueDriver {
+  client;
+  prefix;
+  constructor(client, keyPrefix = 'arcway:') {
+    this.client = client;
+    this.prefix = `${keyPrefix}queue:`;
+  }
+  listKey(namespace, topic) {
+    return `${this.prefix}${namespace}:${topic}`;
+  }
+  lockedKey(namespace, topic) {
+    return `${this.prefix}${namespace}:${topic}:locked`;
+  }
+  idKey() {
+    return `${this.prefix}id`;
+  }
+  async init() {}
+
+  async push(namespace, topic, payload) {
+    const id = await this.client.incr(this.idKey());
+    const item = JSON.stringify({ id, payload });
+    await this.client.rpush(this.listKey(namespace, topic), item);
+  }
+  async pop(namespace, topic, count, lockCooldownMs) {
+    const results = [];
+    const listKey = this.listKey(namespace, topic);
+    const lockedKey = this.lockedKey(namespace, topic);
+    const now = Date.now();
+    const cutoff = now - lockCooldownMs;
+    await this.client.eval(REQUEUE_EXPIRED_LUA, 2, lockedKey, listKey, cutoff.toString());
+    for (let i = 0; i < count; i++) {
+      const raw = await this.client.eval(POP_AND_LOCK_LUA, 2, listKey, lockedKey, now.toString());
+      if (!raw) break;
+      const parsed = JSON.parse(raw);
+      results.push({ id: parsed.id, payload: parsed.payload });
+    }
+    return results;
+  }
+  async remove(namespace, ids) {
+    if (ids.length === 0) return;
+    const idSet = new Set(ids);
+    const pattern = `${this.prefix}${namespace}:*:locked`;
+    const keys = await this.scanKeys(pattern);
+    for (const lockedKey of keys) {
+      const members = await this.client.zrange(lockedKey, 0, -1);
+      for (const member of members) {
+        try {
+          const parsed = JSON.parse(member);
+          if (idSet.has(parsed.id)) {
+            await this.client.zrem(lockedKey, member);
+          }
+        } catch {
+            // Malformed locked member — skip removal
+          }
+      }
+    }
+  }
+  async scanKeys(pattern) {
+    const keys = [];
+    let cursor = '0';
+    do {
+      const [next, found] = await this.client.scan(
+        cursor,
+        'MATCH',
+        pattern,
+        'COUNT',
+        REDIS_SCAN_COUNT,
+      );
+      cursor = next;
+      keys.push(...found);
+    } while (cursor !== '0');
+    return keys;
+  }
+}
+export default RedisQueueDriver;