@nwire/endpoint 0.10.0 → 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

@@ -28,7 +28,7 @@
  * ## Why this exists
  *
  * Every framework eventually needs a process layer — something that knows
- * about SIGTERM, drains in-flight requests, exposes `/healthz`, and binds
+ * about SIGTERM, drains in-flight requests, exposes `/live`, and binds
  * to a port. Most frameworks bolt this on as a deployment afterthought.
  * `@nwire/endpoint` makes it the first-class entry point so you don't
  * write the same K8s-readiness code on every project. It works alone —
@@ -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

@@ -28,7 +28,7 @@
  * ## Why this exists
  *
  * Every framework eventually needs a process layer — something that knows
- * about SIGTERM, drains in-flight requests, exposes `/healthz`, and binds
+ * about SIGTERM, drains in-flight requests, exposes `/live`, and binds
  * to a port. Most frameworks bolt this on as a deployment afterthought.
  * `@nwire/endpoint` makes it the first-class entry point so you don't
  * write the same K8s-readiness code on every project. It works alone —
@@ -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.
@@ -405,7 +435,7 @@ function printBanner(opts) {
             : `   data:   (no HTTP listener)`,
     ];
     if (opts.probePort !== undefined) {
-        // lightship's actual paths — not /readyz + /healthz (which was a
+        // lightship's actual paths — not /ready + /live (which was a
         // historical misnaming in our docs).
         lines.push(`   probes: http://${opts.host}:${opts.probePort}/live · /ready`);
     }

package/dist/lifecycle.d.ts

@@ -7,13 +7,13 @@
  *     `server.close()`. Without it, in-flight requests on persistent
  *     connections silently die when the process exits.
  *   - **lightship**       — Kubernetes-style readiness/liveness probes on a
- *     separate operational port. Flips `/readyz` to 503 the moment shutdown
+ *     separate operational port. Flips `/ready` to 503 the moment shutdown
  *     starts so the load balancer stops sending new traffic — the single
  *     most important step in a zero-downtime rolling deploy.
  *
  * Sequence on SIGTERM/SIGINT:
  *
- *   1. lightship: /readyz → 503        (LB removes us from rotation)
+ *   1. lightship: /ready → 503        (LB removes us from rotation)
  *   2. wait `drainDelay`               (LB has time to catch up; default 10s)
  *   3. stop accepting new connections  (http-terminator)
  *   4. drain in-flight requests        (http-terminator; bounded by drainTimeout)
@@ -105,7 +105,7 @@ export interface LifecycleManager {
     addCheck(check: HealthCheck): void;
     /**
      * Bare Node http handler for probes-on-main deployments. Mount on your
-     * own HTTP server's /livez and /readyz routes; the third arg picks which.
+     * own HTTP server's /live and /ready routes; the third arg picks which.
      * No framework lock-in — works with Express, Fastify, Koa, raw http.
      */
     probeHandler(req: {

package/dist/lifecycle.js

@@ -7,13 +7,13 @@
  *     `server.close()`. Without it, in-flight requests on persistent
  *     connections silently die when the process exits.
  *   - **lightship**       — Kubernetes-style readiness/liveness probes on a
- *     separate operational port. Flips `/readyz` to 503 the moment shutdown
+ *     separate operational port. Flips `/ready` to 503 the moment shutdown
  *     starts so the load balancer stops sending new traffic — the single
  *     most important step in a zero-downtime rolling deploy.
  *
  * Sequence on SIGTERM/SIGINT:
  *
- *   1. lightship: /readyz → 503        (LB removes us from rotation)
+ *   1. lightship: /ready → 503        (LB removes us from rotation)
  *   2. wait `drainDelay`               (LB has time to catch up; default 10s)
  *   3. stop accepting new connections  (http-terminator)
  *   4. drain in-flight requests        (http-terminator; bounded by drainTimeout)
@@ -53,8 +53,8 @@ export async function attachLifecycle(opts) {
     const healthCfg = {
         enabled: opts.health?.enabled ?? true,
         port: opts.health?.port ?? 9_400,
-        livenessPath: opts.health?.livenessPath ?? "/healthz",
-        readinessPath: opts.health?.readinessPath ?? "/readyz",
+        livenessPath: opts.health?.livenessPath ?? "/live",
+        readinessPath: opts.health?.readinessPath ?? "/ready",
         checks: opts.health?.checks ?? [],
     };
     const terminator = createHttpTerminator({
@@ -138,9 +138,9 @@ export async function attachLifecycle(opts) {
         try {
             if (lightship) {
                 lightship.signalNotReady();
-                console.log(`[lifecycle] /readyz → 503; waiting ${shutdownCfg.drainDelay}ms for LB to catch up`);
+                console.log(`[lifecycle] /ready → 503; waiting ${shutdownCfg.drainDelay}ms for LB to catch up`);
                 // The drain delay exists to give the LB time to redirect traffic
-                // after /readyz flips to 503. Without lightship, there's no probe
+                // after /ready flips to 503. Without lightship, there's no probe
                 // for an LB to poll — waiting would just stall shutdown.
                 await new Promise((r) => setTimeout(r, shutdownCfg.drainDelay));
             }
@@ -166,13 +166,13 @@ export async function attachLifecycle(opts) {
     process.once("SIGTERM", () => void shutdown("SIGTERM"));
     process.once("SIGINT", () => void shutdown("SIGINT"));
     /**
-     * Bare Node http handler for `/livez` / `/readyz` on the MAIN port. Use
+     * Bare Node http handler for `/live` / `/ready` on the MAIN port. Use
      * when probes-on-main is the deployment shape (Cloud Run, Lambda Function
      * URLs, simple K8s sidecar-free setups).
      *
      *   const probeHandler = lifecycle.probeHandler;
-     *   expressApp.get("/livez", (req, res) => probeHandler(req, res, "live"));
-     *   expressApp.get("/readyz", (req, res) => probeHandler(req, res, "ready"));
+     *   expressApp.get("/live", (req, res) => probeHandler(req, res, "live"));
+     *   expressApp.get("/ready", (req, res) => probeHandler(req, res, "ready"));
      *
      * `live` is always 200 unless the process is shutting down.
      * `ready` is 200 only when all checks pass AND we're not shutting down.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nwire/endpoint",
-  "version": "0.10.0",
+  "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/container": "0.10.0",
-    "@nwire/hooks": "0.10.0",
-    "@nwire/wires": "0.10.0",
-    "@nwire/logger": "0.10.0"
+    "@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",