keryx 0.21.7 → 0.22.0

package/classes/Action.ts

@@ -181,10 +181,12 @@ export abstract class Action {
    *   action's `inputs` Zod schema (falls back to `Record<string, unknown>` when no schema is
    *   defined). By the time `run` is called, all middleware `runBefore` hooks have already
    *   executed and may have mutated the params.
-   * @param connection - The connection that initiated this action. Provides access to the
-   *   caller's session (`connection.session`), subscription state, and raw transport handle.
-   *   It is `undefined` when the action is invoked outside an HTTP/WebSocket request context
-   *   (e.g., as a background task via the Resque worker or via `api.actions.run()`).
+   * @param connection - The connection that initiated this action. Always defined. Provides
+   *   access to the caller's session (`connection.session`), subscription state, and raw
+   *   transport handle. For background tasks (resque worker), `connection.type === "task"`
+   *   and `connection.session.data` is empty — tasks are fresh starts, so actions that
+   *   need user context should receive it as an input parameter rather than reading from
+   *   the session.
    * @param abortSignal - An `AbortSignal` tied to the action's timeout. The signal is aborted
    *   when the per-action `timeout` (or the global `config.actions.timeout`, default 300 000 ms)
    *   elapses. Long-running actions should check `abortSignal.aborted` or pass the signal to
@@ -194,7 +196,7 @@ export abstract class Action {
    */
   abstract run(
     params: ActionParams<Action>,
-    connection?: Connection,
+    connection: Connection,
     abortSignal?: AbortSignal,
   ): Promise<any>;
 }

package/classes/Router.ts

@@ -0,0 +1,157 @@
+import type { Action, HTTP_METHOD } from "./Action";
+
+/**
+ * Result of a successful route match.
+ */
+export type RouterMatch = {
+  actionName: string;
+  pathParams?: Record<string, string>;
+};
+
+type DynamicRoute = {
+  matcher: RegExp;
+  paramNames: string[];
+  actionName: string;
+};
+
+/**
+ * Fast path-to-action lookup.
+ *
+ * `compile()` builds two lookup structures from a list of actions:
+ *   - a static index keyed by method + exact path for plain-string routes with no `:param` segments
+ *   - a dynamic list (per method) of pre-compiled regexes for `:param` and `RegExp` routes
+ *
+ * `match()` performs an O(1) static lookup first, then falls back to an O(k) scan of
+ * dynamic routes for that method (where k is the number of dynamic routes per method).
+ *
+ * The router preserves the registration order of dynamic routes, so when two dynamic
+ * patterns can both match a path, the first one registered wins — matching the
+ * behavior of the pre-router iteration loop.
+ *
+ * The router reads the action list through a source function supplied to
+ * `compile()`. On each `match()` call it checks whether the returned array
+ * reference or length has changed since the last build, and rebuilds on drift.
+ * This preserves the live-iteration semantics of the previous loop-based matcher
+ * — including tolerating tests that both push new actions onto
+ * `api.actions.actions` and that swap the array wholesale via
+ * `api.actions.actions = api.actions.actions.filter(...)`.
+ */
+export class Router {
+  private staticIndex: Map<HTTP_METHOD, Map<string, string>> = new Map();
+  private dynamicList: Map<HTTP_METHOD, DynamicRoute[]> = new Map();
+  private source: () => Action[] = () => [];
+  private lastSeen: Action[] | null = null;
+  private lastLength = -1;
+
+  /**
+   * Bind the router to an action source and eagerly build the lookup structures.
+   *
+   * The `source` argument may be the action array directly, or a getter function
+   * that returns the current array. A getter is the recommended form for
+   * long-lived routers (e.g. the one on `api.actions`) because some callers
+   * swap the underlying array reference rather than mutating in place.
+   *
+   * Safe to call multiple times — each call fully replaces the previous state.
+   * When in-process hot-reload for actions is added, callers must re-invoke this
+   * method; the currently relied-on dev restart via `bun --watch` is a full
+   * process restart, so `initialize()` naturally re-runs this.
+   *
+   * @param source - Either the actions array or a function returning it. Actions without a `web.route` are skipped.
+   */
+  compile(source: Action[] | (() => Action[])): void {
+    this.source =
+      typeof source === "function" ? source : () => source as Action[];
+
+    // Eagerly build if the source is ready. If the getter throws (e.g. called
+    // inside `initialize()` before `api.actions` is assigned), defer to the
+    // first `match()` call.
+    try {
+      const actions = this.source();
+      this.rebuild(actions);
+    } catch {
+      this.lastSeen = null;
+      this.lastLength = -1;
+    }
+  }
+
+  private rebuild(actions: Action[]): void {
+    this.staticIndex = new Map();
+    this.dynamicList = new Map();
+
+    for (const action of actions) {
+      if (!action?.web?.route) continue;
+      const { route, method } = action.web;
+
+      const isRegExp = route instanceof RegExp;
+      const hasParams = !isRegExp && /:\w+/.test(route as string);
+
+      if (!isRegExp && !hasParams) {
+        let byPath = this.staticIndex.get(method);
+        if (!byPath) {
+          byPath = new Map();
+          this.staticIndex.set(method, byPath);
+        }
+        if (!byPath.has(route as string)) {
+          byPath.set(route as string, action.name);
+        }
+        continue;
+      }
+
+      const matcher = isRegExp
+        ? (route as RegExp)
+        : new RegExp(`^${(route as string).replace(/:\w+/g, "([^/]+)")}$`);
+      const paramNames = isRegExp
+        ? []
+        : ((route as string).match(/:\w+/g) ?? []).map((n) => n.slice(1));
+
+      let list = this.dynamicList.get(method);
+      if (!list) {
+        list = [];
+        this.dynamicList.set(method, list);
+      }
+      list.push({ matcher, paramNames, actionName: action.name });
+    }
+
+    this.lastSeen = actions;
+    this.lastLength = actions.length;
+  }
+
+  /**
+   * Match a path + method against the compiled routes.
+   *
+   * @param path - The request path (already stripped of any API prefix).
+   * @param method - Uppercase HTTP method.
+   * @returns The matched action name plus any extracted path parameters, or `null` if no route matched.
+   */
+  match(path: string, method: HTTP_METHOD): RouterMatch | null {
+    const actions = this.source();
+    if (actions !== this.lastSeen || actions.length !== this.lastLength) {
+      this.rebuild(actions);
+    }
+
+    const staticHit = this.staticIndex.get(method)?.get(path);
+    if (staticHit) return { actionName: staticHit };
+
+    const candidates = this.dynamicList.get(method);
+    if (!candidates) return null;
+
+    for (const { matcher, paramNames, actionName } of candidates) {
+      const result = matcher.exec(path);
+      if (!result) continue;
+
+      if (paramNames.length === 0) return { actionName };
+
+      const pathParams: Record<string, string> = {};
+      for (let i = 0; i < paramNames.length; i++) {
+        const value = result[i + 1];
+        if (value !== undefined) pathParams[paramNames[i]] = value;
+      }
+      return {
+        actionName,
+        pathParams: Object.keys(pathParams).length > 0 ? pathParams : undefined,
+      };
+    }
+
+    return null;
+  }
+}

