@aopslabs/host-shell

A reusable configuration, plugin-bootstrap, and HTTP runtime shell for AOPS Labs plugin hosts.

The manifest adapter accepts versioned route-safety catalog entries containing gateClass, raw sideEffect, and optional policy.safety. A catalog must be entirely legacy or entirely v2; mixed declarations fail before plugin load.

Installation

```bash npm install @aopslabs/host-shell ```

The shell resolves static or installed-registration profiles, applies explicit environment bindings, loads allowlisted plugins, projects manifest policies, and serves health, bootstrap, admission-gated discovery, strict invocation, setup, and domain HTTP routes.

South-oracle hosts can opt into the application-bound authority contract with authority.southOracle.authorityMode=projection-v2 plus exact applicationSlug and audience values. Environment overrides use the brand-prefixed *_SOUTH_ORACLE_AUTHORITY_MODE, *_SOUTH_ORACLE_APPLICATION_SLUG, and *_SOUTH_ORACLE_AUDIENCE keys. The application and audience remain server-owned; callers cannot select them.

Runtime lifecycle

bootstrapHostRuntime({ pluginFactoryOptions }) accepts an app-owned map of runtime dependencies keyed by enabled domain. Values are merged only into the plugin factory invocation; the resolved config, HRM, manifests and diagnostic payloads remain plain. Diagnostics expose injected key names only. Unknown or disabled domains, collisions with configured JSON options, and the reserved hostHttpRoutes, hostLifecycle and hostManifestAdapter keys fail before bootstrap. This option requires a function export. Apps using it own the captured resource cleanup and must register it immediately after acquisition. loadHostPluginModule(plugin, resolvedConfig) uses the same module resolution and strict allowlist as bootstrap, allowing a host to capture dependencies from the installed plugin namespace without adding transport metadata to an HRM.

createHostLifecycleQueue().run(...) serializes only create/reset/dispose transitions. Each caller receives its own failure; a rejected transition does not poison the queue. The application keeps its current runtime and refuses to create a replacement until disposal succeeds.

Use createHostOperationScope().run(...) around the whole service/invoke call. Ordinary operations remain parallel. drain() rejects new work and waits for all accepted work, including work whose HTTP caller disconnected or stopped waiting. Its default 30-second timeout bounds the caller's wait; it retains pending work and a later drain() observes the same completion. Stop admission/worker intake, drain operations, close plugins, then close application-owned resources. SvelteKit hosts can use these helpers without bootstrapHostRuntime or startHostServer.

createHostCleanupStack() registers cleanup immediately after each acquisition and closes in reverse order. It awaits every step and collects failures. Concurrent close callers share an attempt; successful steps are not repeated, failed steps remain for an explicit retry. Callbacks must be idempotent and retain their underlying resource and close promise on failure (for example, the XF PG owner's end-once close). A timeout or rejected close is not successful disposal.

bootstrapHostRuntime registers declared lifecycle hooks before invoking each plugin factory. Failed bootstrap closes both partially initialized and previously loaded plugins. If cleanup also fails, HostBootstrapCleanupError preserves the original cause and the cleanup stack for retry; the app must retain that failure and block a new generation. Use closeHostRuntime(runtime) for awaited, idempotent kernel cleanup. startHostServer().stop() also drains HTTP operations before kernel cleanup, including operations left running by closed connections. These helpers have no PostgreSQL driver dependency or database selection policy.

License

Copyright (c) 2026 Mehmet Zeki Sönmez. Licensed under the PolyForm Strict License 1.0.0; see LICENSE.