@nwire/endpoint 0.9.1 → 0.10.0

package/README.md

@@ -1,105 +1,112 @@
 # @nwire/endpoint
 
-> Process lifecycle for any Node server — graceful shutdown, K8s probes, signal handling. The only Nwire layer that talks to the operating system.
-
-Wraps any Node server (Express, Fastify, Koa, Nest, Hono, raw `http`, or
-a Nwire interface) with `http-terminator` drain, `lightship` readiness /
-liveness probes on a dedicated port, signal handling, and ordered
-shutdown. Boots Nwire apps + mounts Nwire interfaces in the same managed
-process.
+> Process lifecycle — boot an app under one or more transports, drain
+> in-flight work on SIGTERM, surface K8s probes. The only Nwire layer
+> that talks to the operating system.
 
 ```bash
 pnpm add @nwire/endpoint
 ```
 
-## Quick example — Nwire app + interface
+## Quick example
 
 ```ts
+import { createApp } from "@nwire/app";
 import { endpoint } from "@nwire/endpoint";
-import { createApp } from "@nwire/forge";
-import { httpInterface, get } from "@nwire/http";
+import { httpKoa } from "@nwire/koa";
 
-const app = createApp({ modules: [stations] });
-const api = httpInterface({ prefix: "/api" }).wire(get("/health"), async () => ({ ok: true }));
+const app = createApp({ appName: "api" });
+// ... app.wire(...) wires here ...
 
 await endpoint("api", { port: 3000 })
-  .serve(app) // boots container first
-  .serve(api) // attaches HTTP routes
+  .use(httpKoa())
+  .mount(app)
   .run();
 ```
 
-## Quick example — foreign framework
+`.use(adopter)` installs a transport runtime — `httpKoa`, `expressAdapter`,
+`queueInMemory`, `bullmqAdapter`, `mcpAdapter`, `cronAdapter`. Each adopter
+consumes the wires whose binding matches its kind. Stack as many as you
+want on one endpoint; the same wires run under all of them.
+
+## Multi-transport example
 
 ```ts
-import express from "express";
+import { createApp } from "@nwire/app";
 import { endpoint } from "@nwire/endpoint";
+import { httpKoa } from "@nwire/koa";
+import { queueInMemory } from "@nwire/queue";
+import { mcpAdapter } from "@nwire/mcp";
+
+await endpoint("svc", { port: 3000 })
+  .use(httpKoa({ prefix: "/api" }))
+  .use(queueInMemory())
+  .use(mcpAdapter())
+  .mount(app)
+  .run();
+```
 
-const app = express();
-app.get("/", (_req, res) => res.send("hi"));
+## Adopter contract
 
-await endpoint("legacy", { port: 3000 }).serve(app).run();
-// Now lives behind K8s probes + graceful shutdown.
+```ts
+interface Adapter {
+  readonly $kind: "adapter";
+  readonly kind: string; // "http", "queue", "mcp", ...
+  boot(ctx: AdapterBootContext): Promise<void>;
+  shutdown(reason?: string): Promise<void>;
+}
+
+interface AdapterBootContext {
+  readonly wires: ReadonlyArray<Wire>;
+  containerOf(wire: Wire): Container | undefined;
+  readonly logger: Logger;
+  addCheck(check: HealthCheck): void;
+}
 ```
 
-## Surface
+Each adopter receives the full wire collection at boot, picks the ones it
+serves (`binding.$adapter === <its kind>`), and dispatches handlers
+through the runtime when forge is in play, or directly otherwise.
+
+## Lifecycle
 
-| Export                                                    | Role                                                         |
-| --------------------------------------------------------- | ------------------------------------------------------------ |
-| `endpoint(name, config)`                                  | Builder entry. Chain `.serve(target)`, `.run()`.             |
-| `EndpointBuilder`                                         | The chainable type returned by `endpoint()`.                 |
-| `attachLifecycle(opts)`                                   | Low-level escape hatch when you already own a Node `Server`. |
-| `defineCheck(name, fn)`                                   | Readiness probe contributor; aggregated into `/ready`.       |
-| `isNwireServable` / `isAppServable` / `isForeignServable` | Type guards for `.serve()` discrimination.                   |
-| `RunningEndpoint`                                         | Resolved value from `.run()` — exposes `shutdown(reason)`.   |
+| 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.     |
 
