@nwire/endpoint 0.10.1 → 0.11.0

package/README.md

@@ -18,10 +18,7 @@ import { httpKoa } from "@nwire/koa";
 const app = createApp({ appName: "api" });
 // ... app.wire(...) wires here ...
 
-await endpoint("api", { port: 3000 })
-  .use(httpKoa())
-  .mount(app)
-  .run();
+await endpoint("api", { port: 3000 }).use(httpKoa()).mount(app).run();
 ```
 
 `.use(adopter)` installs a transport runtime — `httpKoa`, `expressAdapter`,
@@ -70,12 +67,12 @@ through the runtime when forge is in play, or directly otherwise.
 
 ## Lifecycle
 
-| Stage     | What runs                                              |
-| --------- | ------------------------------------------------------ |
-| `boot`    | App plugins boot; adopters consume wires; probes open. |
-| `serve`   | Adopters listen / subscribe; readiness flips green.    |
-| `drain`   | SIGTERM/SIGINT: stop accepting new work, finish open.  |
-| `close`   | Adopters shut down in reverse order; probes close.     |
+| Stage   | What runs                                              |
+| ------- | ------------------------------------------------------ |
+| `boot`  | App plugins boot; adopters consume wires; probes open. |
+| `serve` | Adopters listen / subscribe; readiness flips green.    |
+| `drain` | SIGTERM/SIGINT: stop accepting new work, finish open.  |
+| `close` | Adopters shut down in reverse order; probes close.     |
 
 `endpoint()` returns a `RunningEndpoint` from `.run()`. Tests call
 `running.shutdown("test")` to skip the SIGTERM dance.
@@ -84,10 +81,10 @@ through the runtime when forge is in play, or directly otherwise.
 
 ```ts
 endpoint("api", {
-  banner: true,                       // boot banner on stdout
+  banner: true, // boot banner on stdout
   probes: { port: 9_400, enabled: true },
   shutdown: { drainTimeout: 30_000, hardTimeout: 5_000 },
-  exitOnShutdown: true,               // tests pass false
+  exitOnShutdown: true, // tests pass false
 });
 ```
 

package/dist/adapter.d.ts

@@ -12,6 +12,7 @@
 import type { Wire } from "@nwire/wires";
 import type { Container } from "@nwire/container";
 import type { Logger } from "@nwire/logger";
+import type { OutboundStage } from "@nwire/runtime";
 import type { HealthCheck } from "./lifecycle.js";
 export interface AdapterBootContext {
     /**
@@ -38,15 +39,39 @@ export interface AdapterBootContext {
     readonly port?: number;
     /** Endpoint-level host hint, paired with `port`. */
     readonly host?: string;
+    /**
+     * Install an outbound pipeline stage on the mounted App's runtime.
+     * Outbound adapters (queuePublisher, natsPublisher, webhookSink, …) call
+     * this at boot to install their terminal stage; inbound adapters ignore
+     * it. Undefined when no App is mounted — the adapter is free to skip
+     * or fall back to a foreign-host integration.
+     */
+    readonly installSinkStage?: (stage: OutboundStage) => void;
 }
 /**
  * Structural shape every transport adopter satisfies. Adopters never
  * extend a base class — the contract is duck-typed at the endpoint.
+ *
+ * `direction` distinguishes the two membrane roles:
+ *
+ *   - "inbound"  — transport → execute. HTTP server, queue listener, cron.
+ *                  These consume wires and translate inbound traffic to
+ *                  `app.execute(handler, input)`.
+ *
+ *   - "outbound" — sink → transport. Queue publisher, NATS publisher,
+ *                  webhook delivery, OTLP exporter. These install a
+ *                  terminal sink stage at boot and translate published
+ *                  events into transport messages.
+ *
+ * Optional, defaulting to "inbound" so adapters that haven't declared
+ * direction continue to behave as inbound transports.
  */
 export interface Adapter {
     readonly $kind: "adapter";
     /** Adopter-kind tag — matches `binding.$adapter` on the wires it consumes. */
     readonly kind: string;
+    /** Membrane direction. Defaults to "inbound" if absent. */
+    readonly direction?: "inbound" | "outbound";
     boot(opts: AdapterBootContext): Promise<void>;
     shutdown(reason?: string): Promise<void>;
     /**

package/dist/endpoint-index.d.ts

@@ -19,6 +19,6 @@
  * (`http-terminator` + `lightship`). The high-level builder is what most
  * projects reach for; the low-level form is for adapters and tests.
  */
-export { endpoint, EndpointBuilder, isAppServable, isForeignServable, type AppServable, type EndpointConfig, type ForeignServable, type RunningEndpoint, type Servable, } from "./endpoint.js";
+export { endpoint, EndpointBuilder, isAppServable, isForeignServable, type AppServable, type EndpointConfig, type ProcessConfig, type ForeignServable, type RunningEndpoint, type Servable, } from "./endpoint.js";
 export { attachLifecycle, defineCheck, type HealthCheck, type HealthConfig, type LifecycleManager, type ShutdownConfig, } from "./lifecycle.js";
 export { isAdapter, type Adapter, type AdapterBootContext } from "./adapter.js";

package/dist/endpoint.d.ts

@@ -90,7 +90,12 @@ export interface ForeignServable {
 export interface AppServable {
     readonly $nwireApp: true;
     readonly container: Container;
-    boot(): Promise<void>;
+    /**
+     * Boot the app. Optional `appConfig` — when present, bound on the app's
+     * container as "config" so plugin boot callbacks can read it (foundation
+     * §19). Endpoint threads what was passed to `.mount(app, appConfig)`.
+     */
+    boot(appConfig?: unknown): Promise<void>;
     shutdown(): Promise<void>;
     /**
      * Optional — app name used in lifecycle event payloads. Defaults to
@@ -105,6 +110,12 @@ export interface AppServable {
      */
     dispatchFrameworkEvent?(eventName: string, payload: unknown): Promise<boolean>;
 }
+/**
+ * Process-level configuration for an endpoint. Owns OS-shaped concerns
+ * only: port, bind address, signal/drain budgets, probe port, banner
+ * toggle. App-level configuration (database URLs, API keys, feature
+ * flags) goes through `.mount(app, appConfig)`.
+ */
 export interface EndpointConfig {
     /** Port for HTTP-class transports. Omit for queue-only / cron-only endpoints. */
     readonly port?: number;
@@ -119,6 +130,8 @@ export interface EndpointConfig {
     /** Test seam — skip process.exit() during shutdown. Default unset. */
     readonly exitOnShutdown?: boolean;
 }
+/** Foundation §19 alias — `endpoint("name", processConfig)` reads as intent. */
+export type ProcessConfig = EndpointConfig;
 export interface RunningEndpoint {
     readonly name: string;
     readonly server?: Server;
@@ -162,6 +175,8 @@ export declare class EndpointBuilder {
     private foreignServables;
     private adapters;
     private mounted;
+    /** App config threaded into `app.boot(...)` at `run()`. */
+    private mountedAppConfig;
     /**
      * Per-phase lifecycle hooks. Created lazily at builder-construction so
      * they appear in `listHooks()` (and `.nwire/hooks.json` after scan)
@@ -192,10 +207,17 @@ export declare class EndpointBuilder {
     use(adopter: Adapter): EndpointBuilder;
     /**
      * Mount the source whose wires the adopters consume. One source per
-     * endpoint — App or standalone Interface. For multi-app topologies,
-     * compose via `appCompose(...)` from `@nwire/app` and mount the result.
+     * endpoint — an App or a standalone Interface. For multi-app
+     * topologies, compose via `appCompose(...)` from `@nwire/app` and
+     * mount the result.
+     *
+     * `appConfig` (when mounting an App) is threaded to `app.boot(appConfig)`
+     * at `.run()` time. Plugin boot callbacks read it via
+     * `container.resolve("config")`. The process/app config split:
+     * process config goes to `endpoint(name, processConfig)`, app config
+     * goes here.
      */
-    mount(source: WireSource): EndpointBuilder;
+    mount(source: WireSource, appConfig?: unknown): EndpointBuilder;
     /**
      * Boot all served apps in order, then attach all served interfaces +
      * foreign apps, then start listening. Returns a {@link RunningEndpoint}

package/dist/endpoint.js

@@ -81,6 +81,8 @@ export class EndpointBuilder {
     // ─── New-shape state (.use / .mount) ─────────────────────────────────
     adapters = [];
     mounted;
+    /** App config threaded into `app.boot(...)` at `run()`. */
+    mountedAppConfig = undefined;
     /**
      * Per-phase lifecycle hooks. Created lazily at builder-construction so
      * they appear in `listHooks()` (and `.nwire/hooks.json` after scan)
@@ -146,10 +148,17 @@ export class EndpointBuilder {
     }
     /**
      * Mount the source whose wires the adopters consume. One source per
-     * endpoint — App or standalone Interface. For multi-app topologies,
-     * compose via `appCompose(...)` from `@nwire/app` and mount the result.
+     * endpoint — an App or a standalone Interface. For multi-app
+     * topologies, compose via `appCompose(...)` from `@nwire/app` and
+     * mount the result.
+     *
+     * `appConfig` (when mounting an App) is threaded to `app.boot(appConfig)`
+     * at `.run()` time. Plugin boot callbacks read it via
+     * `container.resolve("config")`. The process/app config split:
+     * process config goes to `endpoint(name, processConfig)`, app config
+     * goes here.
      */
-    mount(source) {
+    mount(source, appConfig) {
         if (this.mounted) {
             throw new Error(`endpoint("${this.name}").mount(): a source is already mounted ("${"appName" in this.mounted ? this.mounted.appName : "interface"}"). ` +
                 `One source per endpoint — use appCompose(...) from "@nwire/app" to compose multiple apps.`);
@@ -158,6 +167,7 @@ export class EndpointBuilder {
             throw new Error(`endpoint("${this.name}").mount(): expected an App with .interface, or a standalone Interface.`);
         }
         this.mounted = source;
+        this.mountedAppConfig = appConfig;
         // If mounting an App, also boot it via the existing apps array.
         if (isAppWithInterface(source) && !this.apps.includes(source)) {
             this.apps.push(source);
@@ -200,7 +210,15 @@ export class EndpointBuilder {
             startedAt: new Date().toISOString(),
         });
         for (const app of this.apps) {
-            await app.boot();
+            // Pass appConfig only to the mounted app — appCompose sub-apps don't
+            // carry their own per-app config in this path.
+            const appConfig = this.mounted && app === this.mounted ? this.mountedAppConfig : undefined;
+            if (appConfig !== undefined) {
+                await app.boot(appConfig);
+            }
+            else {
+                await app.boot();
+            }
         }
         // The container the host hands to each adopter — the first served
         // app's. Multi-app composites carry per-wire app references that
@@ -243,14 +261,24 @@ export class EndpointBuilder {
                 ? mountedSource
                 : mountedSource.interface;
         const containerOf = (_w) => {
-            // For 0.10 first pass, route every wire to the mounted source's
-            // container (if it's an App). Multi-app composites carry per-wire
-            // app references on the wire (.app); future work uses that for
-            // per-wire container routing.
+            // Wires tagged with a source app (via `appCompose`) route to that
+            // app's container; un-tagged wires fall back to the mounted
+            // source's container.
             const sourceApp = mountedSource && !isInterfaceShape(mountedSource) ? mountedSource : undefined;
             const wireApp = _w.app;
             return wireApp?.container ?? sourceApp?.container;
         };
+        // Outbound adapters install sink terminals on the mounted App's
+        // runtime at boot. Available only when an App with a Runtime is
+        // mounted.
+        const mountedAppRuntime = mountedSource && isAppWithInterface(mountedSource)
+            ? mountedSource.runtime
+            : undefined;
+        const installSinkStage = mountedAppRuntime?.sink
+            ? (stage) => {
+                mountedAppRuntime.sink(stage);
+            }
+            : undefined;
         for (const adopter of this.adapters) {
             const wires = sourceInterface?.forAdapter(adopter.kind) ?? [];
             await adopter.boot({
@@ -260,6 +288,8 @@ export class EndpointBuilder {
                 addCheck: (c) => accumulatedChecks.push(c),
                 port: this.config.port,
                 host: this.config.host,
+                // eslint-disable-next-line @typescript-eslint/no-explicit-any
+                installSinkStage: installSinkStage,
             });
         }
         // 3. Wrap the server (if any) with graceful shutdown + probes.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nwire/endpoint",
-  "version": "0.10.1",
+  "version": "0.11.0",
   "description": "Nwire — production process lifecycle. Wraps any Node server (Express, Fastify, Koa, Nest, Nwire interfaces) with K8s-grade graceful shutdown, http-terminator drain, and lightship readiness/liveness probes. Standalone — no framework dependency beyond @nwire/container.",
   "keywords": [
     "endpoint",
@@ -32,10 +32,11 @@
   "dependencies": {
     "http-terminator": "^3.2.0",
     "lightship": "^9.0.4",
-    "@nwire/hooks": "0.10.1",
-    "@nwire/container": "0.10.1",
-    "@nwire/logger": "0.10.1",
-    "@nwire/wires": "0.10.1"
+    "@nwire/hooks": "0.11.0",
+    "@nwire/runtime": "0.11.0",
+    "@nwire/container": "0.11.0",
+    "@nwire/wires": "0.11.0",
+    "@nwire/logger": "0.11.0"
   },
   "devDependencies": {
     "@types/node": "^22.19.9",