keryx 0.4.0 → 0.5.0

package/classes/Action.ts

@@ -50,6 +50,9 @@ export type ActionConstructorInputs = {
     method?: HTTP_METHOD;
   };
 
+  /** Per-action timeout in ms (overrides global `config.server.web.actionTimeout`; 0 disables) */
+  timeout?: number;
+
   /** Configure this action as a background task/job */
   task?: {
     /** Optional recurring frequency in milliseconds */
@@ -85,6 +88,7 @@ export abstract class Action {
     route: RegExp | string;
     method: HTTP_METHOD;
   };
+  timeout?: number;
   task?: {
     frequency?: number;
     queue: string;
@@ -95,6 +99,7 @@ export abstract class Action {
     this.description = args.description ?? `An Action: ${this.name}`;
     this.inputs = args.inputs;
     this.middleware = args.middleware ?? [];
+    this.timeout = args.timeout;
     this.mcp = { enabled: true, ...args.mcp };
     this.web = {
       route: args.web?.route ?? `/${this.name}`,
@@ -111,11 +116,26 @@ export abstract class Action {
    * It can be `async`.
    * Usually the goal of this run method is to return the data that you want to be sent to API consumers.
    * If error is thrown in this method, it will be logged, caught, and returned to the client as `error`
+   *
+   * @param params - The validated and coerced action inputs. The type is inferred from the
+   *   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 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
+   *   cancellable APIs (e.g., `fetch`) to exit promptly. Not provided when timeouts are
+   *   disabled (`timeout: 0`).
    * @throws {TypedError} All errors thrown should be TypedError instances
    */
   abstract run(
     params: ActionParams<Action>,
     connection?: Connection,
+    abortSignal?: AbortSignal,
   ): Promise<any>;
 }
 

package/classes/Connection.ts

@@ -76,7 +76,26 @@ export class Connection<T extends Record<string, any> = Record<string, any>> {
         }
       }
 
-      response = await action.run(formattedParams, this);
+      const timeoutMs = action.timeout ?? config.actions.timeout;
+      if (timeoutMs > 0) {
+        const controller = new AbortController();
+        const timeoutError = new TypedError({
+          message: `Action '${action.name}' timed out after ${timeoutMs}ms`,
+          type: ErrorType.CONNECTION_ACTION_TIMEOUT,
+        });
+        const timeoutPromise = new Promise<never>((_, reject) => {
+          setTimeout(() => {
+            controller.abort();
+            reject(timeoutError);
+          }, timeoutMs);
+        });
+        response = await Promise.race([
+          action.run(formattedParams, this, controller.signal),
+          timeoutPromise,
+        ]);
+      } else {
+        response = await action.run(formattedParams, this);
+      }
 
       for (const middleware of action.middleware ?? []) {
         if (middleware.runAfter) {

package/classes/TypedError.ts

@@ -27,6 +27,7 @@ export enum ErrorType {
   "CONNECTION_CHANNEL_AUTHORIZATION" = "CONNECTION_CHANNEL_AUTHORIZATION",
   "CONNECTION_CHANNEL_VALIDATION" = "CONNECTION_CHANNEL_VALIDATION",
 
+  "CONNECTION_ACTION_TIMEOUT" = "CONNECTION_ACTION_TIMEOUT",
   "CONNECTION_RATE_LIMITED" = "CONNECTION_RATE_LIMITED",
 
   "CONNECTION_TASK_DEFINITION" = "CONNECTION_TASK_DEFINITION",
@@ -56,6 +57,7 @@ export const ErrorStatusCodes: Record<ErrorType, number> = {
   [ErrorType.CONNECTION_NOT_SUBSCRIBED]: 406,
   [ErrorType.CONNECTION_CHANNEL_AUTHORIZATION]: 403,
   [ErrorType.CONNECTION_CHANNEL_VALIDATION]: 400,
+  [ErrorType.CONNECTION_ACTION_TIMEOUT]: 408,
   [ErrorType.CONNECTION_RATE_LIMITED]: 429,
 
   [ErrorType.CONNECTION_TASK_DEFINITION]: 500,

package/config/actions.ts

@@ -0,0 +1,7 @@
+import { loadFromEnvIfSet } from "../util/config";
+
+export const configActions = {
+  timeout: await loadFromEnvIfSet("ACTION_TIMEOUT", 300_000),
+  fanOutBatchSize: await loadFromEnvIfSet("ACTION_FAN_OUT_BATCH_SIZE", 100),
+  fanOutResultTtl: await loadFromEnvIfSet("ACTION_FAN_OUT_RESULT_TTL", 600),
+};

package/config/index.ts

@@ -1,3 +1,4 @@
+import { configActions } from "./actions";
 import { configChannels } from "./channels";
 import { configDatabase } from "./database";
 import { configLogger } from "./logger";
@@ -11,6 +12,7 @@ import { configSession } from "./session";
 import { configTasks } from "./tasks";
 
 export const config = {
+  actions: configActions,
   channels: configChannels,
   process: configProcess,
   logger: configLogger,

package/initializers/actionts.ts

@@ -5,13 +5,11 @@ import { api, logger } from "../api";
 import { DEFAULT_QUEUE, type Action } from "../classes/Action";
 import { Initializer } from "../classes/Initializer";
 import { ErrorType, TypedError } from "../classes/TypedError";
+import { config } from "../config";
 import { globLoader } from "../util/glob";
 
 const namespace = "actions";
 
-const DEFAULT_FAN_OUT_BATCH_SIZE = 100;
-const DEFAULT_FAN_OUT_RESULT_TTL = 600; // 10 minutes in seconds
-
 export type FanOutJob = {
   action: string;
   inputs?: TaskInputs;
@@ -130,8 +128,10 @@ export class Actions extends Initializer {
       return { ...job, queue: resolvedQueue, inputs: job.inputs ?? {} };
     });
 
-    const batchSize = resolvedOptions.batchSize ?? DEFAULT_FAN_OUT_BATCH_SIZE;
-    const resultTtl = resolvedOptions.resultTtl ?? DEFAULT_FAN_OUT_RESULT_TTL;
+    const batchSize =
+      resolvedOptions.batchSize ?? config.actions.fanOutBatchSize;
+    const resultTtl =
+      resolvedOptions.resultTtl ?? config.actions.fanOutResultTtl;
     const fanOutId = randomUUID();
     const metaKey = `fanout:${fanOutId}`;
 

package/package.json

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