-### Config
+`endpoint()` returns a `RunningEndpoint` from `.run()`. Tests call
+`running.shutdown("test")` to skip the SIGTERM dance.
+
+## Config
 
 ```ts
 endpoint("api", {
-  port: 3000, // omit for queue/cron-only endpoints
-  host: "0.0.0.0",
-  banner: true, // boot banner on stdout
-  probes: { port: 9_400, checks: [redisProbe] },
-  shutdown: {
-    timeoutMs: 30_000,
-    onShutdown: async () => {
-      /* … */
-    },
-  },
-  exitOnShutdown: true, // test seam — skip process.exit()
+  banner: true,                       // boot banner on stdout
+  probes: { port: 9_400, enabled: true },
+  shutdown: { drainTimeout: 30_000, hardTimeout: 5_000 },
+  exitOnShutdown: true,               // tests pass false
 });
 ```
 
-### What `.serve()` accepts
-
-| Target                                   | Detection                 | Behavior                                        |
-| ---------------------------------------- | ------------------------- | ----------------------------------------------- |
-| Nwire interface (e.g. `httpInterface()`) | `$nwireServable === true` | Attached to a host (HTTP / queue / …).          |
-| Nwire app (`createApp`)                  | `$nwireApp === true`      | Booted first; its container fulfils interfaces. |
-| Express / Fastify / Koa / Nest           | Has `.listen(port, …)`    | Wrapped with terminator + probes.               |
-
-Multiple `.serve()` calls compose: apps boot in declaration order;
-interfaces attach after; shutdown runs in reverse.
+## Probes
 
-### Lifecycle observation
+When `probes.enabled` is true, a separate HTTP server on
+`probes.port` (default 9400) serves:
 
-Each `endpoint(name, ...)` instance creates three named hooks
-(`endpoint.boot:<name>`, `endpoint.serve:<name>`, `endpoint.shutdown:<name>`)
-on construction so they appear in `listHooks()` and `.nwire/hooks.json`
-before any `.run()`. Plugins layer `.use()` / `.on()` to extend a phase
-without monkey-patching the builder. App runtimes that expose
-`adoptHook` get the taps routed into telemetry automatically.
+- `GET /live` — liveness; 200 if the process is up
+- `GET /ready` — readiness; 200 once boot completes and all `addCheck()`
+  contributors pass
 
-The builder also fires `WireMounting` / `WireMounted` / `WireUnmounted`
-on every served app's `FrameworkEventBus`, plus `AppReady` once
-lightship flips `/ready` to 200.
+Both are intentionally on a separate port from the app — Kubernetes can
+poll them without touching the app's traffic.
 
 ## Related
 
-- `@nwire/http` — produces `NwireServable` instances via `httpInterface()`.
-- `@nwire/app` — declares the `WireMounting` / `AppReady` framework events fired here.
-- `@nwire/hooks` — the dispatch substrate behind the three per-endpoint hooks.
-
-## Status
-
-v0.x — builder API + framework events + per-endpoint hooks are locked. Multi-foreign-framework on one port is intentionally unsupported.
+- [`@nwire/app`](../core-app) — produces the App that adopters mount
+- [`@nwire/wires`](../core-wires) — the binding kinds adopters consume
+- [`@nwire/koa`](../nwire-koa) — canonical HTTP adopter
+- [`@nwire/queue`](../nwire-queue) — in-memory queue adopter (`@nwire/bullmq` for production)
+- [`@nwire/mcp`](../nwire-mcp) — Model Context Protocol adopter

package/dist/adapter.d.ts

