@nwire/koa 0.12.0 → 0.13.0

package/dist/http-koa.js

@@ -35,6 +35,24 @@ import bodyParser from "koa-bodyparser";
 import cors from "@koa/cors";
 import helmet from "koa-helmet";
 import KoaRouter from "@koa/router";
+/** Zod throws a `ZodError` (name + `issues[]`) on a failed `.parse()`. */
+function isZodError(e) {
+    return (typeof e === "object" &&
+        e !== null &&
+        e.name === "ZodError" &&
+        Array.isArray(e.issues));
+}
+/**
+ * A human-readable summary of the first validation issue. Safe to expose:
+ * it describes the caller's own input, not internal state.
+ */
+function zodSummary(e) {
+    const first = e.issues[0];
+    if (!first)
+        return "validation failed";
+    const path = (first.path ?? []).join(".") || "(body)";
+    return `${path}: ${first.message}`;
+}
 function isHttpBinding(b) {
     return (typeof b === "object" &&
         b !== null &&
@@ -45,6 +63,9 @@ function isHttpBinding(b) {
 export function httpKoa(config = {}) {
     let server;
     let koaInstance;
+    // Set during boot — answers "does the wire own this URL path?" for the
+    // one-Vite dev host. Undefined before boot.
+    let ownsPredicate;
     const logger = config.logger ?? new ConsoleLogger();
     return {
         $kind: "adapter",
@@ -58,6 +79,12 @@ export function httpKoa(config = {}) {
         koa() {
             return koaInstance;
         },
+        handler() {
+            return koaInstance?.callback();
+        },
+        owns(pathname) {
+            return ownsPredicate?.(pathname) ?? false;
+        },
         async boot(ctx) {
             const koa = new Koa();
             koaInstance = koa;
@@ -77,12 +104,32 @@ export function httpKoa(config = {}) {
                 catch (err) {
                     const e = err;
                     const isNwireError = e?.$kind === "error";
-                    kctx.status = typeof e.status === "number" ? e.status : 500;
+                    if (isZodError(err)) {
+                        // A schema `.parse()` that escaped the per-route catch (e.g. an
+                        // action's own input schema). Validation failures are the
+                        // caller's fault → 400 with a readable summary, never an opaque
+                        // 500. The message is about their input, so it's safe to expose.
+                        kctx.status = 400;
+                        kctx.body = { error: { code: "validation_failed", summary: zodSummary(err) } };
+                        return;
+                    }
+                    const status = typeof e.status === "number" ? e.status : 500;
+                    kctx.status = status;
                     if (isNwireError) {
                         kctx.body = {
                             error: { code: e.code ?? "internal_error", summary: e.summary ?? "Internal error" },
                         };
                     }
+                    else if (status >= 400 && status < 500) {
+                        // A client error raised by middleware before any handler ran —
+                        // most commonly the body parser rejecting malformed JSON. The
+                        // status is already the caller's fault, and the message describes
+                        // their own request, so surface it as a clean client error rather
+                        // than an opaque "internal_error".
+                        kctx.body = {
+                            error: { code: e.code ?? "bad_request", summary: e.message ?? "Bad request" },
+                        };
+                    }
                     else {
                         logger.error?.(`[http-koa] unhandled error: ${e?.message ?? e}`, undefined);
                         kctx.body = {
@@ -249,7 +296,7 @@ export function httpKoa(config = {}) {
                         kctx.body = {
                             error: {
                                 code: "validation_failed",
-                                summary: err.message,
+                                summary: isZodError(err) ? zodSummary(err) : err.message,
                             },
                         };
                         return;
@@ -274,7 +321,12 @@ export function httpKoa(config = {}) {
                             : (kc.request.headers["x-tenant"] ?? undefined));
                     const envelopePartial = {
                         tenant: resolveTenant(kctx),
-                        userId: kctx.state.userId ?? undefined,
+                        // Prefer an explicit `state.userId`, but fall back to the
+                        // user object's id so handlers reading `envelope.userId` work
+                        // whenever auth middleware populated `state.user`.
+                        userId: kctx.state.userId ??
+                            kctx.state.user?.id ??
+                            undefined,
                         // Pass the full user object through when adopter auth middleware
                         // populated it. Without this, transport-agnostic RBAC has to
                         // reach into `ctx.koa.state.user` and couples the handler to
@@ -285,17 +337,25 @@ export function httpKoa(config = {}) {
                     };
                     // eslint-disable-next-line @typescript-eslint/no-explicit-any
                     const wireApp = wire.app;
-                    // eslint-disable-next-line @typescript-eslint/no-explicit-any
-                    const runtimeExecute = wireApp?.runtime?.execute;
+                    const runtime = wireApp?.runtime;
                     let result;
                     try {
-                        if (runtimeExecute) {
-                            // Unified dispatch — runtime.execute builds the canonical
-                            // ctx (input + envelope + execute + emit + enqueue + resolve
-                            // + scope) for both HandlerDefinition and plain `(input, ctx)`
-                            // function shapes, threads transport extras (logger, koa)
-                            // onto the same ctx, and runs the hook chain when present.
-                            result = await runtimeExecute.call(wireApp.runtime, wire.handler, input, envelopePartial, { logger: handlerCtx.logger, koa: handlerCtx.koa });
+                        if (runtime?.receive) {
+                            // Unified inbound — the HTTP request becomes a command on the
+                            // runtime's source chain. The terminal router lands it on
+                            // runtime.execute, which builds the canonical ctx (input +
+                            // envelope + execute + emit + enqueue + resolve + scope) for
+                            // both action/handler and plain `(input, ctx)` shapes and
+                            // threads transport extras (logger, koa) onto that ctx.
+                            result = await runtime.receive({
+                                kind: "command",
+                                name: wire.handler?.name ?? "handler",
+                                input,
+                                target: wire.handler,
+                            }, {
+                                envelope: envelopePartial,
+                                extras: { logger: handlerCtx.logger, koa: handlerCtx.koa },
+                            });
                         }
                         else {
                             // No-runtime fallback — standalone interface without an App.
@@ -395,6 +455,43 @@ export function httpKoa(config = {}) {
                 }
             }
             koa.use(router.routes()).use(router.allowedMethods());
+            // Ownership predicate for the one-Vite dev host. The wire owns its route
+            // prefix subtree (so `/api/*` always reaches koa — and 404s/401s there,
+            // not in Studio) plus the well-known surfaces it mounts outside the
+            // router: `/openapi.json`, `/docs`, and the `/_nwire/*` inspect tree.
+            // Everything else (`/`, Studio assets + deep links) is not ours, so the
+            // host serves Studio. When no prefix is configured the wire's routes sit
+            // at the root, so we fall back to a method-agnostic route match to avoid
+            // claiming `/`.
+            const owned = new Set();
+            if (config.openapi?.spec || config.openapi?.generator || config.openapi?.auto) {
+                owned.add(openapiPath);
+            }
+            if (docsConfig !== null)
+                owned.add(docsPath);
+            const inspectPrefix = inspectEnabled
+                ? ((typeof inspectEnabled === "object" ? inspectEnabled.prefix : undefined) ?? "/_nwire")
+                : undefined;
+            const routePrefix = config.prefix;
+            ownsPredicate = (pathname) => {
+                if (owned.has(pathname))
+                    return true;
+                if (inspectPrefix &&
+                    (pathname === inspectPrefix || pathname.startsWith(inspectPrefix + "/"))) {
+                    return true;
+                }
+                if (routePrefix) {
+                    return pathname === routePrefix || pathname.startsWith(routePrefix + "/");
+                }
+                // No prefix — match real route paths so `/` and unknown paths fall
+                // through to Studio. `.match` is method-agnostic via the `path` layers.
+                try {
+                    return router.match(pathname, "GET").path.length > 0;
+                }
+                catch {
+                    return false;
+                }
+            };
             // Listen if a port is available: adopter-level config.port wins,
             // otherwise fall back to the endpoint-level port hint from boot ctx.
             const listenPort = config.port ?? ctx.port;
@@ -412,6 +509,11 @@ export function httpKoa(config = {}) {
         },
         async shutdown() {
             if (server) {
+                // `close()` stops listening but waits on in-flight connections;
+                // idle HTTP keep-alive sockets would otherwise hold the server (and
+                // a test runner's worker) open indefinitely. Drop them so shutdown
+                // is prompt and the listening handle is actually released.
+                server.closeAllConnections?.();
                 await new Promise((resolve) => server.close(() => {
                     resolve();
                 }));

package/dist/inspect.d.ts

@@ -2,17 +2,24 @@
  * `/_nwire/*` — read + dispatch surface Studio (and MCP tooling) reads
  * to render the live state of a running app.
  *
- *   GET  /_nwire/manifest    — app name + adopter info + wire summary
- *   GET  /_nwire/wires       — every wire's binding kind + key fields
- *   GET  /_nwire/runtime     — telemetry tap + framework-event log shape
- *   GET  /_nwire/actors/:t   — actor instances of type `t` from the store
- *   POST /_nwire/dispatch    — invoke a registered handler by name
+ *   GET  /_nwire/manifest      — app name + adopter info + wire summary
+ *   GET  /_nwire/wires         — every wire's binding kind + key fields
+ *   GET  /_nwire/runtime       — framework-event log shape + lifecycle
+ *   GET  /_nwire/events/recent — recent wire events from the ring buffer
+ *   GET  /_nwire/events/stream — SSE stream of live wire events
+ *   GET  /_nwire/actors/:t     — actor instances of type `t` from the store
+ *   POST /_nwire/dispatch      — invoke a registered handler by name
  *
  * `inspect: true` (or `inspect: { ... }`) on `httpKoa({ ... })` mounts
  * these before per-route middleware so they don't sit behind auth gates.
  *
  * Production deployments should add an admin guard via
  * `inspect: { middleware: [requireAdmin] }`.
+ *
+ * Telemetry is now a sink — records flow to TelemetryReporter instances
+ * (file, OTLP, …) configured at the app level. The former
+ * `/_nwire/telemetry/recent` and `/_nwire/telemetry/stream` endpoints
+ * have been removed; use the reporter output directly.
  */
 import type Koa from "koa";
 import type { Wire } from "@nwire/wires";

package/dist/inspect.js

@@ -2,17 +2,24 @@
  * `/_nwire/*` — read + dispatch surface Studio (and MCP tooling) reads
  * to render the live state of a running app.
  *
- *   GET  /_nwire/manifest    — app name + adopter info + wire summary
- *   GET  /_nwire/wires       — every wire's binding kind + key fields
- *   GET  /_nwire/runtime     — telemetry tap + framework-event log shape
- *   GET  /_nwire/actors/:t   — actor instances of type `t` from the store
- *   POST /_nwire/dispatch    — invoke a registered handler by name
+ *   GET  /_nwire/manifest      — app name + adopter info + wire summary
+ *   GET  /_nwire/wires         — every wire's binding kind + key fields
+ *   GET  /_nwire/runtime       — framework-event log shape + lifecycle
+ *   GET  /_nwire/events/recent — recent wire events from the ring buffer
+ *   GET  /_nwire/events/stream — SSE stream of live wire events
+ *   GET  /_nwire/actors/:t     — actor instances of type `t` from the store
+ *   POST /_nwire/dispatch      — invoke a registered handler by name
  *
  * `inspect: true` (or `inspect: { ... }`) on `httpKoa({ ... })` mounts
  * these before per-route middleware so they don't sit behind auth gates.
  *
  * Production deployments should add an admin guard via
  * `inspect: { middleware: [requireAdmin] }`.
+ *
+ * Telemetry is now a sink — records flow to TelemetryReporter instances
+ * (file, OTLP, …) configured at the app level. The former
+ * `/_nwire/telemetry/recent` and `/_nwire/telemetry/stream` endpoints
+ * have been removed; use the reporter output directly.
  */
 function summarizeWire(wire) {
     const b = wire.binding;
@@ -65,29 +72,26 @@ class RingBuffer {
 }
 function attachStreams(opts) {
     const events = new RingBuffer(500);
-    const telemetry = new RingBuffer(500);
     const listeners = new Set();
     // eslint-disable-next-line @typescript-eslint/no-explicit-any
     const rt = opts.app?.runtime;
     if (typeof rt?.onTelemetry === "function") {
         rt.onTelemetry((rec) => {
-            telemetry.push(rec);
             if (rec.kind === "event.published" || rec.kind === "event.deduped") {
                 events.push(rec);
-            }
-            for (const fn of listeners) {
-                try {
-                    fn(rec);
-                }
-                catch {
-                    // Listener crashed; drop without taking the runtime with it.
+                for (const fn of listeners) {
+                    try {
+                        fn(rec);
+                    }
+                    catch {
+                        // Listener crashed; drop without taking the runtime with it.
+                    }
                 }
             }
         });
     }
     return {
         events,
-        telemetry,
         subscribe(fn) {
             listeners.add(fn);
             return () => listeners.delete(fn);
@@ -107,7 +111,7 @@ export function mountInspect(koa, opts) {
     const prefix = opts.config.prefix ?? "/_nwire";
     const chain = opts.config.middleware ?? [];
     const isProd = process.env.NODE_ENV === "production";
-    // Eagerly attach the telemetry tap on the App's runtime so we don't
+    // Eagerly attach the event tap on the App's runtime so we don't
     // miss records emitted before the first /_nwire/* request.
     streamsFor(opts);
     // Production guardrail: `/dispatch` is remote-handler invocation. If the
@@ -187,18 +191,16 @@ async function dispatchInspect(kctx, opts) {
         });
         return;
     }
-    if (kctx.method === "GET" && (sub === "/events/recent" || sub === "/telemetry/recent")) {
+    if (kctx.method === "GET" && sub === "/events/recent") {
         const streams = streamsFor(opts);
         const limit = Number(kctx.query.limit ?? "200") || 200;
-        const buf = sub === "/events/recent" ? streams.events : streams.telemetry;
-        const records = buf.recent(limit);
+        const records = streams.events.recent(limit);
         kctx.type = "application/json";
-        kctx.body = JSON.stringify(sub === "/events/recent" ? records.map((rec, i) => toBufferedEvent(rec, i)) : records);
+        kctx.body = JSON.stringify(records.map((rec, i) => toBufferedEvent(rec, i)));
         return;
     }
-    if (kctx.method === "GET" && (sub === "/events/stream" || sub === "/telemetry/stream")) {
+    if (kctx.method === "GET" && sub === "/events/stream") {
         const streams = streamsFor(opts);
-        const onlyEvents = sub === "/events/stream";
         kctx.respond = false;
         const res = kctx.res;
         res.statusCode = 200;
@@ -206,18 +208,14 @@ async function dispatchInspect(kctx, opts) {
         res.setHeader("Cache-Control", "no-cache, no-transform");
         res.setHeader("Connection", "keep-alive");
         // Backfill from the ring buffer.
-        const backfill = onlyEvents ? streams.events.recent(50) : streams.telemetry.recent(50);
+        const backfill = streams.events.recent(50);
         let seq = 0;
         for (const rec of backfill) {
-            const payload = onlyEvents ? toBufferedEvent(rec, seq++) : rec;
-            res.write(`data: ${JSON.stringify(payload)}\n\n`);
+            res.write(`data: ${JSON.stringify(toBufferedEvent(rec, seq++))}\n\n`);
         }
         const unsub = streams.subscribe((rec) => {
-            if (onlyEvents && rec.kind !== "event.published" && rec.kind !== "event.deduped")
-                return;
             try {
-                const payload = onlyEvents ? toBufferedEvent(rec, seq++) : rec;
-                res.write(`data: ${JSON.stringify(payload)}\n\n`);
+                res.write(`data: ${JSON.stringify(toBufferedEvent(rec, seq++))}\n\n`);
             }
             catch {
                 // socket gone
@@ -231,6 +229,8 @@ async function dispatchInspect(kctx, opts) {
                 // socket gone
             }
         }, 25_000);
+        // An idle SSE keepalive must never keep the process alive on its own.
+        keepalive.unref();
         kctx.req.on("close", () => {
             unsub();
             clearInterval(keepalive);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nwire/koa",
-  "version": "0.12.0",
+  "version": "0.13.0",
   "description": "Nwire — Koa-backed HTTP adopter. Consumes wires from @nwire/wires/http and serves them as Koa routes under endpoint lifecycle.",
   "keywords": [
     "adopter",
@@ -33,10 +33,10 @@
     "koa-bodyparser": "^4.4.1",
     "koa-helmet": "^8.0.1",
     "zod": "^4.0.0",
-    "@nwire/container": "0.12.0",
-    "@nwire/endpoint": "0.12.0",
-    "@nwire/logger": "0.12.0",
-    "@nwire/wires": "0.12.0"
+    "@nwire/endpoint": "0.13.0",
+    "@nwire/logger": "0.13.0",
+    "@nwire/container": "0.13.0",
+    "@nwire/wires": "0.13.0"
   },
   "devDependencies": {
     "@asteasolutions/zod-to-openapi": "^8.0.0",
@@ -47,8 +47,8 @@
     "@types/node": "^22.19.9",
     "typescript": "^5.9.3",
     "vitest": "^4.0.18",
-    "@nwire/app": "0.12.0",
-    "@nwire/handler": "0.12.0"
+    "@nwire/app": "0.13.0",
+    "@nwire/handler": "0.13.0"
   },
   "peerDependencies": {
     "@asteasolutions/zod-to-openapi": "^8.0.0"