@forgeax/engine-host 0.1.27 → 0.1.29

package/src/__tests__/host.test.ts

@@ -9,6 +9,7 @@ import {
   createHostAssembly,
   createHostTransport,
   createHostWebSocketClient,
+  HOST_ACTIVATION_REPORT_SERVICE,
   HostAssemblyError,
 } from '../index';
 
@@ -26,6 +27,59 @@ function catalogFor(plugin: Plugin) {
 }
 
 describe('Engine host pair', () => {
+  it('admits one explicit bootstrap revision and preserves the owner activation callback', async () => {
+    const ownerReports: string[] = [];
+    const subscriberReports: string[] = [];
+    const backend = await createBackendHost({
+      config: { phase: 'owner' },
+      onActivationReport: (report) => {
+        ownerReports.push(report.revision);
+      },
+    });
+    const client = backend.transport.connect();
+    const remove = backend.subscribeActivationReports((report) => {
+      subscriberReports.push(report.revision);
+    });
+    try {
+      const original = backend.assembly.current;
+      const bootstrap = await backend.update(
+        { config: { phase: 'bootstrap' } },
+        { bootstrap: true },
+      );
+      const full = await backend.update({ config: { phase: 'full' } });
+      await client.request(HOST_ACTIVATION_REPORT_SERVICE, {
+        state: 'active',
+        revision: bootstrap.revision,
+      });
+      expect(ownerReports).toEqual([bootstrap.revision]);
+      expect(subscriberReports).toEqual([bootstrap.revision]);
+      await expect(
+        client.request(HOST_ACTIVATION_REPORT_SERVICE, {
+          state: 'active',
+          revision: original.revision,
+        }),
+      ).rejects.toMatchObject({ code: 'host-assembly-revision-mismatch' });
+      remove();
+      await client.request(HOST_ACTIVATION_REPORT_SERVICE, {
+        state: 'active',
+        revision: full.revision,
+      });
+      expect(ownerReports).toEqual([bootstrap.revision, full.revision]);
+      expect(subscriberReports).toEqual([bootstrap.revision]);
+      await backend.update({ config: { phase: 'next-bootstrap' } }, { bootstrap: true });
+      await expect(
+        client.request(HOST_ACTIVATION_REPORT_SERVICE, {
+          state: 'active',
+          revision: bootstrap.revision,
+        }),
+      ).rejects.toMatchObject({ code: 'host-assembly-revision-mismatch' });
+    } finally {
+      remove();
+      client.close();
+      await backend.dispose();
+    }
+    expect(() => backend.subscribeActivationReports(() => {})).toThrow(HostAssemblyError);
+  });
   it('activates a static frontend assembly through native Cordis Loader and unloads it', async () => {
     const events: string[] = [];
     const plugin: Plugin = {
@@ -357,6 +411,61 @@ describe('Engine host pair', () => {
     await new Promise<void>((resolve) => server.close(() => resolve()));
   });
 
+  it('preserves unknown remote business codes across the real WebSocket boundary', async () => {
+    const server = new WebSocketServer({ port: 0 });
+    await once(server, 'listening');
+    const address = server.address();
+    if (address === null || typeof address === 'string') throw new Error('WebSocket port missing');
+    const failures = {
+      capability: {
+        code: 'view-engine-capability-unavailable',
+        expected: 'Engine workspace capability project.open to be installed',
+        hint: 'Build and install the matching Engine workspace plugin before opening a project.',
+        detail: { capability: 'project.open' },
+      },
+      asset: {
+        code: 'view-workspace-asset-unsupported',
+        expected: 'Engine asset.open to support asset kind material',
+        hint: 'Use an Engine type-preview capability for this asset kind.',
+        detail: { kind: 'material' },
+      },
+    } as const;
+    const transport = createHostTransport();
+    const unregister = transport.register('forgeax.view.workspace.call', ({ payload }) => {
+      const failure =
+        (payload as { readonly operation?: unknown }).operation === 'asset.open'
+          ? failures.asset
+          : failures.capability;
+      throw Object.assign(new Error(failure.hint), failure);
+    });
+    server.on('connection', (socket) => attachHostWebSocketServer(socket, transport));
+    let client: Awaited<ReturnType<typeof createHostWebSocketClient>> | undefined;
+    try {
+      client = await createHostWebSocketClient(new WebSocket(`ws://127.0.0.1:${address.port}`));
+      for (const failure of [failures.capability, failures.asset]) {
+        await expect(
+          client.request('forgeax.view.workspace.call', {
+            operation: failure === failures.asset ? 'asset.open' : 'project.open',
+          }),
+        ).rejects.toMatchObject({
+          code: 'host-transport-failure',
+          expected: failure.expected,
+          hint: failure.hint,
+          detail: {
+            service: 'host/socket',
+            remoteCode: failure.code,
+            ...failure.detail,
+          },
+        });
+      }
+    } finally {
+      client?.close();
+      unregister();
+      transport.close();
+      await new Promise<void>((resolve) => server.close(() => resolve()));
+    }
+  });
+
   it('withdraws the frontend capability when its backend connection closes', async () => {
     const plugin: Plugin = { name: 'disconnect-fixture', apply() {} };
     const pair = {

package/src/__tests__/startup.test.ts

@@ -0,0 +1,27 @@
+import { describe, expect, it } from 'vitest';
+import { createHostStartup } from '../startup.js';
+
+describe('generic host startup', () => {
+  it('owns only supplied Cordis startup entries and releases them', async () => {
+    let disposed = false;
+    const startup = await createHostStartup({
+      startupPlugins: [
+        {
+          name: 'fixture-startup',
+          apply(ctx) {
+            ctx.effect(
+              () => () => {
+                disposed = true;
+              },
+              'fixture-startup',
+            );
+          },
+        },
+      ],
+    });
+
+    expect(startup.ownedContext).toBe(true);
+    await startup.dispose();
+    expect(disposed).toBe(true);
+  });
+});

package/src/backend.ts

@@ -20,6 +20,7 @@ import {
   modulesFromCatalog,
   validateHostAssembly,
 } from './protocol.js';
+import { createHostStartup, type HostStartup } from './startup.js';
 import {
   createHostTransport,
   HOST_ACTIVATION_REPORT_SERVICE,
@@ -59,7 +60,15 @@ export interface BackendHost {
   readonly transport: HostTransportServer;
   readonly ownedContext: boolean;
   /** Reconcile backend Entries and publish the matching frontend assembly atomically. */
-  update(input: HostAssemblyInput | readonly GamePluginEntry[]): Promise<HostAssembly>;
+  update(
+    input: HostAssemblyInput | readonly GamePluginEntry[],
+    /** Replace the one admitted bootstrap revision for staged frontend reconnects. */
+    options?: { readonly bootstrap?: boolean },
+  ): Promise<HostAssembly>;
+  /** Observe accepted reports without replacing the owning host's callback. */
+  subscribeActivationReports(
+    listener: (report: HostActivationReport) => void | Promise<void>,
+  ): () => void;
   dispose(): Promise<void>;
 }
 
@@ -157,7 +166,6 @@ function assertBackendCatalogIdentity(
  */
 export async function createBackendHost(options: BackendHostOptions = {}): Promise<BackendHost> {
   const context = options.context ?? new Context();
-  const ownedContext = options.context === undefined;
   const realm = options.realm ?? 'engine';
   const catalog = options.catalog;
   const pairedBackendEntries =
@@ -188,7 +196,7 @@ export async function createBackendHost(options: BackendHostOptions = {}): Promi
     });
   const checkedInitial = validateHostAssembly(initialAssembly);
   if (!checkedInitial.ok) {
-    if (ownedContext) await context.fiber.dispose();
+    if (options.context === undefined) await context.fiber.dispose();
     throw checkedInitial.error;
   }
   const backendModules =
@@ -203,23 +211,27 @@ export async function createBackendHost(options: BackendHostOptions = {}): Promi
   // at the promoted full assembly from an earlier client.  Keep that one
   // staged revision valid for activation reports; all other revisions must
   // still match the current authority exactly.
-  const bootstrapRevision = checkedInitial.value.revision;
+  let bootstrapRevision = checkedInitial.value.revision;
+  const activationListeners = new Set<(report: HostActivationReport) => void | Promise<void>>();
   const transport = options.transport ?? createHostTransport();
-  let foundationFiber: Fiber | undefined;
+  let startup: HostStartup | undefined;
   let loaderFiber: Fiber | undefined;
   let loader: CatalogLoader | undefined;
   let backendEntries =
     options.pairs === undefined
       ? (options.entries ?? options.assembly?.entries ?? [])
       : pairedBackendEntries;
-  const startupFibers: Fiber[] = [];
   let unregisterAssemblyService: (() => void) | undefined;
   let unregisterActivationService: (() => void) | undefined;
   let unsubscribeAssembly: (() => void) | undefined;
   try {
-    foundationFiber = await context.plugin(hostFoundationPlugin(assembly, transport));
-    for (const plugin of options.startupPlugins ?? [])
-      startupFibers.push(await context.plugin(plugin));
+    startup = await createHostStartup({
+      context,
+      startupPlugins: [
+        hostFoundationPlugin(assembly, transport),
+        ...(options.startupPlugins ?? []),
+      ],
+    });
     if (catalog !== undefined) {
       const bootstrapped = await bootstrapCatalogLoader(context, catalog, realm, {
         catalogDigest: checkedInitial.value.revision,
@@ -250,6 +262,7 @@ export async function createBackendHost(options: BackendHostOptions = {}): Promi
           );
         }
         await options.onActivationReport?.(report);
+        for (const listener of activationListeners) await listener(report);
         return { accepted: true };
       },
     );
@@ -261,9 +274,7 @@ export async function createBackendHost(options: BackendHostOptions = {}): Promi
     unregisterAssemblyService?.();
     unsubscribeAssembly?.();
     await loaderFiber?.dispose();
-    for (const fiber of startupFibers.reverse()) await fiber.dispose();
-    await foundationFiber?.dispose();
-    if (ownedContext) await context.fiber.dispose();
+    await startup?.dispose();
     throw error;
   }
 
@@ -273,8 +284,22 @@ export async function createBackendHost(options: BackendHostOptions = {}): Promi
     ...(loader === undefined ? {} : { loader }),
     assembly,
     transport,
-    ownedContext,
-    async update(nextInput) {
+    ownedContext: options.context === undefined,
+    subscribeActivationReports(listener) {
+      if (disposed) {
+        throw new HostAssemblyError(
+          'host-assembly-service-unavailable',
+          'the backend host to remain active while observing activation reports',
+          'Subscribe on an active host instance.',
+          { service: HOST_ACTIVATION_REPORT_SERVICE },
+        );
+      }
+      activationListeners.add(listener);
+      return () => {
+        activationListeners.delete(listener);
+      };
+    },
+    async update(nextInput, updateOptions) {
       if (disposed) {
         throw new HostAssemblyError(
           'host-assembly-service-unavailable',
@@ -320,19 +345,19 @@ export async function createBackendHost(options: BackendHostOptions = {}): Promi
         await loader.await();
       }
       backendEntries = nextBackendEntries;
+      if (updateOptions?.bootstrap === true) bootstrapRevision = checkedCandidate.value.revision;
       return authority.publish(effectiveInput);
     },
     async dispose() {
       if (disposed) return;
       disposed = true;
+      activationListeners.clear();
       unsubscribeAssembly?.();
       unregisterActivationService?.();
       unregisterAssemblyService?.();
       transport.close();
       await loaderFiber?.dispose();
-      for (const fiber of startupFibers.reverse()) await fiber.dispose();
-      await foundationFiber?.dispose();
-      if (ownedContext) await context.fiber.dispose();
+      await startup?.dispose();
     },
   };
   return host;

package/src/frontend.ts

@@ -19,6 +19,7 @@ import {
   modulesFromCatalog,
   validateHostAssembly,
 } from './protocol.js';
+import { createHostStartup, type HostStartup } from './startup.js';
 import {
   HOST_ACTIVATION_REPORT_SERVICE,
   HOST_ASSEMBLY_SERVICE,
@@ -306,8 +307,7 @@ export async function createFrontendHost(options: FrontendHostOptions = {}): Pro
       return status;
     },
   };
-  const startupFibers: Fiber[] = [];
-  let foundationFiber: Fiber | undefined;
+  let startup: HostStartup | undefined;
   let loaderFiber: Fiber | undefined;
   let loader: CatalogLoader | undefined;
   let disposed = false;
@@ -356,9 +356,13 @@ export async function createFrontendHost(options: FrontendHostOptions = {}): Pro
   }
 
   try {
-    foundationFiber = await context.plugin(hostFoundationPlugin(state, options.transport));
-    for (const plugin of options.startupPlugins ?? [])
-      startupFibers.push(await context.plugin(plugin));
+    startup = await createHostStartup({
+      context,
+      startupPlugins: [
+        hostFoundationPlugin(state, options.transport),
+        ...(options.startupPlugins ?? []),
+      ],
+    });
     if (options.autoActivate !== false) {
       // Activation is performed below through the returned host so its status
       // callback and failure rollback cover the first assembly as well.
@@ -393,9 +397,7 @@ export async function createFrontendHost(options: FrontendHostOptions = {}): Pro
   } catch (error) {
     removeTransportDisconnect?.();
     await loaderFiber?.dispose();
-    for (const fiber of startupFibers.reverse()) await fiber.dispose();
-    await foundationFiber?.dispose();
-    if (ownedContext) await context.fiber.dispose();
+    await startup?.dispose();
     throw error;
   }
 
@@ -434,9 +436,7 @@ export async function createFrontendHost(options: FrontendHostOptions = {}): Pro
       disposed = true;
       removeTransportDisconnect?.();
       await loaderFiber?.dispose();
-      for (const fiber of startupFibers.reverse()) await fiber.dispose();
-      await foundationFiber?.dispose();
-      if (ownedContext) await context.fiber.dispose();
+      await startup?.dispose();
       status = { state: 'disposed', revision: current.revision };
     },
   };

package/src/index.ts

@@ -36,6 +36,7 @@ export {
   modulesFromCatalog,
   validateHostAssembly,
 } from './protocol.js';
+export { createHostStartup, type HostStartup, type HostStartupOptions } from './startup.js';
 export {
   attachHostWebSocketServer,
   connectHostWebSocket,

package/src/protocol.ts

@@ -116,7 +116,12 @@ export interface HostAssemblyErrorDetailByCode {
   'host-assembly-service-unavailable': { readonly service: string };
   'host-assembly-stale-request': { readonly service: string; readonly generation: number };
   'host-assembly-request-aborted': { readonly service: string };
-  'host-transport-failure': { readonly service: string; readonly reason: string };
+  'host-transport-failure': {
+    readonly service: string;
+    readonly reason: string;
+    /** Business error code received from a remote host service, if any. */
+    readonly remoteCode?: string;
+  };
   'host-assembly-not-ready': {
     readonly entryId: string;
     readonly fiberState: string;

package/src/startup.ts

@@ -0,0 +1,43 @@
+import { Context, type Fiber, type Plugin } from '@forgeax/engine-plugin';
+
+/**
+ * The product-neutral host bootstrap. It owns only a Cordis Context and the
+ * supplied startup entries; assembly, transport, Project, and App are all
+ * ordinary plugins layered above this seam.
+ */
+export interface HostStartupOptions {
+  readonly context?: Context;
+  readonly startupPlugins?: readonly Plugin[];
+}
+
+export interface HostStartup {
+  readonly context: Context;
+  readonly ownedContext: boolean;
+  readonly fibers: readonly Fiber[];
+  dispose(): Promise<void>;
+}
+
+export async function createHostStartup(options: HostStartupOptions = {}): Promise<HostStartup> {
+  const context = options.context ?? new Context();
+  const ownedContext = options.context === undefined;
+  const fibers: Fiber[] = [];
+  let disposed = false;
+  try {
+    for (const plugin of options.startupPlugins ?? []) fibers.push(await context.plugin(plugin));
+  } catch (error) {
+    for (const fiber of fibers.reverse()) await fiber.dispose();
+    if (ownedContext) await context.fiber.dispose();
+    throw error;
+  }
+  return {
+    context,
+    ownedContext,
+    fibers,
+    async dispose(): Promise<void> {
+      if (disposed) return;
+      disposed = true;
+      for (const fiber of [...fibers].reverse()) await fiber.dispose();
+      if (ownedContext) await context.fiber.dispose();
+    },
+  };
+}

package/src/transport.ts

@@ -431,8 +431,10 @@ function errorFromSummary(service: string, summary: HostErrorSummary): HostAssem
     );
   }
   return new HostAssemblyError('host-transport-failure', summary.expected, summary.hint, {
+    ...detail,
     service,
     reason: summary.detail.reason ? String(summary.detail.reason) : summary.code,
+    remoteCode: summary.code,
   });
 }