@@ -0,0 +1,62 @@
+/**
+ * `Adapter` contract — what every transport runtime (`@nwire/koa`,
+ * `@nwire/bullmq`, `@nwire/mcp`, `@nwire/cron`, …) implements.
+ *
+ * The endpoint hands each adopter its slice of wires + a `containerOf`
+ * resolver that maps each wire back to its source app's container.
+ * Adopter ownership is bounded: filter wires by `kind`, build the
+ * transport runtime, start serving, drain on shutdown.
+ *
+ * `endpoint("api").use(adopter).mount(source).run()` is the nwire path.
+ */
+import type { Wire } from "@nwire/wires";
+import type { Container } from "@nwire/container";
+import type { Logger } from "@nwire/logger";
+import type { HealthCheck } from "./lifecycle.js";
+export interface AdapterBootContext {
+    /**
+     * Wires the adopter should consume — already filtered to the adopter's
+     * kind by the endpoint (the endpoint calls `interface.forAdapter(kind)`
+     * before invoking boot).
+     */
+    readonly wires: readonly Wire[];
+    /**
+     * Resolve a wire to its source app's container. Returns `undefined`
+     * for wires that came from a standalone interface (no app); adopters
+     * fall back to a `dummyContainer()` or skip resolution as appropriate.
+     */
+    readonly containerOf: (wire: Wire) => Container | undefined;
+    /** Logger handed in by the endpoint. */
+    readonly logger: Logger;
+    /** Register a health check with the endpoint's lifecycle manager. */
+    readonly addCheck: (check: HealthCheck) => void;
+    /**
+     * Endpoint-level port hint, when the host declared one
+     * (`endpoint("name", { port })`). HTTP-class adopters fall back to it
+     * when no transport-level port was passed to the adopter factory.
+     */
+    readonly port?: number;
+    /** Endpoint-level host hint, paired with `port`. */
+    readonly host?: string;
+}
+/**
+ * Structural shape every transport adopter satisfies. Adopters never
+ * extend a base class — the contract is duck-typed at the endpoint.
+ */
+export interface Adapter {
+    readonly $kind: "adapter";
+    /** Adopter-kind tag — matches `binding.$adapter` on the wires it consumes. */
+    readonly kind: string;
+    boot(opts: AdapterBootContext): Promise<void>;
+    shutdown(reason?: string): Promise<void>;
+    /**
+     * Optional — port the adopter's listener bound to, once `boot()` ran.
+     * HTTP-class adopters surface this so the endpoint banner can report
+     * the real port (ephemeral binds with `port: 0` only become visible
+     * after `listen()` resolves). Returns undefined for non-listening
+     * adopters or before boot.
+     */
+    port?(): number | undefined;
+}
+/** Type narrow — is this an Adapter? */
+export declare function isAdapter(x: unknown): x is Adapter;

package/dist/adapter.js

@@ -0,0 +1,20 @@
+/**
+ * `Adapter` contract — what every transport runtime (`@nwire/koa`,
+ * `@nwire/bullmq`, `@nwire/mcp`, `@nwire/cron`, …) implements.
+ *
+ * The endpoint hands each adopter its slice of wires + a `containerOf`
+ * resolver that maps each wire back to its source app's container.
+ * Adopter ownership is bounded: filter wires by `kind`, build the
+ * transport runtime, start serving, drain on shutdown.
+ *
+ * `endpoint("api").use(adopter).mount(source).run()` is the nwire path.
+ */
+/** Type narrow — is this an Adapter? */
+export function isAdapter(x) {
+    return (typeof x === "object" &&
+        x !== null &&
+        x.$kind === "adapter" &&
+        typeof x.kind === "string" &&
+        typeof x.boot === "function" &&
+        typeof x.shutdown === "function");
+}

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, isNwireServable, type AppServable, type EndpointConfig, type ForeignServable, type HostBindings, type HostFactory, type NwireServable, type RunningEndpoint, type Servable, } from "./endpoint.js";
+export { endpoint, EndpointBuilder, isAppServable, isForeignServable, type AppServable, type EndpointConfig, type ForeignServable, type RunningEndpoint, type Servable, } from "./endpoint.js";
 export { attachLifecycle, defineCheck, type HealthCheck, type HealthConfig, type LifecycleManager, type ShutdownConfig, } from "./lifecycle.js";