package/initializers/actionts.ts

@@ -4,6 +4,7 @@ import path from "path";
 import { api, logger } from "../api";
 import { type Action, DEFAULT_QUEUE } from "../classes/Action";
 import { Initializer } from "../classes/Initializer";
+import { Router } from "../classes/Router";
 import { ErrorType, TypedError } from "../classes/TypedError";
 import { config } from "../config";
 import { formatLoadedMessage } from "../util/config";
@@ -672,8 +673,16 @@ export class Actions extends Initializer {
       }),
     );
 
+    // Keep the router compile co-located with action assembly — if in-process
+    // hot-reload is ever added, this is the single seam that must re-fire.
+    // The getter lets the router track wholesale array replacement (e.g. tests
+    // that do `api.actions.actions = api.actions.actions.filter(...)`).
+    const router = new Router();
+    router.compile(() => api.actions.actions);
+
     return {
       actions,
+      router,
 
       enqueue: this.enqueue,
       fanOut: this.fanOut,

package/initializers/resque.ts

@@ -279,9 +279,11 @@ export class Resque extends Initializer {
   };
 
   /**
-   * Wrap an action as a node-resque job. Creates a temporary `Connection` with type `"resque"`,
-   * converts inputs to a plain object, and runs the action via `connection.act()`. Handles
-   * fan-out result/error collection and recurring task re-enqueue.
+   * Wrap an action as a node-resque job. Creates a fresh `Connection` of type `"task"`
+   * with an empty in-memory session stub (tasks are fresh starts — no Redis read/write
+   * for session), converts inputs to a plain object, and runs the action via
+   * `connection.act()`. Handles fan-out result/error collection and recurring task
+   * re-enqueue.
    */
   wrapActionAsJob = (
     action: Action,
@@ -291,18 +293,6 @@ export class Resque extends Initializer {
       pluginOptions: {},
 
       perform: async function (params: ActionParams<typeof action>) {
-        const connection = new Connection(
-          "resque",
-          `job:${api.process.name}:${SERVER_JOB_COUNTER++}}`,
-        );
-
-        const propagatedCorrelationId = params._correlationId as
-          | string
-          | undefined;
-        if (propagatedCorrelationId) {
-          connection.correlationId = propagatedCorrelationId;
-        }
-
         const plainParams: Record<string, unknown> =
           typeof params === "object" && params !== null
             ? Object.fromEntries(
@@ -312,6 +302,27 @@ export class Resque extends Initializer {
               )
             : {};
 
+        const propagatedCorrelationId = plainParams._correlationId as
+          | string
+          | undefined;
+
+        const connection = new Connection(
+          "task",
+          `job:${api.process.name}:${SERVER_JOB_COUNTER++}`,
+        );
+        if (propagatedCorrelationId) {
+          connection.correlationId = propagatedCorrelationId;
+        }
+        // Synthesize an empty session in-memory — tasks are fresh starts; needed data
+        // must come through action params, not session state.
+        connection.session = {
+          id: `task:${connection.id}`,
+          cookieName: config.session.cookieName,
+          createdAt: Date.now(),
+          data: {},
+        };
+        connection.sessionLoaded = true;
+
         const fanOutId = plainParams._fanOutId as string | undefined;
 
         let response: Awaited<ReturnType<(typeof action)["run"]>>;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "keryx",
-  "version": "0.21.7",
+  "version": "0.22.0",
   "module": "index.ts",
   "type": "module",
   "license": "MIT",
@@ -49,6 +49,7 @@
     "middleware/",
     "servers/",
     "templates/",
+    "testing/",
     "util/",
     "api.ts",
     "index.ts",
@@ -69,7 +70,8 @@
     "./util/*": "./util/*",
     "./config": "./config/index.ts",
     "./config/*": "./config/*",
-    "./servers/*": "./servers/*"
+    "./servers/*": "./servers/*",
+    "./testing": "./testing/index.ts"
   },
   "scripts": {
     "start": "bun keryx.ts start",

package/templates/scaffold/middleware-session.ts.mustache

@@ -3,7 +3,7 @@ import type { ActionMiddleware } from "keryx/classes/Action.ts";
 
 export const SessionMiddleware: ActionMiddleware = {
   runBefore: async (_params, connection: Connection<{ userId?: number }>) => {
-    if (!connection.session || !connection.session.data.userId) {
+    if (!connection.session?.data.userId) {
       throw new TypedError({
         message: "Session not found",
         type: ErrorType.CONNECTION_SESSION_NOT_FOUND,

package/testing/index.ts

@@ -0,0 +1,105 @@
+import { afterAll, beforeAll } from "bun:test";
+import { api } from "../api";
+import type { WebServer } from "../servers/web";
+
+/**
+ * Generous lifecycle hook timeout (15s) for `beforeAll` / `afterAll`.
+ *
+ * `api.start()` and `api.stop()` connect to Redis, Postgres, run migrations,
+ * etc. — slower than a unit test, especially in CI. Pass this as the second
+ * argument to `beforeAll` / `afterAll` so hooks don't time out.
+ *
+ * Note: `bun:test`'s `setDefaultTimeout` and `bunfig.toml [test].timeout` only
+ * apply to `test()` blocks, not lifecycle hooks.
+ */
+export const HOOK_TIMEOUT = 15_000;
+
+/**
+ * Return the actual URL the web server bound to (with resolved port).
+ * Returns an empty string if the web server isn't running.
+ *
+ * Call after `api.start()` so the server has bound its port. Useful when
+ * `WEB_SERVER_PORT=0` is set so each test file gets a random available port.
+ */
+export function serverUrl(): string {
+  const web = api.servers.servers.find(
+    (s: { name: string }) => s.name === "web",
+  ) as WebServer | undefined;
+  return web?.url || "";
+}
+
+/**
+ * Register `beforeAll` / `afterAll` hooks that start and stop the API around
+ * a test file. Returns a getter for the bound server URL — the URL isn't known
+ * until after `api.start()` binds the port, so it can't be returned directly.
+ *
+ * **Hook ordering gotcha.** `bun:test` runs `beforeAll` and `afterAll` hooks in
+ * registration order (not LIFO). So whichever hook is registered first runs
+ * first — in both phases. This matters in two ways:
+ *
+ * 1. **Config overrides that must happen before `api.start()`** — register a
+ *    separate `beforeAll` that sets the config *before* calling `useTestServer()`,
+ *    so it runs first.
+ * 2. **Teardown cleanup that needs Redis/DB access** — the helper's `afterAll`
+ *    calls `api.stop()`, which closes the Redis and Postgres connections. Any
+ *    cleanup that touches those must run *before* `api.stop()`. Since `afterAll`
+ *    also runs in registration order, the helper's `api.stop()` runs first. Put
+ *    connection-dependent cleanup in the same `afterAll` block as the original
+ *    start/stop pair rather than splitting it, or handle cleanup in `afterEach`.
+ *
+ * @param opts.clearDatabase - Truncate all tables in `beforeAll`. Default `false`.
+ *   Requires the `db` initializer to be active. Opt in for tests that mutate
+ *   persistent state.
+ * @param opts.clearRedis - Flush the current Redis DB in `beforeAll`. Default
+ *   `false`. Requires the `redis` initializer to be active. Opt in for tests
+ *   that exercise pub/sub so messages from prior tests don't leak in.
+ * @returns A getter function that returns the server URL once `api.start()` has
+ *   bound its port. Call the getter at each fetch site: `fetch(getUrl() + "/api/...")`.
+ *
+ * @example
+ * const getUrl = useTestServer({ clearDatabase: true });
+ *
+ * test("creates a user", async () => {
+ *   const res = await fetch(getUrl() + "/api/user", { method: "PUT", ... });
+ *   expect(res.status).toBe(200);
+ * });
+ */
+export function useTestServer(
+  opts: { clearDatabase?: boolean; clearRedis?: boolean } = {},
+): () => string {
+  const { clearDatabase = false, clearRedis = false } = opts;
+  let url = "";
+  beforeAll(async () => {
+    await api.start();
+    url = serverUrl();
+    if (clearDatabase) await api.db.clearDatabase();
+    if (clearRedis) await api.redis.redis.flushdb();
+  }, HOOK_TIMEOUT);
+  afterAll(async () => {
+    await api.stop();
+  }, HOOK_TIMEOUT);
+  return () => url;
+}
+
+/**
+ * Poll a condition until it returns true, or throw after a timeout.
+ *
+ * Use this instead of fixed `Bun.sleep()` calls when waiting for async side
+ * effects like background tasks, pub/sub delivery, or presence updates.
+ *
+ * @param condition - Function returning a boolean (or Promise of one). Polled
+ *   repeatedly until it returns truthy.
+ * @param opts.interval - Milliseconds between polls. Default 50.
+ * @param opts.timeout - Milliseconds before giving up. Default 5000.
+ * @throws {Error} If the condition doesn't become truthy before the timeout.
+ */
+export async function waitFor(
+  condition: () => Promise<boolean> | boolean,
+  { interval = 50, timeout = 5000 } = {},
+): Promise<void> {
+  const start = Date.now();
+  while (!(await condition())) {
+    if (Date.now() - start > timeout) throw new Error("waitFor timed out");
+    await Bun.sleep(interval);
+  }
+}

package/util/webRouting.ts

@@ -7,6 +7,10 @@ import { config } from "../config";
 /**
  * Match a URL path + HTTP method against registered action routes.
  * Returns the action name and any extracted path parameters, or `null` if no match.
+ *
+ * Delegates to the pre-compiled `api.actions.router` for O(1) static-route lookup
+ * and an ordered scan of parameterized routes. This function only handles the
+ * transport concern of stripping the configured API prefix before routing.
  */
 export async function determineActionName(
   url: ReturnType<typeof parse>,
@@ -20,46 +24,14 @@ export async function determineActionName(
     "",
   );
 
-  for (const action of api.actions.actions) {
-    if (!action?.web?.route) continue;
-
-    // Convert route with path parameters to regex
-    const routeWithParams = `${action.web.route}`.replace(/:\w+/g, "([^/]+)");
-    const matcher =
-      action.web.route instanceof RegExp
-        ? action.web.route
-        : new RegExp(`^${routeWithParams}$`);
-
-    if (
-      pathToMatch &&
-      pathToMatch.match(matcher) &&
-      method.toUpperCase() === action.web.method
-    ) {
-      // Extract path parameters if the route has them
-      const pathParams: Record<string, string> = {};
-      const paramNames = (`${action.web.route}`.match(/:\w+/g) || []).map(
-        (name) => name.slice(1),
-      );
-      const match = pathToMatch.match(matcher);
+  if (!pathToMatch) return { actionName: null, pathParams: null };
 
-      if (match && paramNames.length > 0) {
-        // Skip the first match (full string) and use the captured groups
-        for (let i = 0; i < paramNames.length; i++) {
-          const value = match[i + 1];
-          if (value !== undefined) {
-            pathParams[paramNames[i]] = value;
-          }
-        }
-      }
-
-      return {
-        actionName: action.name,
-        pathParams: Object.keys(pathParams).length > 0 ? pathParams : undefined,
-      };
-    }
-  }
-
-  return { actionName: null, pathParams: null };
+  const match = api.actions.router.match(
+    pathToMatch,
+    method.toUpperCase() as HTTP_METHOD,
+  );
+  if (!match) return { actionName: null, pathParams: null };
+  return { actionName: match.actionName, pathParams: match.pathParams };
 }
 
 /**