arcway 0.1.26 → 0.1.28

package/server/pages/ssr.js

@@ -4,6 +4,13 @@ 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';
+
+function getHtmlHeaders() {
+  return {
+    'Content-Type': 'text/html; charset=utf-8',
+    'Cache-Control': 'no-store',
+  };
+}
 const REACT_INTERNALS_KEY = '__CLIENT_INTERNALS_DO_NOT_USE_OR_WARN_USERS_THEY_CANNOT_UPGRADE';
 function syncReactInternals(projectReactModule) {
   try {
@@ -154,7 +161,7 @@ async function renderPage(
     cacheVersion,
   );
   if (!Component || typeof Component !== 'function') {
-    res.writeHead(500, { 'Content-Type': 'text/html' });
+    res.writeHead(500, getHtmlHeaders());
     res.end('<h1>500 - Page component is not a valid React component</h1>');
     return;
   }
@@ -188,10 +195,12 @@ async function renderPage(
   }
   element = wrapWithProviders(createElement, element, pathname, params);
   const { PassThrough } = await import('node:stream');
-  const { pipe } = renderToPipeableStream(element, {
+  let pass = null;
+  let closed = false;
+  const { pipe, abort } = renderToPipeableStream(element, {
     onAllReady() {
-      if (res.headersSent) return;
-      res.writeHead(200, { 'Content-Type': 'text/html; charset=utf-8' });
+      if (res.headersSent || closed) return;
+      res.writeHead(200, getHtmlHeaders());
       const headHtml = renderHeadToString(headData);
       const shell = buildHtmlShell({
         headHtml,
@@ -205,24 +214,39 @@ ${scriptTags}
 ${liveReloadTag}`,
       });
       res.write(shell.head);
-      const pass = new PassThrough();
-      pass.on('data', (chunk) => res.write(chunk));
+      pass = new PassThrough();
+      pass.on('data', (chunk) => {
+        if (!closed && !res.writableEnded) res.write(chunk);
+      });
       pass.on('end', () => {
-        res.write(shell.tail);
+        if (!closed && !res.writableEnded) {
+          res.write(shell.tail);
+          res.end();
+        }
         clearSSRHeadData();
-        res.end();
       });
       pipe(pass);
     },
     onError(err) {
       clearSSRHeadData();
+      // A client disconnect aborts the render and surfaces here; that's a normal
+      // peer disconnect, not a server fault — don't log it or write to a dead res.
+      if (closed) return;
       console.error('SSR render error:', err);
       if (!res.headersSent) {
-        res.writeHead(500, { 'Content-Type': 'text/html' });
+        res.writeHead(500, getHtmlHeaders());
         res.end('<h1>500 - Render Error</h1>');
       }
     },
   });
+  // Client gone (mid-stream, or before the shell was ready): stop React from
+  // rendering into a dead response and tear down the PassThrough.
+  res.on('close', () => {
+    if (closed) return;
+    closed = true;
+    abort();
+    if (pass) pass.destroy();
+  });
 }
 async function renderErrorPage(
   bundlePath,
@@ -244,7 +268,7 @@ async function renderErrorPage(
     cacheVersion,
   );
   if (!Component || typeof Component !== 'function') {
-    res.writeHead(statusCode, { 'Content-Type': 'text/html' });
+    res.writeHead(statusCode, getHtmlHeaders());
     res.end(
       `<h1>${statusCode} - ${statusCode === 404 ? 'Not Found' : 'Internal Server Error'}</h1>`,
     );
@@ -262,33 +286,46 @@ async function renderErrorPage(
     {},
   );
   const { PassThrough } = await import('node:stream');
-  const { pipe } = renderToPipeableStream(element, {
+  let pass = null;
+  let closed = false;
+  const { pipe, abort } = renderToPipeableStream(element, {
     onAllReady() {
-      if (res.headersSent) return;
+      if (res.headersSent || closed) return;
       const headHtml = renderHeadToString(headData);
-      res.writeHead(statusCode, { 'Content-Type': 'text/html; charset=utf-8' });
+      res.writeHead(statusCode, getHtmlHeaders());
       const shell = buildHtmlShell({ headHtml, fontPreloadTags, cssLinkTag });
       res.write(shell.head);
-      const pass = new PassThrough();
-      pass.on('data', (chunk) => res.write(chunk));
+      pass = new PassThrough();
+      pass.on('data', (chunk) => {
+        if (!closed && !res.writableEnded) res.write(chunk);
+      });
       pass.on('end', () => {
-        res.write(shell.tail);
+        if (!closed && !res.writableEnded) {
+          res.write(shell.tail);
+          res.end();
+        }
         clearSSRHeadData();
-        res.end();
       });
       pipe(pass);
     },
     onError(err) {
       clearSSRHeadData();
+      if (closed) return;
       console.error('Error page render error:', err);
       if (!res.headersSent) {
-        res.writeHead(statusCode, { 'Content-Type': 'text/html' });
+        res.writeHead(statusCode, getHtmlHeaders());
         res.end(
           `<h1>${statusCode} - ${statusCode === 404 ? 'Not Found' : 'Internal Server Error'}</h1>`,
         );
       }
     },
   });
+  res.on('close', () => {
+    if (closed) return;
+    closed = true;
+    abort();
+    if (pass) pass.destroy();
+  });
 }
 export {
   buildCssLinkTag,

package/server/plugins/capabilities.js

@@ -0,0 +1,66 @@
+import { requiredCapabilities } from './manifest.js';
+
+class CapabilityNotAvailable extends Error {
+  constructor(capability, reason = 'missing or disabled') {
+    super(`Capability not available: ${capability} (${reason})`);
+    this.name = 'CapabilityNotAvailable';
+    this.capability = capability;
+    this.reason = reason;
+  }
+}
+
+class CapabilityRegistry {
+  #providers = new Map();
+
+  register(pluginId, capability, factory) {
+    if (typeof factory !== 'function') {
+      throw new Error(
+        `Capability ${capability} from plugin ${pluginId} must be registered with a factory`,
+      );
+    }
+    if (this.#providers.has(capability)) {
+      const existing = this.#providers.get(capability);
+      throw new Error(
+        `Capability ${capability} is already provided by plugin ${existing.pluginId}`,
+      );
+    }
+    this.#providers.set(capability, { pluginId, factory, enabled: true });
+  }
+
+  setPluginEnabled(pluginId, enabled) {
+    for (const provider of this.#providers.values()) {
+      if (provider.pluginId === pluginId) provider.enabled = enabled;
+    }
+  }
+
+  has(capability) {
+    const provider = this.#providers.get(capability);
+    return provider?.enabled === true;
+  }
+
+  inject(ctx, requires) {
+    for (const capability of requiredCapabilities(requires)) {
+      const provider = this.#providers.get(capability);
+      if (!provider) throw new CapabilityNotAvailable(capability, 'missing provider');
+      if (!provider.enabled) throw new CapabilityNotAvailable(capability, 'provider disabled');
+      ctx[capability] = provider.factory({
+        capability,
+        providerPluginId: provider.pluginId,
+        req: ctx.req,
+        session: ctx.req?.session,
+        ctx,
+      });
+    }
+    return ctx;
+  }
+
+  list() {
+    return [...this.#providers.entries()].map(([capability, provider]) => ({
+      capability,
+      pluginId: provider.pluginId,
+      enabled: provider.enabled,
+    }));
+  }
+}
+
+export { CapabilityNotAvailable, CapabilityRegistry };

package/server/plugins/discovery.js

@@ -0,0 +1,111 @@
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import { discoverPackageDirectories } from '../discovery.js';
+import { loadModule } from '../module-loader.js';
+import { validateManifest } from './manifest.js';
+
+async function exists(filePath) {
+  try {
+    await fs.access(filePath);
+    return true;
+  } catch (err) {
+    if (err.code === 'ENOENT') return false;
+    throw err;
+  }
+}
+
+async function readJson(filePath, label) {
+  try {
+    return JSON.parse(await fs.readFile(filePath, 'utf8'));
+  } catch (err) {
+    throw new Error(`Failed to read ${label} at ${filePath}: ${err}`);
+  }
+}
+
+function getManifest(module, manifestPath) {
+  const manifest = module.manifest ?? module.default?.manifest ?? module.default;
+  if (!manifest || typeof manifest !== 'object') {
+    throw new Error(`Plugin manifest at ${manifestPath} must export a manifest object`);
+  }
+  return manifest;
+}
+
+async function loadPluginPackage(packageDir) {
+  const packageJsonPath = path.join(packageDir, 'package.json');
+  if (!(await exists(packageJsonPath))) {
+    throw new Error(`Plugin package at ${packageDir} must include package.json`);
+  }
+  const packageJson = await readJson(packageJsonPath, 'package.json');
+
+  const pluginJs = path.join(packageDir, 'plugin.js');
+  const pluginJson = path.join(packageDir, 'plugin.json');
+  let manifestPath;
+  let module = {};
+  let rawManifest;
+
+  if (await exists(pluginJs)) {
+    manifestPath = pluginJs;
+    module = await loadModule(pluginJs, import.meta.url);
+    rawManifest = getManifest(module, pluginJs);
+  } else if (await exists(pluginJson)) {
+    manifestPath = pluginJson;
+    rawManifest = await readJson(pluginJson, 'plugin.json');
+  } else {
+    throw new Error(`Plugin package at ${packageDir} must include plugin.js or plugin.json`);
+  }
+
+  const manifest = validateManifest(
+    {
+      version: packageJson.version,
+      name: packageJson.name,
+      ...rawManifest,
+    },
+    { packageName: packageJson.name },
+  );
+
+  const routesDir = path.join(packageDir, 'routes');
+  const jobsDir = path.join(packageDir, 'jobs');
+  const migrationsDir =
+    typeof manifest.contributes.migrations === 'string'
+      ? path.join(packageDir, manifest.contributes.migrations)
+      : path.join(packageDir, 'migrations');
+
+  return {
+    id: manifest.id,
+    dir: packageDir,
+    packageJson,
+    manifest,
+    module,
+    manifestPath,
+    routesDir: (await exists(routesDir)) ? routesDir : null,
+    jobsDir: (await exists(jobsDir)) ? jobsDir : null,
+    migrationsDir: (await exists(migrationsDir)) ? migrationsDir : null,
+  };
+}
+
+async function discoverPlugins(dirs) {
+  const plugins = [];
+  const seen = new Map();
+
+  for (const dir of dirs ?? []) {
+    const packages = await discoverPackageDirectories(dir, {
+      markerFiles: ['plugin.js', 'plugin.json'],
+      label: 'plugin',
+    });
+    for (const entry of packages) {
+      const plugin = await loadPluginPackage(entry.dir);
+      if (seen.has(plugin.id)) {
+        throw new Error(
+          `Duplicate plugin id ${plugin.id} in ${seen.get(plugin.id)} and ${plugin.dir}`,
+        );
+      }
+      seen.set(plugin.id, plugin.dir);
+      plugins.push(plugin);
+    }
+  }
+
+  plugins.sort((a, b) => a.id.localeCompare(b.id));
+  return plugins;
+}
+
+export { discoverPlugins, loadPluginPackage };

package/server/plugins/graph.js

@@ -0,0 +1,114 @@
+import { requiredCapabilities } from './manifest.js';
+
+function buildProviderMap(plugins) {
+  const providers = new Map();
+  for (const plugin of plugins) {
+    for (const capability of plugin.manifest.provides) {
+      if (providers.has(capability)) {
+        throw new Error(
+          `Capability ${capability} is provided by both ${providers.get(capability).id} and ${plugin.id}`,
+        );
+      }
+      providers.set(capability, plugin);
+    }
+  }
+  return providers;
+}
+
+function resolvePluginGraph(plugins, enabledIds) {
+  const allProviders = buildProviderMap(plugins);
+  const byId = new Map(plugins.map((plugin) => [plugin.id, plugin]));
+  const enabled = new Set(enabledIds);
+  const missing = [];
+  const edges = new Map();
+
+  for (const plugin of plugins) {
+    edges.set(plugin.id, new Set());
+    if (!enabled.has(plugin.id)) continue;
+    for (const capability of requiredCapabilities(plugin.manifest.requires)) {
+      const provider = allProviders.get(capability);
+      if (!provider) {
+        missing.push({ pluginId: plugin.id, capability, reason: 'missing provider' });
+        continue;
+      }
+      if (!enabled.has(provider.id)) {
+        missing.push({
+          pluginId: plugin.id,
+          capability,
+          providerId: provider.id,
+          reason: 'provider disabled',
+        });
+        continue;
+      }
+      if (provider.id !== plugin.id) edges.get(provider.id).add(plugin.id);
+    }
+  }
+
+  if (missing.length > 0) {
+    const first = missing[0];
+    const provider = first.providerId ? ` from ${first.providerId}` : '';
+    throw new Error(
+      `Plugin ${first.pluginId} requires capability ${first.capability}${provider}: ${first.reason}`,
+    );
+  }
+
+  const indegree = new Map([...enabled].map((id) => [id, 0]));
+  for (const [providerId, dependents] of edges) {
+    if (!enabled.has(providerId)) continue;
+    for (const dependentId of dependents) {
+      if (enabled.has(dependentId)) indegree.set(dependentId, indegree.get(dependentId) + 1);
+    }
+  }
+
+  const ready = [...indegree.entries()]
+    .filter(([, degree]) => degree === 0)
+    .map(([id]) => id)
+    .sort();
+  const orderedIds = [];
+
+  while (ready.length > 0) {
+    const id = ready.shift();
+    orderedIds.push(id);
+    for (const dependentId of [...(edges.get(id) ?? [])].sort()) {
+      if (!enabled.has(dependentId)) continue;
+      indegree.set(dependentId, indegree.get(dependentId) - 1);
+      if (indegree.get(dependentId) === 0) ready.push(dependentId);
+    }
+    ready.sort();
+  }
+
+  if (orderedIds.length !== enabled.size) {
+    throw new Error('Plugin capability graph contains a cycle');
+  }
+
+  return {
+    providers: allProviders,
+    order: orderedIds.map((id) => byId.get(id)),
+    edges,
+  };
+}
+
+function cascadeDisabled(plugins, disabledIds) {
+  const providers = buildProviderMap(plugins);
+  const disabled = new Map([...disabledIds].map((id) => [id, 'disabled']));
+  let changed = true;
+
+  while (changed) {
+    changed = false;
+    for (const plugin of plugins) {
+      if (disabled.has(plugin.id)) continue;
+      for (const capability of requiredCapabilities(plugin.manifest.requires)) {
+        const provider = providers.get(capability);
+        if (!provider || disabled.has(provider.id)) {
+          disabled.set(plugin.id, `disabled (missing dependency: ${capability})`);
+          changed = true;
+          break;
+        }
+      }
+    }
+  }
+
+  return disabled;
+}
+
+export { buildProviderMap, cascadeDisabled, resolvePluginGraph };

package/server/plugins/manager.js

@@ -0,0 +1,210 @@
+import { discoverRoutes } from '../router/routes.js';
+import { discoverJobs } from '../jobs/runner.js';
+import { CapabilityRegistry } from './capabilities.js';
+import { discoverPlugins } from './discovery.js';
+import { buildProviderMap, cascadeDisabled, resolvePluginGraph } from './graph.js';
+import { requiredCapabilities } from './manifest.js';
+
+function configuredEnablements(config) {
+  const enablements = config?.enablements ?? config?.enabledPlugins ?? {};
+  return enablements && typeof enablements === 'object' ? enablements : {};
+}
+
+function pluginEnabledByDefault(plugin, enablements) {
+  if (Object.prototype.hasOwnProperty.call(enablements, plugin.id)) {
+    return enablements[plugin.id] === true;
+  }
+  return plugin.manifest.defaultEnabled === true;
+}
+
+function capabilityFactory(plugin, capability) {
+  return (
+    plugin.module.capabilities?.[capability] ??
+    plugin.module.default?.capabilities?.[capability] ??
+    plugin.module[`create${capability[0]?.toUpperCase() ?? ''}${capability.slice(1)}`]
+  );
+}
+
+class PluginManager {
+  constructor(config, { log, runLifecycle = true } = {}) {
+    this.config = config ?? { enabled: false, dirs: [] };
+    this.log = log;
+    this.runLifecycle = runLifecycle;
+    this.plugins = [];
+    this.enabled = new Set();
+    this.status = new Map();
+    this.loadOrder = [];
+    this.capabilities = new CapabilityRegistry();
+  }
+
+  async init() {
+    if (this.config.enabled !== true) return this;
+
+    this.plugins = await discoverPlugins(this.config.dirs);
+    const enablements = configuredEnablements(this.config);
+    this.enabled = new Set(
+      this.plugins
+        .filter((plugin) => pluginEnabledByDefault(plugin, enablements))
+        .map((plugin) => plugin.id),
+    );
+
+    this.#rebuildGraph();
+
+    for (const plugin of this.loadOrder) {
+      if (this.runLifecycle) {
+        await this.#runLifecycle(plugin, 'onLoad');
+        await this.#runLifecycle(plugin, 'onEnable');
+      }
+      this.log?.info?.(`Plugin enabled: ${plugin.id}`);
+    }
+    return this;
+  }
+
+  get enabledPlugins() {
+    return this.loadOrder;
+  }
+
+  getPlugin(id) {
+    return this.plugins.find((plugin) => plugin.id === id) ?? null;
+  }
+
+  async enable(id) {
+    const plugin = this.getPlugin(id);
+    if (!plugin) throw new Error(`Unknown plugin: ${id}`);
+    this.enabled.add(id);
+    this.#rebuildGraph();
+    if (this.runLifecycle) await this.#runLifecycle(plugin, 'onEnable');
+  }
+
+  async runEnabledLifecycle() {
+    for (const plugin of this.loadOrder) {
+      await this.#runLifecycle(plugin, 'onLoad');
+      await this.#runLifecycle(plugin, 'onEnable');
+    }
+    this.runLifecycle = true;
+  }
+
+  async disable(id) {
+    const plugin = this.getPlugin(id);
+    if (!plugin) throw new Error(`Unknown plugin: ${id}`);
+    this.enabled.delete(id);
+    if (this.runLifecycle) await this.#runLifecycle(plugin, 'onDisable');
+    this.#rebuildGraph();
+  }
+
+  injectCapabilities(ctx, requires) {
+    return this.capabilities.inject(ctx, requires);
+  }
+
+  async discoverRoutes() {
+    const routes = [];
+    for (const plugin of this.enabledPlugins) {
+      if (!plugin.routesDir) continue;
+      const discovered = await discoverRoutes(plugin.routesDir, {
+        prefix: `/plugins/${plugin.id}`,
+        plugin: {
+          id: plugin.id,
+          requires: plugin.manifest.requires,
+        },
+      });
+      routes.push(...discovered);
+    }
+    return routes;
+  }
+
+  async discoverJobs() {
+    const jobs = [];
+    for (const plugin of this.enabledPlugins) {
+      if (!plugin.jobsDir) continue;
+      const discovered = await discoverJobs(plugin.jobsDir);
+      for (const job of discovered) {
+        const definition = {
+          ...job.definition,
+          name: `plugins/${plugin.id}/${job.definition.name}`,
+          plugin: {
+            id: plugin.id,
+            requires: plugin.manifest.requires,
+          },
+        };
+        jobs.push({ ...job, definition, filePath: null });
+      }
+    }
+    return jobs;
+  }
+
+  migrations() {
+    return this.enabledPlugins
+      .filter((plugin) => plugin.migrationsDir)
+      .map((plugin) => ({
+        pluginId: plugin.id,
+        dir: plugin.migrationsDir,
+        contributes: plugin.manifest.contributes.migrations,
+      }));
+  }
+
+  #rebuildGraph() {
+    const providers = buildProviderMap(this.plugins);
+    for (const plugin of this.plugins) {
+      if (!this.enabled.has(plugin.id)) continue;
+      for (const capability of requiredCapabilities(plugin.manifest.requires)) {
+        if (!providers.has(capability)) {
+          throw new Error(
+            `Plugin ${plugin.id} requires capability ${capability}: missing provider`,
+          );
+        }
+      }
+    }
+
+    const disabled = cascadeDisabled(
+      this.plugins,
+      this.plugins.filter((plugin) => !this.enabled.has(plugin.id)).map((plugin) => plugin.id),
+    );
+    this.status = new Map();
+    for (const plugin of this.plugins) {
+      this.status.set(plugin.id, disabled.get(plugin.id) ?? 'enabled');
+    }
+
+    const effectiveEnabled = new Set(
+      this.plugins
+        .filter((plugin) => this.status.get(plugin.id) === 'enabled')
+        .map((plugin) => plugin.id),
+    );
+    const graph = resolvePluginGraph(this.plugins, effectiveEnabled);
+    this.loadOrder = graph.order;
+
+    this.capabilities = new CapabilityRegistry();
+    for (const plugin of this.loadOrder) {
+      for (const capability of plugin.manifest.provides) {
+        const factory = capabilityFactory(plugin, capability);
+        if (!factory) {
+          throw new Error(
+            `Plugin ${plugin.id} provides ${capability} but does not export a factory`,
+          );
+        }
+        this.capabilities.register(plugin.id, capability, factory);
+      }
+    }
+    for (const plugin of this.plugins) {
+      this.capabilities.setPluginEnabled(plugin.id, this.status.get(plugin.id) === 'enabled');
+    }
+  }
+
+  async #runLifecycle(plugin, name) {
+    const hook = plugin.manifest.lifecycle?.[name];
+    if (!hook) return;
+    const fn =
+      typeof hook === 'function' ? hook : (plugin.module[hook] ?? plugin.module.default?.[hook]);
+    if (typeof fn !== 'function') {
+      throw new Error(`Plugin ${plugin.id} lifecycle.${name} does not resolve to a function`);
+    }
+    await fn({ plugin, manager: this });
+  }
+}
+
+async function createPluginManager(config, options) {
+  const manager = new PluginManager(config, options);
+  await manager.init();
+  return manager;
+}
+
+export { PluginManager, createPluginManager };