-//# sourceMappingURL=endpoint-index.d.ts.map
+export { isAdapter, type Adapter, type AdapterBootContext } from "./adapter.js";

package/dist/endpoint-index.js

@@ -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, isNwireServable, } from "./endpoint.js";
+export { endpoint, EndpointBuilder, isAppServable, isForeignServable, } from "./endpoint.js";
 export { attachLifecycle, defineCheck, } from "./lifecycle.js";
-//# sourceMappingURL=endpoint-index.js.map
+export { isAdapter } from "./adapter.js";

package/dist/endpoint.d.ts

@@ -34,10 +34,11 @@
  * write the same K8s-readiness code on every project. It works alone —
  * install only this package and wrap any Node server.
  */
-import type { Server } from "node:http";
+import { type Server } from "node:http";
 import type { Container } from "@nwire/container";
-import type { AttachBindings, NwireInterface } from "@nwire/interface";
-import { type HealthConfig, type HealthCheck, type LifecycleManager, type ShutdownConfig } from "./lifecycle.js";
+import type { Interface } from "@nwire/wires";
+import { type HealthConfig, type LifecycleManager, type ShutdownConfig } from "./lifecycle.js";
+import { type Adapter } from "./adapter.js";
 /**
  * Per-endpoint lifecycle hook context. The same shape flows through all
  * three phases (boot / serve / shutdown) so observers can correlate.
@@ -56,33 +57,18 @@ export interface EndpointHookCtx {
     readonly startedAt: string;
 }
 /**
- * Anything that can be served by an endpoint. Three categories:
+ * Anything that can be served by an endpoint. Two categories:
  *
- *   1. **NwireServable** — a Nwire interface (http/queue/etc) that knows how
- *      to produce a request handler and report what transport it needs.
- *   2. **ForeignServable** — an existing framework app (Express / Fastify /
+ *   1. **ForeignServable** — an existing framework app (Express / Fastify /
  *      Koa / Nest / etc) that the endpoint will wrap.
- *   3. **AppServable** — a Container-with-lifecycle that gets booted first
- *      so transports can use its bindings.
+ *   2. **AppServable** — a Container-with-lifecycle that gets booted first
+ *      so transports can use its bindings. Wires are dispatched via
+ *      `.use(adopter).mount(app)` separately from `.serve()`.
  *
  * Detection is structural: the endpoint inspects the shape at runtime to
- * decide how to serve it. No magic — see {@link isNwireServable},
- * {@link isAppServable}, {@link isForeignServable}.
+ * decide how to serve it. See {@link isAppServable}, {@link isForeignServable}.
  */
-export type Servable = NwireServable | ForeignServable | AppServable;
-/**
- * A Nwire interface compiled for the endpoint. The interface exposes how
- * it wants to be mounted: which transport, what handler shape, what
- * health checks it contributes.
- */
-export interface NwireServable extends NwireInterface {
-    /** Which transport this interface uses. Decides what listener spins up. */
-    readonly transport: "http" | "graphql" | "queue" | "cron" | "ws" | "mcp" | "custom";
-    /** Optional health checks contributed by the interface itself. */
-    readonly checks?: readonly HealthCheck[];
-    /** Run during shutdown — disconnect from broker, flush, etc. */
-    shutdown?(): void | Promise<void>;
-}
+export type Servable = ForeignServable | AppServable;
 /**
  * A foreign framework app — typically `express()`, `Fastify()`, `Koa()`,
  * or `NestFactory.create(AppModule)`. The endpoint will use the framework's
@@ -113,21 +99,12 @@ export interface AppServable {
     readonly appName?: string;
     /**
      * Optional — dispatch a framework lifecycle event on the app's bus.
-     * The endpoint uses this to fire `nwire.wire.mounting` /
-     * `nwire.wire.mounted` / `nwire.wire.unmounted` / `nwire.app.ready`
-     * at the right points in the serve loop.
-     *
-     * The dispatcher is duck-typed by event NAME so endpoint stays
-     * independent of `@nwire/app`. Apps that don't expose this method
-     * still serve correctly — endpoint just skips dispatch silently.
-     *
-     * Returns `false` when a series-bail subscriber prevented; `true`
-     * otherwise. Endpoint honors `false` only for the `*-ing` events.
+     * The endpoint uses this to fire `nwire.app.ready` once readiness
+     * flips. Duck-typed by event name so endpoint stays independent of
+     * `@nwire/app`; apps without the method still serve correctly.
      */
     dispatchFrameworkEvent?(eventName: string, payload: unknown): Promise<boolean>;
 }
