@mauroandre/velojs 0.0.52 → 0.0.53

package/README.md

@@ -1320,7 +1320,7 @@ Hooks (`useParams`, `useQuery`, `usePathname`, `Loader`, `useLoader`) access thi
 
 ## Testing
 
-VeloJS ships a backend testing toolkit at `@mauroandre/velojs/testing`. Spin up the app in memory, fire HTTP requests against the registered handlers, subscribe to event streams. No socket, no browser, no fragile mocks of framework internals.
+VeloJS ships a backend testing toolkit at `@mauroandre/velojs/testing`. Spin up the app in memory, fire HTTP requests against the registered handlers, subscribe to event streams. No browser, no fragile mocks of framework internals — and a real TCP port when an external actor has to reach the app.
 
 ```typescript
 import { createTestApp } from "@mauroandre/velojs/testing";
@@ -1332,6 +1332,7 @@ const app = await createTestApp({
     routes,
     bootstrap: async () => { await connect(process.env.MONGO_URI!); },
     getSessionCookie: async ({ user }) => ({ session: await sign(user) }),
+    // port: 0,   // optional — also serve this app over real TCP (see below)
 });
 
 // HTTP
@@ -1358,6 +1359,7 @@ await app.close();
 | API | Purpose |
 |-----|---------|
 | `createTestApp(options)` | Build isolated app with bootstrap + auth callback |
+| `app.port` / `app.url` | Real port and base URL of the TCP listener — `undefined` in the default in-memory mode |
 | `app.get/post/put/patch/delete` | HTTP requests (cookies, headers, query, JSON/FormData body) |
 | `app.action(fn, opts)` | Invoke `action_*` by function reference |
 | `app.loader(fn, opts)` | Invoke `loader` and unwrap response data |
@@ -1368,6 +1370,26 @@ await app.close();
 | `app.reset()` | Clear stream buffers/listeners between tests |
 | `app.close()` | Tear down everything (zero open handles guaranteed) |
 
+### External actors over TCP
+
+In-memory requests never leave the process, so an actor that does — a worker in another VM POSTing a notify callback — needs a real socket. Pass `port` and the **same app instance** is served over TCP as well:
+
+```typescript
+const app = await createTestApp({ routes, port: 0 });   // 0 → free port
+
+// Hand the URL to the external client (worker, container, another test process)
+await provisioning.startWorker({ notifyUrl: `${app.url}/_action/Jobs/notify` });
+
+// The worker POSTs over real HTTP; the in-memory subscription sees the event —
+// same app, same stream registry, no glue and no second instance
+const sub = await app.subscribe(stream_progress, { channel: jobId });
+const event = await sub.next({ timeoutMs: 5000 });
+
+await app.close();   // closes the listener, dropping in-flight SSE/WebSocket connections
+```
+
+Pages, endpoints, actions, `?_data=1` loaders, SSE and WebSocket all answer as in production; `app.close()` also terminates connections still open on the listener. `port` and `hostname` come from the options only — never from `process.env.PORT`/`HOST` (test determinism). Omitted `hostname` follows Node's default bind (all interfaces — the listener is reachable from the local network); `app.url` reports `http://localhost:<port>` unless an explicit hostname was given.
+
 See [Testing docs](https://github.com/mauro-andre/velojs/blob/dev/site/docs/17-testing.md) for the full guide with patterns, isolation, and FAQ.
 
 ---

package/agent/skills/velojs-testing/SKILL.md

@@ -1,11 +1,11 @@
 ---
 name: velojs-testing
-description: "Writing tests with `createTestApp` from `@mauroandre/velojs/testing`: HTTP requests, actions, loaders, auth, SSE subscriptions, sockets. Use when writing or fixing a test for a VeloJS app."
+description: "Writing tests with `createTestApp` from `@mauroandre/velojs/testing`: HTTP requests, actions, loaders, auth, SSE subscriptions, sockets, and serving the app on a real TCP port for external actors. Use when writing or fixing a test for a VeloJS app."
 ---
 
 # Testing
 
-VeloJS ships a backend testing toolkit at `@mauroandre/velojs/testing`. It spins up your app in memory, fires HTTP requests against the registered handlers, subscribes to event streams, and asserts on the result. No socket. No browser. No fragile mocks of the framework internals.
+VeloJS ships a backend testing toolkit at `@mauroandre/velojs/testing`. It spins up your app in memory, fires HTTP requests against the registered handlers, subscribes to event streams, and asserts on the result. No browser. No fragile mocks of the framework internals. And when an actor outside this process has to reach the app — a worker sending a notify callback — the same app instance is served over a real TCP port.
 
 You test the whole stack — middleware, auth, routing, conventions, serialization — through the API your real users hit.
 
@@ -77,6 +77,7 @@ const app = await createTestApp({
     routes,
     bootstrap?: async () => { ... },
     getSessionCookie?: async ({ user }) => ({ ... }),
+    port?: 0,
 });
 ```
 
@@ -85,10 +86,12 @@ const app = await createTestApp({
 | `routes` | Required. Your app's `routes` array — typically `import routes from "./app/routes.js"` (it is the **default** export of `routes.tsx`) |
 | `bootstrap` | Runs once before the app is created. Use for DB connections, index creation, anything `app/server.tsx` does at startup. `addRoutes()` and `onServer()` calls here are **scoped to this app only** |
 | `getSessionCookie` | Maps a user object to cookies the test client will attach. Required for `app.as(user)` and `app.sessionCookies(user)` |
+| `port` | Optional. Serves the same app over real TCP on this port (`0` → free port, see [External actors over TCP](#external-actors-over-tcp)) |
+| `hostname` | Interface to bind when `port` is set (e.g. `"127.0.0.1"`). Omitted → Node's default, all interfaces |
 
 ### app.close()
 
-Tears down everything: heartbeats, retention timers, listeners, callbacks. After `close()`, Vitest must report **zero open handles**. Always call it in `afterAll`.
+Tears down everything: heartbeats, retention timers, listeners, callbacks — and the TCP listener when `port` was passed, terminating the SSE/WebSocket connections still open on it. After `close()`, Vitest must report **zero open handles**. Always call it in `afterAll`.
 
 ### app.reset()
 
@@ -159,6 +162,34 @@ await app.get("/api/posts", { query: { tag: ["preact", "ssr"] } });
 // → /api/posts?tag=preact&tag=ssr
 ```
 
+## External actors over TCP
+
+The in-memory client never leaves the process. When the actor under test *does* — a worker in another VM POSTing a notify callback to the control-plane — pass `port` and the **same instance** is served over real TCP:
+
+```typescript
+const app = await createTestApp({ routes, port: 0 });   // 0 → free port
+
+// `app.url` / `app.port` are the real, usable address — hand it to the worker
+await provisioning.startWorker({ notifyUrl: `${app.url}/_action/Jobs/notify` });
+
+// The worker POSTs over real HTTP. It's the same instance behind app.get and
+// app.subscribe, so a stream watched in-memory sees the event — no glue and no
+// "test watches an empty stream because it hit another instance":
+const sub = await app.subscribe(stream_progress, { channel: jobId });
+const event = await sub.next({ timeoutMs: 5000 });
+
+await app.close();   // listener down; in-flight SSE/WS connections dropped
+```
+
+Everything answers as in production — pages, endpoints, `action_*`, `?_data=1` loaders, SSE (`stream_*`) and WebSocket (`socket_*`). `app.close()` refuses new connections and terminates the ones still open, so a suite that keeps the app alive across tests tears down promptly even with a worker mid-SSE.
+
+Two rules keep tests deterministic:
+
+- **Ports come from the options only.** `port` and `hostname` are never read from `process.env.PORT`/`HOST`.
+- **The bind follows the option.** An explicit `hostname` (e.g. `"127.0.0.1"`) keeps the listener loopback; omitted, Node's default applies — all interfaces, reachable from the local network. `app.url` reports `http://localhost:<port>` unless an explicit hostname was given.
+
+Without `port`, nothing changes: the app is purely in-memory, and `app.port`/`app.url` are `undefined`.
+
 ## Auth — getSessionCookie and .as
 
 Most authenticated tests look like:
@@ -293,7 +324,7 @@ it("perChannelSource aborts when the last subscriber leaves", async () => {
 
 ## Sockets — `.socket(handler)`
 
-`app.socket(handlerOrStubOrPath, opts)` opens an **in-memory** WebSocket session against a `socket_*` handler — no real TCP, no upgrade handshake. The handler runs directly with a mock Context.
+`app.socket(handlerOrStubOrPath, opts)` opens an **in-memory** WebSocket session against a `socket_*` handler — no real TCP, no upgrade handshake. The handler runs directly with a mock Context. (For a real handshake, create the app with `port` and connect a client to `ws://...` — see [External actors over TCP](#external-actors-over-tcp).)
 
 ```typescript
 import { socket_terminal } from "../app/workers/WorkerTerminal.js";

package/dist/server.d.ts

@@ -4,6 +4,21 @@ import { AsyncLocalStorage } from "node:async_hooks";
 export declare const serverDataStorage: AsyncLocalStorage<Record<string, unknown>>;
 type ServerCallback = (server: import("http").Server) => void;
 export declare function onServer(fn: ServerCallback): void;
+/**
+ * Points the global `activeServer` at `server` and drains the callbacks
+ * registered in the current context. Exported for the testing toolkit, which
+ * serves a TestApp over TCP and must hand the real server to `onServer()`
+ * callbacks (same flush as `startServer`).
+ */
+export declare function flushServerCallbacks(server: import("http").Server): void;
+/**
+ * Drops the global `activeServer` when it still points at `server`. A closed
+ * server must stop answering `onServer()`: a late registrant would receive a
+ * dead instance (address() === null) instead of queueing for the next one.
+ * `startServer` does the same through `server.once("close", …)`; the testing
+ * toolkit has no such event to lean on because it closes the server itself.
+ */
+export declare function clearActiveServer(server: import("http").Server): void;
 export interface StartServerOptions {
     routes: AppRoutes;
     port?: number;

package/dist/server.js

@@ -1,17 +1,17 @@
-import { jsx as v } from "preact/jsx-runtime";
+import { jsx as w } from "preact/jsx-runtime";
 import { Hono as R } from "hono";
 import { logger as T } from "hono/logger";
 import { trimTrailingSlash as E } from "hono/trailing-slash";
 import { render as C } from "preact-render-to-string";
-import { Router as $ } from "wouter-preact";
-import { AsyncLocalStorage as k } from "node:async_hooks";
+import { Router as A } from "wouter-preact";
+import { AsyncLocalStorage as $ } from "node:async_hooks";
 import { getAppContext as _ } from "./app-context.js";
-import { flushPendingStreamRoutes as A, registerStreamHandler as D } from "./events.js";
+import { flushPendingStreamRoutes as k, registerStreamHandler as D } from "./events.js";
 import { registerSocketRoutes as O, injectWebSocketServer as S } from "./sockets.js";
-const P = new k();
+const P = new $();
 globalThis.__veloServerData = P;
 let g = null;
-function Z(e) {
+function ee(e) {
   if (g) {
     e(g);
     return;
@@ -24,23 +24,26 @@ function b(e) {
   for (const s of t.serverCallbacks) s(e);
   t.serverCallbacks.length = 0;
 }
-function ee(e) {
+function I(e) {
+  g === e && (g = null);
+}
+function te(e) {
   _().pendingRoutes.push(e);
 }
-const I = (e) => JSON.stringify(e).replace(/</g, "\\u003c").replace(/>/g, "\\u003e").replace(/\u2028/g, "\\u2028").replace(/\u2029/g, "\\u2029"), N = (e, t, s, a) => {
+const N = (e) => JSON.stringify(e).replace(/</g, "\\u003c").replace(/>/g, "\\u003e").replace(/\u2028/g, "\\u2028").replace(/\u2029/g, "\\u2029"), H = (e, t, s, a) => {
   if (a && a !== 200 && e.status(a), e.req.query("_data") === "1") {
     const c = globalThis.__veloBuildHash || void 0, r = s ? { ...s, __buildHash: c } : { __buildHash: c };
     return e.json(r);
   }
   const o = e.req.path, n = P.run(
     s ?? {},
-    () => C(/* @__PURE__ */ v($, { ssrPath: o, children: t }))
+    () => C(/* @__PURE__ */ w(A, { ssrPath: o, children: t }))
   );
   if (e.header("Cache-Control", "no-cache"), !s)
     return e.html(n);
-  const i = `<script>window.__PAGE_DATA__=${I(s)}<\/script>`;
+  const i = `<script>window.__PAGE_DATA__=${N(s)}<\/script>`;
   return e.html(n.replace("</head>", () => `${i}</head>`));
-}, H = async (e, t) => {
+}, G = async (e, t) => {
   const s = t.req.param(), a = t.req.query(), o = { params: s, query: a, c: t }, n = await Promise.all(
     e.map(async (r) => {
       if (!r.loader) return null;
@@ -66,16 +69,16 @@ const I = (e) => JSON.stringify(e).replace(/</g, "\\u003c").replace(/>/g, "\\u00
     data: c,
     shortCircuit: i
   };
-}, G = (e) => {
+}, x = (e) => {
   if (e.length === 0) return null;
   const t = e.filter(Boolean);
   if (t.length === 0) return null;
   if (t.length === 1) {
     const o = t[0];
-    return /* @__PURE__ */ v(o, {});
+    return /* @__PURE__ */ w(o, {});
   }
   const s = t[t.length - 1];
-  return t.slice(0, -1).reduceRight((o, n) => /* @__PURE__ */ v(n, { children: o }), /* @__PURE__ */ v(s, {}));
+  return t.slice(0, -1).reduceRight((o, n) => /* @__PURE__ */ w(n, { children: o }), /* @__PURE__ */ w(s, {}));
 }, y = (e, t, s = [], a = []) => {
   for (const o of t) {
     if (o.handler && !o.module) {
@@ -107,13 +110,13 @@ const I = (e) => JSON.stringify(e).replace(/</g, "\\u003c").replace(/>/g, "\\u00
         continue;
       }
       const l = async (d) => {
-        const { components: u, data: h, shortCircuit: m } = await H(n, d);
+        const { components: u, data: h, shortCircuit: m } = await G(n, d);
         if (m) {
-          const w = m.headers.get("Location");
-          return d.req.query("_data") === "1" && w && m.status >= 300 && m.status < 400 ? d.json({ __redirect: w }) : m;
+          const v = m.headers.get("Location");
+          return d.req.query("_data") === "1" && v && m.status >= 300 && m.status < 400 ? d.json({ __redirect: v }) : m;
         }
-        const p = G(u);
-        return N(d, p, h, r);
+        const p = x(u);
+        return H(d, p, h, r);
       };
       c ? e.notFound(l) : i.length > 0 ? e.on(["GET"], [f], ...i, l) : e.on(["GET"], [f], l);
     } else
@@ -148,8 +151,8 @@ const I = (e) => JSON.stringify(e).replace(/</g, "\\u003c").replace(/>/g, "\\u00
               const p = await f(m);
               return u.json(p ?? { ok: !0 });
             } catch (p) {
-              const w = p instanceof Error ? p.message : "Action failed";
-              return u.json({ error: w }, 500);
+              const v = p instanceof Error ? p.message : "Action failed";
+              return u.json({ error: v }, 500);
             }
           };
           n.length > 0 ? e.on(
@@ -163,7 +166,7 @@ const I = (e) => JSON.stringify(e).replace(/</g, "\\u003c").replace(/>/g, "\\u00
     }
     a.children && q(e, a.children, n);
   }
-}, x = async (e, t, s = []) => {
+}, V = async (e, t, s = []) => {
   const a = (o, n) => {
     for (const i of o) {
       const c = i.module?.metadata?.moduleId, r = [
@@ -191,7 +194,7 @@ const I = (e) => JSON.stringify(e).replace(/</g, "\\u003c").replace(/>/g, "\\u00
     }
   };
   a(t, s);
-}, V = (e, t) => t ? t.startsWith("/") ? e + t : e ? e + "/" + t : "/" + t : e || "", W = (e) => {
+}, W = (e, t) => t ? t.startsWith("/") ? e + t : e ? e + "/" + t : "/" + t : e || "", K = (e) => {
   const t = /* @__PURE__ */ new Set(), s = (a) => {
     for (const o of a) {
       if (o.module && !o.children) {
@@ -204,7 +207,7 @@ const I = (e) => JSON.stringify(e).replace(/</g, "\\u003c").replace(/>/g, "\\u00
   return s(e), t;
 }, j = (e, t, s, a = "", o = []) => {
   for (const n of t) {
-    const i = V(a, n.path), c = [
+    const i = W(a, n.path), c = [
       ...o,
       ...n.middlewares || []
     ], r = !!n.handler, f = !!n.method;
@@ -236,21 +239,21 @@ const I = (e) => JSON.stringify(e).replace(/</g, "\\u003c").replace(/>/g, "\\u00
       c
     );
   }
-}, K = async (e) => {
+}, L = async (e) => {
   const t = new R();
   t.use(E()), process.env.NODE_ENV !== "production" && t.use("*", T());
   const a = _().pendingRoutes.splice(0);
   for (const n of a)
     await n(t);
-  y(t, e), q(t, e), await x(t, e);
-  const o = W(e);
-  if (j(t, e, o), await O(t, e), A(t), process.env.NODE_ENV !== "production" && !g) {
+  y(t, e), q(t, e), await V(t, e);
+  const o = K(e);
+  if (j(t, e, o), await O(t, e), k(t), process.env.NODE_ENV !== "production" && !g) {
     const n = globalThis.__veloDevServer;
     n && (b(n), await S(t, n));
   }
   return t;
-}, te = async (e) => {
-  const { routes: t } = e, s = Number(process.env.PORT) || e.port || 3e3, a = process.env.HOST || e.hostname || void 0, o = await K(t);
+}, oe = async (e) => {
+  const { routes: t } = e, s = Number(process.env.PORT) || e.port || 3e3, a = process.env.HOST || e.hostname || void 0, o = await L(t);
   if (process.env.NODE_ENV === "production" && !process.env.VELO_STATIC) {
     const { serve: n } = await import("@hono/node-server"), { serveStatic: i } = await import("@hono/node-server/serve-static"), { join: c } = await import("node:path"), r = c(process.cwd(), "dist/client");
     (process.env.STATIC_BASE_URL || "").startsWith("http") || o.use("/*", i({ root: r }));
@@ -263,17 +266,19 @@ const I = (e) => JSON.stringify(e).replace(/</g, "\\u003c").replace(/>/g, "\\u00
     } else
       console.log(`Server running on port ${s}`);
     await S(o, l), b(l), l.once("close", () => {
-      g === l && (g = null);
+      I(l);
     });
   }
   return o;
 };
 export {
-  ee as addRoutes,
-  K as createApp,
-  K as default,
-  I as jsonForScript,
-  Z as onServer,
+  te as addRoutes,
+  I as clearActiveServer,
+  L as createApp,
+  L as default,
+  b as flushServerCallbacks,
+  N as jsonForScript,
+  ee as onServer,
   P as serverDataStorage,
-  te as startServer
+  oe as startServer
 };

package/dist/testing/createTestApp.d.ts

@@ -19,5 +19,13 @@ import type { TestApp, CreateTestAppOptions } from "./types.js";
  *     getSessionCookie: async ({ user }) => ({ session: await sign(user) }),
  * });
  * ```
+ *
+ * Pass `port` to also serve the same app over real TCP — for external actors
+ * (a worker in another process) that cannot call `hono.fetch` in-memory:
+ *
+ * ```typescript
+ * const app = await createTestApp({ routes, port: 0 });
+ * await handToWorker(`${app.url}/_action/Jobs/notify`);
+ * ```
  */
 export declare function createTestApp(opts: CreateTestAppOptions): Promise<TestApp>;