@forgeax/engine-host 0.1.27 → 0.1.28

package/dist/startup.d.ts

@@ -0,0 +1,18 @@
+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 declare function createHostStartup(options?: HostStartupOptions): Promise<HostStartup>;
+//# sourceMappingURL=startup.d.ts.map

package/dist/startup.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"startup.d.ts","sourceRoot":"","sources":["../src/startup.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,KAAK,KAAK,EAAE,KAAK,MAAM,EAAE,MAAM,wBAAwB,CAAC;AAE1E;;;;GAIG;AACH,MAAM,WAAW,kBAAkB;IACjC,QAAQ,CAAC,OAAO,CAAC,EAAE,OAAO,CAAC;IAC3B,QAAQ,CAAC,cAAc,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;CAC7C;AAED,MAAM,WAAW,WAAW;IAC1B,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC;IAC1B,QAAQ,CAAC,YAAY,EAAE,OAAO,CAAC;IAC/B,QAAQ,CAAC,MAAM,EAAE,SAAS,KAAK,EAAE,CAAC;IAClC,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CAC1B;AAED,wBAAsB,iBAAiB,CAAC,OAAO,GAAE,kBAAuB,GAAG,OAAO,CAAC,WAAW,CAAC,CAuB9F"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@forgeax/engine-host",
-  "version": "0.1.27",
+  "version": "0.1.28",
   "private": false,
   "type": "module",
   "license": "Apache-2.0",
@@ -45,7 +45,7 @@
   ],
   "dependencies": {
     "@deepseek-ai/cordis-plugin-loader": "1.0.2",
-    "@forgeax/engine-plugin": "0.1.27"
+    "@forgeax/engine-plugin": "0.1.28"
   },
   "devDependencies": {
     "@types/node": "^20.14.0",

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,
@@ -157,7 +158,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 +188,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 =
@@ -205,21 +205,24 @@ export async function createBackendHost(options: BackendHostOptions = {}): Promi
   // still match the current authority exactly.
   const bootstrapRevision = checkedInitial.value.revision;
   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,
@@ -261,9 +264,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,7 +274,7 @@ export async function createBackendHost(options: BackendHostOptions = {}): Promi
     ...(loader === undefined ? {} : { loader }),
     assembly,
     transport,
-    ownedContext,
+    ownedContext: options.context === undefined,
     async update(nextInput) {
       if (disposed) {
         throw new HostAssemblyError(
@@ -330,9 +331,7 @@ export async function createBackendHost(options: BackendHostOptions = {}): Promi
       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/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();
+    },
+  };
+}