-/** What the endpoint hands to each NwireServable.attach() call. */
-export type HostBindings = AttachBindings;
 export interface EndpointConfig {
     /** Port for HTTP-class transports. Omit for queue-only / cron-only endpoints. */
     readonly port?: number;
@@ -170,13 +147,21 @@ export interface RunningEndpoint {
  * ```
  */
 export declare function endpoint(name: string, config?: EndpointConfig): EndpointBuilder;
+/**
+ * Type narrow — does this source carry a wire collection (an App or a
+ * standalone Interface)? Endpoint accepts both shapes via `.mount()`.
+ */
+type WireSource = (AppServable & {
+    readonly interface: Interface;
+}) | Interface;
 /** Internal builder; users get one via {@link endpoint}. */
 export declare class EndpointBuilder {
     private readonly name;
     private readonly config;
     private apps;
-    private nwireServables;
     private foreignServables;
+    private adapters;
+    private mounted;
     /**
      * Per-phase lifecycle hooks. Created lazily at builder-construction so
      * they appear in `listHooks()` (and `.nwire/hooks.json` after scan)
@@ -192,11 +177,25 @@ export declare class EndpointBuilder {
     private readonly shutdownHook;
     constructor(name: string, config: EndpointConfig);
     /**
-     * Add something to serve. Multiple calls compose. Apps are booted first
-     * (any order between them is OK — boot order matters within an app, not
-     * across them), then Nwire interfaces and foreign apps are attached.
+     * Add something to serve. Multiple calls compose — an App boots its
+     * container/plugins; a framework app (Express/Fastify/Nest) attaches
+     * as a foreign listener so its routing system runs side by side. For
+     * Nwire wire-collections, use `.use(adopter).mount(app)`.
      */
     serve(target: Servable): EndpointBuilder;
+    /**
+     * Install a transport adopter — an `Adapter` value produced by an
+     * adopter package (`httpKoa()`, `queueBullmq()`, `mcp()`, …). Multiple
+     * `.use()` calls compose; the endpoint hands each adopter its slice of
+     * wires from the mounted source at `.run()` time.
+     */
+    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.
+     */
+    mount(source: WireSource): EndpointBuilder;
     /**
      * Boot all served apps in order, then attach all served interfaces +
      * foreign apps, then start listening. Returns a {@link RunningEndpoint}
@@ -209,8 +208,6 @@ export declare class EndpointBuilder {
      */
     run(): Promise<RunningEndpoint>;
 }
-/** True when the target is a Nwire interface (http/queue/etc) compiled for endpoint mount. */
-export declare function isNwireServable(x: unknown): x is NwireServable;
 /** True when the target is a Nwire app (container + lifecycle). */
 export declare function isAppServable(x: unknown): x is AppServable;
 /**
@@ -218,18 +215,7 @@ export declare function isAppServable(x: unknown): x is AppServable;
  *
  * Some hosts (Express, Connect) return a callable function as their app
  * value; others return an object (Fastify, Koa). We accept both — a
- * function with a `.listen` method counts. NwireServables are excluded
- * by the `$nwireServable` check at the call site.
+ * function with a `.listen` method counts.
  */
 export declare function isForeignServable(x: unknown): x is ForeignServable;
-/**
- * Per-transport host factory shape (provided by interface packages like
- * `@nwire/http`). The endpoint stays transport-agnostic by holding a
- * reference to this through `_buildHost` and asking the transport to
- * produce a Server when needed.
- */
-export interface HostFactory {
-    addCheck(check: HealthCheck): void;
-    listen(port: number, host: string): Promise<Server>;
-}
-//# sourceMappingURL=endpoint.d.ts.map
+export {};