@forgeax/engine-host 0.1.28 → 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/backend.ts

@@ -60,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>;
 }
 
@@ -203,7 +211,8 @@ 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 startup: HostStartup | undefined;
   let loaderFiber: Fiber | undefined;
@@ -253,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 };
       },
     );
@@ -275,7 +285,21 @@ export async function createBackendHost(options: BackendHostOptions = {}): Promi
     assembly,
     transport,
     ownedContext: options.context === undefined,
-    async update(nextInput) {
+    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',
@@ -321,11 +345,13 @@ 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?.();

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/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,
   });
 }