keryx 0.21.9 → 0.22.1

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/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.9",
+  "version": "0.22.1",
   "module": "index.ts",
   "type": "module",
   "license": "MIT",

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

@@ -2,6 +2,14 @@ import { afterAll, beforeAll } from "bun:test";
 import { api } from "../api";
 import type { WebServer } from "../servers/web";
 
+export {
+  buildWebSocket,
+  createSession,
+  createUser,
+  subscribeToChannel,
+  waitForBroadcastMessages,
+} from "./websocket";
+
 /**
  * Generous lifecycle hook timeout (15s) for `beforeAll` / `afterAll`.
  *

package/testing/websocket.ts

@@ -0,0 +1,171 @@
+import { expect } from "bun:test";
+import { api } from "../api";
+import type { WebServer } from "../servers/web";
+
+const wsUrl = () => {
+  const web = api.servers.servers.find(
+    (s: { name: string }) => s.name === "web",
+  ) as WebServer | undefined;
+  return (web?.url || "")
+    .replace("https://", "wss://")
+    .replace("http://", "ws://");
+};
+
+/**
+ * Open a WebSocket against the running test server and return the socket along
+ * with a mutable array that accumulates every `message` event as it arrives.
+ *
+ * The promise resolves once the socket's `open` event fires, so callers can
+ * immediately send actions without an additional readiness check.
+ *
+ * @param options.headers - Request headers to include in the WebSocket upgrade
+ *   (for example a session cookie). Optional.
+ * @returns An object with the open `socket` and the live `messages` array that
+ *   every subsequent handler populates.
+ */
+export const buildWebSocket = async (
+  options: { headers?: Record<string, string> } = {},
+) => {
+  const socket = new WebSocket(wsUrl(), { headers: options.headers });
+  const messages: MessageEvent[] = [];
+  socket.addEventListener("message", (event) => {
+    messages.push(event);
+  });
+  socket.addEventListener("error", (event) => {
+    console.error(event);
+  });
+  await new Promise((resolve) => {
+    socket.addEventListener("open", resolve);
+  });
+  return { socket, messages };
+};
+
+/**
+ * Send a `user:create` action over the given WebSocket and return the created
+ * user from the server's response.
+ *
+ * Assumes this is the first action sent on the socket — it reads `messages[0]`.
+ *
+ * @throws {Error} If the server responds with an error payload.
+ */
+export const createUser = async (
+  socket: WebSocket,
+  messages: MessageEvent[],
+  name: string,
+  email: string,
+  password: string,
+) => {
+  socket.send(
+    JSON.stringify({
+      messageType: "action",
+      action: "user:create",
+      messageId: 1,
+      params: { name, email, password },
+    }),
+  );
+
+  while (messages.length === 0) await Bun.sleep(10);
+  const response = JSON.parse(messages[0].data);
+
+  if (response.error) {
+    throw new Error(`User creation failed: ${response.error.message}`);
+  }
+
+  return response.response.user;
+};
+
+/**
+ * Send a `session:create` action over the given WebSocket and return the
+ * response payload (user + session).
+ *
+ * Assumes `createUser` was invoked first — it reads `messages[1]`.
+ *
+ * @throws {Error} If the server responds with an error payload.
+ */
+export const createSession = async (
+  socket: WebSocket,
+  messages: MessageEvent[],
+  email: string,
+  password: string,
+) => {
+  socket.send(
+    JSON.stringify({
+      messageType: "action",
+      action: "session:create",
+      messageId: 2,
+      params: { email, password },
+    }),
+  );
+
+  while (messages.length < 2) await Bun.sleep(10);
+  const response = JSON.parse(messages[1].data);
+
+  if (response.error) {
+    throw new Error(`Session creation failed: ${response.error.message}`);
+  }
+
+  return response.response;
+};
+
+/**
+ * Subscribe the socket to a channel and wait for the server's subscribe
+ * confirmation.
+ *
+ * Matches the confirmation by content rather than index, because presence
+ * broadcast events (join/leave) delivered via Redis pub/sub can arrive before
+ * the subscribe confirmation and shift message indices.
+ */
+export const subscribeToChannel = async (
+  socket: WebSocket,
+  messages: MessageEvent[],
+  channel: string,
+) => {
+  socket.send(JSON.stringify({ messageType: "subscribe", channel }));
+
+  let response: Record<string, any> | undefined;
+  while (!response) {
+    for (const m of messages) {
+      const parsed = JSON.parse(m.data);
+      if (parsed.subscribed?.channel === channel) {
+        response = parsed;
+        break;
+      }
+    }
+    if (!response) await Bun.sleep(10);
+  }
+  return response;
+};
+
+/**
+ * Wait briefly and return all broadcast (non-action-reply) messages received on
+ * the socket so far, asserting the expected count.
+ *
+ * Broadcasts are distinguished from action replies by the absence of a
+ * `messageId` field. Uses `expect()` internally so callers see a readable
+ * failure with the raw broadcast payload dumped to stderr on mismatch.
+ *
+ * @throws {Error} When the observed broadcast count does not equal
+ *   `expectedCount`.
+ */
+export const waitForBroadcastMessages = async (
+  messages: MessageEvent[],
+  expectedCount: number,
+) => {
+  await Bun.sleep(100);
+
+  const broadcastMessages: Record<string, any>[] = [];
+  for (const message of messages) {
+    const parsedMessage = JSON.parse(message.data);
+    if (!parsedMessage.messageId) {
+      broadcastMessages.push(parsedMessage);
+    }
+  }
+
+  try {
+    expect(broadcastMessages.length).toBe(expectedCount);
+  } catch (e) {
+    console.error(JSON.stringify(broadcastMessages, null, 2));
+    throw e;
+  }
+  return broadcastMessages;
+};