keryx 0.25.5 → 0.26.0

package/classes/Connection.ts

@@ -11,6 +11,54 @@ import { LogFormat } from "./Logger";
 import { StreamingResponse } from "./StreamingResponse";
 import { ErrorType, TypedError } from "./TypedError";
 
+/**
+ * Per-invocation context passed to {@link BeforeActHook} and {@link AfterActHook}.
+ * The same object instance threads from `beforeAct` to `afterAct` for a single
+ * action invocation, so hooks can stash span refs, timing data, etc.
+ */
+export interface ActContext {
+  /** Mutable scratch space shared between `beforeAct` and `afterAct`. */
+  metadata: Record<string, unknown>;
+}
+
+/**
+ * Unified outcome passed to {@link AfterActHook}. Discriminate via the `success` field.
+ * Covers both the happy-path and error paths of an action invocation.
+ */
+export type ActOutcome =
+  | { success: true; response: unknown; duration: number }
+  | { success: false; error: unknown; duration: number };
+
+/**
+ * Runs inside `Connection.act()` after params are validated and before the action's
+ * own `runBefore` middleware. Fires for every action invocation regardless of
+ * transport (web, websocket, task, cli, mcp, …) — inspect `connection.type` to
+ * discriminate. Throwing fails the action.
+ *
+ * Register via `api.hooks.actions.beforeAct(...)`.
+ */
+export type BeforeActHook = (
+  actionName: string,
+  params: Record<string, unknown>,
+  connection: Connection,
+  ctx: ActContext,
+) => Promise<void> | void;
+
+/**
+ * Runs inside `Connection.act()` after the action completes (success or failure),
+ * in a `finally` block so it always fires if the corresponding `beforeAct` fired.
+ * Receives the same `ctx` plus an {@link ActOutcome} describing what happened.
+ *
+ * Register via `api.hooks.actions.afterAct(...)`.
+ */
+export type AfterActHook = (
+  actionName: string,
+  params: Record<string, unknown>,
+  connection: Connection,
+  ctx: ActContext,
+  outcome: ActOutcome,
+) => Promise<void> | void;
+
 /**
  * Represents a client connection to the server — HTTP request, WebSocket, or internal caller.
  * Each connection tracks its own session, channel subscriptions, and rate-limit state.
@@ -108,6 +156,11 @@ export class Connection<
 
     let action: Action | undefined;
     let formattedParams: Record<string, unknown> | undefined;
+    // Cross-transport action hooks (api.hooks.actions.beforeAct / afterAct).
+    // beforeActRan guards afterAct so we only fire after-hooks for invocations
+    // where before-hooks also fired (i.e. action found + params validated).
+    const actCtx: ActContext = { metadata: {} };
+    let beforeActRan = false;
     try {
       action = this.findAction(actionName);
       if (!action) {
@@ -122,6 +175,11 @@ export class Connection<
 
       formattedParams = await this.formatParams(params, action);
 
+      for (const hook of api.hooks.actions.beforeActHooks) {
+        await hook(action.name, formattedParams, this, actCtx);
+      }
+      beforeActRan = true;
+
       for (const middleware of action.middleware ?? []) {
         if (middleware.runBefore) {
           const middlewareResponse = await middleware.runBefore(
@@ -184,6 +242,15 @@ export class Connection<
           }
         }
       }
+      if (beforeActRan && action && formattedParams) {
+        const actDuration = new Date().getTime() - reqStartTime;
+        const outcome: ActOutcome = error
+          ? { success: false, error, duration: actDuration }
+          : { success: true, response, duration: actDuration };
+        for (const hook of api.hooks.actions.afterActHooks) {
+          await hook(action.name, formattedParams, this, actCtx, outcome);
+        }
+      }
       this._actDepth--;
     }
 

package/index.ts

@@ -5,6 +5,7 @@ import "./initializers/actionts";
 import "./initializers/channels";
 import "./initializers/connections";
 import "./initializers/db";
+import "./initializers/hooks";
 import "./initializers/mcp";
 import "./initializers/oauth";
 import "./initializers/observability";
@@ -22,16 +23,34 @@ export type { ActionMiddleware } from "./classes/Action";
 export { HTTP_METHOD, MCP_RESPONSE_FORMAT } from "./classes/Action";
 export type { ChannelMiddleware } from "./classes/Channel";
 export { CHANNEL_NAME_PATTERN } from "./classes/Channel";
+export type {
+  ActContext,
+  ActOutcome,
+  AfterActHook,
+  BeforeActHook,
+} from "./classes/Connection";
 export { Connection } from "./classes/Connection";
 export { LogLevel } from "./classes/Logger";
 export type { KeryxPlugin, PluginGenerator } from "./classes/Plugin";
 export { SSEResponse, StreamingResponse } from "./classes/StreamingResponse";
 export { ErrorStatusCodes, ErrorType, TypedError } from "./classes/TypedError";
 export type { KeryxConfig } from "./config";
+export type { OnEnqueueHook } from "./initializers/actionts";
+export type {
+  AfterJobHook,
+  BeforeJobHook,
+  JobContext,
+  JobOutcome,
+} from "./initializers/resque";
 export type { SessionData } from "./initializers/session";
 export { checkRateLimit, RateLimitMiddleware } from "./middleware/rateLimit";
 export { TransactionMiddleware } from "./middleware/transaction";
-export type { WebServer } from "./servers/web";
+export type {
+  AfterRequestHook,
+  BeforeRequestHook,
+  RequestContext,
+  WebServer,
+} from "./servers/web";
 export { buildProgram } from "./util/cli";
 export { deepMerge, deepMergeDefaults, loadFromEnvIfSet } from "./util/config";
 export { getValidTypes } from "./util/generate";

package/initializers/actionts.ts

@@ -68,11 +68,44 @@ declare module "keryx" {
 
 export type TaskInputs = Record<string, any>;
 
+/**
+ * Runs when any action is enqueued — via {@link Actions.enqueue}, {@link Actions.enqueueAt},
+ * {@link Actions.enqueueIn}, or the per-job calls inside {@link Actions.fanOut}. Fires after
+ * the queue has been resolved and before the job is placed in Redis.
+ *
+ * Return a new `TaskInputs` object to replace the payload (e.g. to inject trace headers),
+ * or return `void` / `undefined` to leave the payload unchanged. If multiple hooks are
+ * registered they run sequentially in registration order; each receives the output of
+ * the previous one.
+ *
+ * Register via `api.hooks.actions.onEnqueue(...)`.
+ */
+export type OnEnqueueHook = (
+  actionName: string,
+  inputs: TaskInputs,
+  queue: string,
+) => Promise<TaskInputs | void> | TaskInputs | void;
+
 export class Actions extends Initializer {
   constructor() {
     super(namespace);
+    this.dependsOn = ["hooks"];
   }
 
+  /** Run all registered `onEnqueue` hooks, threading inputs through each. */
+  private runOnEnqueueHooks = async (
+    actionName: string,
+    inputs: TaskInputs,
+    queue: string,
+  ): Promise<TaskInputs> => {
+    let current = inputs;
+    for (const hook of api.hooks.actions.onEnqueueHooks) {
+      const next = await hook(actionName, current, queue);
+      if (next !== undefined) current = next;
+    }
+    return current;
+  };
+
   /**
    * Enqueue an action to be performed in the background.
    *
@@ -96,11 +129,12 @@ export class Actions extends Initializer {
       });
     }
     queue = queue ?? action?.task?.queue ?? DEFAULT_QUEUE;
+    const finalInputs = await this.runOnEnqueueHooks(actionName, inputs, queue);
     api.observability.task.enqueuedTotal.add(1, {
       action: actionName,
       queue,
     });
-    return api.resque.queue.enqueue(queue, actionName, [inputs]);
+    return api.resque.queue.enqueue(queue, actionName, [finalInputs]);
   };
 
   /**
@@ -302,11 +336,12 @@ export class Actions extends Initializer {
     queue: string = DEFAULT_QUEUE,
     suppressDuplicateTaskError = false,
   ) => {
+    const finalInputs = await this.runOnEnqueueHooks(actionName, inputs, queue);
     return api.resque.queue.enqueueAt(
       timestamp,
       queue,
       actionName,
-      [inputs],
+      [finalInputs],
       suppressDuplicateTaskError,
     );
   };
@@ -328,11 +363,12 @@ export class Actions extends Initializer {
     queue: string = DEFAULT_QUEUE,
     suppressDuplicateTaskError = false,
   ) => {
+    const finalInputs = await this.runOnEnqueueHooks(actionName, inputs, queue);
     return api.resque.queue.enqueueIn(
       time,
       queue,
       actionName,
-      [inputs],
+      [finalInputs],
       suppressDuplicateTaskError,
     );
   };

package/initializers/hooks.ts

@@ -0,0 +1,114 @@
+import type { AfterActHook, BeforeActHook } from "../classes/Connection";
+import { Initializer } from "../classes/Initializer";
+import type { AfterRequestHook, BeforeRequestHook } from "../servers/web";
+import type { OnEnqueueHook } from "./actionts";
+import type { AfterJobHook, BeforeJobHook } from "./resque";
+
+const namespace = "hooks";
+
+declare module "keryx" {
+  export interface API {
+    [namespace]: Awaited<ReturnType<Hooks["initialize"]>>;
+  }
+}
+
+/**
+ * Central registry for framework lifecycle hooks. Plugins register hooks here
+ * from their initializer's `initialize()`; the framework iterates the registered
+ * hooks at runtime.
+ *
+ * Public surface: `api.hooks.web`, `api.hooks.actions`, `api.hooks.resque`. See
+ * the respective hook type definitions for semantics (in `servers/web.ts`,
+ * `initializers/actionts.ts`, `initializers/resque.ts`).
+ */
+export class Hooks extends Initializer {
+  private webBeforeRequest: BeforeRequestHook[] = [];
+  private webAfterRequest: AfterRequestHook[] = [];
+  private actionsOnEnqueue: OnEnqueueHook[] = [];
+  private actionsBeforeAct: BeforeActHook[] = [];
+  private actionsAfterAct: AfterActHook[] = [];
+  private resqueBeforeJob: BeforeJobHook[] = [];
+  private resqueAfterJob: AfterJobHook[] = [];
+
+  constructor() {
+    super(namespace);
+  }
+
+  async initialize() {
+    const self = this;
+    return {
+      web: {
+        /**
+         * Register a hook to run at the start of every HTTP request, before
+         * routing. Covers static files, OAuth, MCP, metrics, and actions.
+         * Does not fire for WebSocket upgrades.
+         */
+        beforeRequest(hook: BeforeRequestHook): void {
+          self.webBeforeRequest.push(hook);
+        },
+        /**
+         * Register a hook to run after the `Response` is built, before
+         * compression. Receives the same `ctx` object passed to `beforeRequest`,
+         * so state stashed in `ctx.metadata` flows through.
+         */
+        afterRequest(hook: AfterRequestHook): void {
+          self.webAfterRequest.push(hook);
+        },
+        /** @internal Iterated by `WebServer.handleIncomingConnection`. */
+        beforeRequestHooks:
+          self.webBeforeRequest as ReadonlyArray<BeforeRequestHook>,
+        /** @internal Iterated by `WebServer.handleIncomingConnection`. */
+        afterRequestHooks:
+          self.webAfterRequest as ReadonlyArray<AfterRequestHook>,
+      },
+      actions: {
+        /**
+         * Register a hook to run on every enqueue. Fires for `enqueue`,
+         * `enqueueAt`, `enqueueIn`, and per-job inside `fanOut`. Hooks may
+         * mutate inputs by returning a replacement object.
+         */
+        onEnqueue(hook: OnEnqueueHook): void {
+          self.actionsOnEnqueue.push(hook);
+        },
+        /**
+         * Register a hook to run inside `Connection.act()` after params are
+         * validated and before the action's `runBefore` middleware. Fires for
+         * every action invocation across all transports (web, websocket, task,
+         * cli, mcp, …) — inspect `connection.type` to discriminate.
+         */
+        beforeAct(hook: BeforeActHook): void {
+          self.actionsBeforeAct.push(hook);
+        },
+        /**
+         * Register a hook to run inside `Connection.act()` in a `finally` block
+         * after the action completes (success or failure). Receives the same
+         * `ctx` as `beforeAct` plus a unified {@link ActOutcome}. Fires across
+         * all transports.
+         */
+        afterAct(hook: AfterActHook): void {
+          self.actionsAfterAct.push(hook);
+        },
+        /** @internal Iterated by `Actions.enqueue`, `enqueueAt`, `enqueueIn`. */
+        onEnqueueHooks: self.actionsOnEnqueue as ReadonlyArray<OnEnqueueHook>,
+        /** @internal Iterated inside `Connection.act`. */
+        beforeActHooks: self.actionsBeforeAct as ReadonlyArray<BeforeActHook>,
+        /** @internal Iterated inside `Connection.act`. */
+        afterActHooks: self.actionsAfterAct as ReadonlyArray<AfterActHook>,
+      },
+      resque: {
+        /** Register a hook to run before each job's action executes. */
+        beforeJob(hook: BeforeJobHook): void {
+          self.resqueBeforeJob.push(hook);
+        },
+        /** Register a hook to run after each job's action executes (success or failure). */
+        afterJob(hook: AfterJobHook): void {
+          self.resqueAfterJob.push(hook);
+        },
+        /** @internal Iterated inside `wrapActionAsJob.perform`. */
+        beforeJobHooks: self.resqueBeforeJob as ReadonlyArray<BeforeJobHook>,
+        /** @internal Iterated inside `wrapActionAsJob.perform`. */
+        afterJobHooks: self.resqueAfterJob as ReadonlyArray<AfterJobHook>,
+      },
+    };
+  }
+}

package/initializers/resque.ts

@@ -18,9 +18,54 @@ import {
 import { Initializer } from "../classes/Initializer";
 import { LogFormat } from "../classes/Logger";
 import { TypedError } from "../classes/TypedError";
+import type { TaskInputs } from "./actionts";
 
 const namespace = "resque";
 
+/**
+ * Per-job context passed to {@link BeforeJobHook} and {@link AfterJobHook}.
+ * The same object instance is threaded from `beforeJob` to `afterJob`, so hooks can
+ * stash span refs, timing data, or any other state in `metadata`.
+ */
+export interface JobContext {
+  /** Mutable scratch space shared between `beforeJob` and `afterJob`. */
+  metadata: Record<string, unknown>;
+}
+
+/**
+ * Unified outcome passed to {@link AfterJobHook}. Discriminate via the `success` field.
+ * Covers both the worker `success` and `failure` paths in a single shape.
+ */
+export type JobOutcome =
+  | { success: true; result: unknown; duration: number }
+  | { success: false; error: unknown; duration: number };
+
+/**
+ * Runs inside the job wrapper immediately before the action executes (i.e. before
+ * `connection.act()`). Receives the action name and decoded params, giving plugins
+ * access to trace headers or other correlation data embedded in inputs. Hooks run
+ * sequentially in registration order. Throwing fails the job.
+ */
+export type BeforeJobHook = (
+  actionName: string,
+  params: TaskInputs,
+  ctx: JobContext,
+) => Promise<void> | void;
+
+/**
+ * Runs inside the job wrapper after the action executes, in a `finally` block so it
+ * fires for both success and failure. Receives the same `ctx` passed to `beforeJob`
+ * plus a {@link JobOutcome} describing what happened. Hooks run sequentially in
+ * registration order. Errors thrown by an `afterJob` hook do not mask an action
+ * error but may surface instead of it if the action succeeded.
+ */
+export type AfterJobHook = (
+  actionName: string,
+  params: TaskInputs,
+  ctx: JobContext,
+  outcome: JobOutcome,
+) => Promise<void> | void;
+
 function logResqueEvent(
   level: "info" | "warn",
   textMessage: string,
@@ -49,7 +94,7 @@ let SERVER_JOB_COUNTER = 1;
 export class Resque extends Initializer {
   constructor() {
     super(namespace);
-    this.dependsOn = ["redis", "actions", "process"];
+    this.dependsOn = ["redis", "actions", "process", "hooks"];
   }
 
   /** Create and connect the resque `Queue` instance (used for enqueuing jobs). */
@@ -322,15 +367,32 @@ export class Resque extends Initializer {
 
         const fanOutId = plainParams._fanOutId as string | undefined;
 
+        const jobCtx: JobContext = { metadata: {} };
+        const jobStartTime = Date.now();
+        for (const hook of api.hooks.resque.beforeJobHooks) {
+          await hook(action.name, plainParams, jobCtx);
+        }
+
         let response: Awaited<ReturnType<(typeof action)["run"]>>;
         let error: TypedError | undefined;
+        let outcome: JobOutcome | undefined;
         try {
           const payload = await connection.act(action.name, plainParams);
           response = payload.response;
           error = payload.error;
 
           if (error) throw error;
+          outcome = {
+            success: true,
+            result: response,
+            duration: Date.now() - jobStartTime,
+          };
         } catch (e) {
+          outcome = {
+            success: false,
+            error: e,
+            duration: Date.now() - jobStartTime,
+          };
           // Collect fan-out error before re-throwing
           if (fanOutId) {
             const metaKey = `fanout:${fanOutId}`;
@@ -351,6 +413,11 @@ export class Resque extends Initializer {
           }
           throw e;
         } finally {
+          if (outcome) {
+            for (const hook of api.hooks.resque.afterJobHooks) {
+              await hook(action.name, plainParams, jobCtx, outcome);
+            }
+          }
           if (
             action.task &&
             action.task.frequency &&

package/initializers/servers.ts

@@ -17,7 +17,7 @@ declare module "keryx" {
 export class Servers extends Initializer {
   constructor() {
     super(namespace);
-    this.dependsOn = ["actions"];
+    this.dependsOn = ["actions", "hooks"];
     this.runModes = [RUN_MODE.SERVER];
   }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "keryx",
-  "version": "0.25.5",
+  "version": "0.26.0",
   "module": "index.ts",
   "type": "module",
   "license": "MIT",

package/servers/web.ts

@@ -25,10 +25,49 @@ import {
 } from "../util/webSocket";
 import { handleStaticFile } from "../util/webStaticFiles";
 
+/**
+ * Per-request context passed to {@link BeforeRequestHook} and {@link AfterRequestHook}.
+ * The same object instance is passed to both hooks for a given request, so `beforeRequest`
+ * implementations can stash state (e.g. span refs, start time) in `metadata` for
+ * `afterRequest` to pick up.
+ */
+export interface RequestContext {
+  /** Client IP address as reported by `server.requestIP()`, or `"unknown-IP"`. */
+  ip: string;
+  /** Session id from the session cookie, or a freshly minted UUID. */
+  id: string;
+  /** Mutable scratch space shared between `beforeRequest` and `afterRequest`. */
+  metadata: Record<string, unknown>;
+}
+
+/**
+ * Runs at the start of every HTTP request, before any routing or static file handling.
+ * WebSocket upgrades do not fire this hook. Throwing an error propagates out of the
+ * request handler. Hooks run sequentially in registration order.
+ */
+export type BeforeRequestHook = (
+  req: Request,
+  ctx: RequestContext,
+) => Promise<void> | void;
+
+/**
+ * Runs after the `Response` is built and before compression. Receives the same `ctx`
+ * object that was passed to the matching `beforeRequest`. Hooks run sequentially in
+ * registration order.
+ */
+export type AfterRequestHook = (
+  req: Request,
+  res: Response,
+  ctx: RequestContext,
+) => Promise<void> | void;
+
 /**
  * HTTP + WebSocket server built on `Bun.serve`. Handles REST action routing (with path params),
  * static file serving (with ETag/304 caching), WebSocket connections (actions, PubSub subscribe/unsubscribe),
- * OAuth endpoints, and MCP SSE streams. Exposes `api.servers.web`.
+ * OAuth endpoints, and MCP SSE streams.
+ *
+ * Plugins register HTTP lifecycle hooks via `api.hooks.web.beforeRequest` /
+ * `api.hooks.web.afterRequest`.
  */
 export class WebServer extends Server<ReturnType<typeof Bun.serve>> {
   /** The actual port the server bound to (resolved after start, e.g. when config port is 0). */
@@ -169,8 +208,17 @@ export class WebServer extends Server<ReturnType<typeof Bun.serve>> {
     )
       return; // upgrade the request to a WebSocket
 
+    const ctx: RequestContext = { ip, id, metadata: {} };
+    for (const hook of api.hooks.web.beforeRequestHooks) {
+      await hook(req, ctx);
+    }
+
     const response = await this.handleHttpRequest(req, server, ip, id);
 
+    for (const hook of api.hooks.web.afterRequestHooks) {
+      await hook(req, response, ctx);
+    }
+
     // SSE and other streaming responses: disable idle timeout and skip compression
     if (response.headers.get("Content-Type")?.includes("text/event-stream")) {
       server.timeout(req, 0);