keryx 0.16.3 → 0.17.0

package/actions/status.ts

@@ -1,3 +1,4 @@
+import { sql } from "drizzle-orm";
 import { z } from "zod";
 import { Action, api } from "../api";
 import { HTTP_METHOD } from "../classes/Action";
@@ -6,7 +7,7 @@ import packageJSON from "../package.json";
 export class Status implements Action {
   name = "status";
   description =
-    "Returns server health and runtime information including the server name, process ID, package version, uptime in milliseconds, and memory consumption in MB. Does not require authentication.";
+    "Returns server health and runtime information including the server name, process ID, package version, uptime in milliseconds, memory consumption in MB, and dependency health checks for the database and Redis. Does not require authentication.";
   inputs = z.object({});
   web = { route: "/status", method: HTTP_METHOD.GET };
 
@@ -14,12 +15,35 @@ export class Status implements Action {
     const consumedMemoryMB =
       Math.round((process.memoryUsage().heapUsed / 1024 / 1024) * 100) / 100;
 
+    let databaseHealthy = false;
+    try {
+      if (api.db?.db) {
+        await api.db.db.execute(sql`SELECT NOW()`);
+        databaseHealthy = true;
+      }
+    } catch {}
+
+    let redisHealthy = false;
+    try {
+      if (api.redis?.redis) {
+        await api.redis.redis.ping();
+        redisHealthy = true;
+      }
+    } catch {}
+
+    const healthy = databaseHealthy && redisHealthy;
+
     return {
       name: api.process.name,
       pid: api.process.pid,
       version: packageJSON.version,
       uptime: new Date().getTime() - api.bootTime,
       consumedMemoryMB,
+      healthy,
+      checks: {
+        database: databaseHealthy,
+        redis: redisHealthy,
+      },
     };
   }
 }

package/actions/swagger.ts

@@ -182,18 +182,31 @@ export class Swagger implements Action {
 
       // Build responses - use generated schema if available
       const responses = JSON.parse(JSON.stringify(swaggerResponses));
-      const responseSchema = api.swagger?.responseSchemas[action.name];
-      if (responseSchema) {
-        const schemaName = `${action.name.replace(/:/g, "_")}_Response`;
-        components.schemas[schemaName] = responseSchema;
+
+      if (action.web?.streaming) {
+        // Streaming endpoints return SSE
         responses["200"] = {
-          description: "successful operation",
+          description: "Server-Sent Events stream",
           content: {
-            "application/json": {
-              schema: { $ref: `#/components/schemas/${schemaName}` },
+            "text/event-stream": {
+              schema: { type: "string" },
             },
           },
         };
+      } else {
+        const responseSchema = api.swagger?.responseSchemas[action.name];
+        if (responseSchema) {
+          const schemaName = `${action.name.replace(/:/g, "_")}_Response`;
+          components.schemas[schemaName] = responseSchema;
+          responses["200"] = {
+            description: "successful operation",
+            content: {
+              "application/json": {
+                schema: { $ref: `#/components/schemas/${schemaName}` },
+              },
+            },
+          };
+        }
       }
 
       // Add path/method

package/classes/Action.ts

@@ -81,6 +81,8 @@ export type ActionConstructorInputs = {
     route?: RegExp | string;
     /** HTTP method to bind the route to */
     method?: HTTP_METHOD;
+    /** When true, Swagger documents this endpoint as returning `text/event-stream` instead of JSON */
+    streaming?: boolean;
   };
 
   /** Per-action timeout in ms (overrides global `config.server.web.actionTimeout`; 0 disables) */
@@ -136,6 +138,7 @@ export abstract class Action {
   web?: {
     route: RegExp | string;
     method: HTTP_METHOD;
+    streaming?: boolean;
   };
   timeout?: number;
   task?: {
@@ -152,6 +155,7 @@ export abstract class Action {
     this.web = {
       route: args.web?.route ?? `/${this.name}`,
       method: args.web?.method ?? HTTP_METHOD.GET,
+      streaming: args.web?.streaming ?? false,
     };
     this.task = {
       frequency: args.task?.frequency,

package/classes/Connection.ts

@@ -8,6 +8,7 @@ import type { RateLimitInfo } from "../middleware/rateLimit";
 import { isSecret } from "../util/zodMixins";
 import type { Action, ActionParams } from "./Action";
 import { LogFormat } from "./Logger";
+import { StreamingResponse } from "./StreamingResponse";
 import { ErrorType, TypedError } from "./TypedError";
 
 /**
@@ -164,8 +165,15 @@ export class Connection<
               formattedParams,
               this,
             );
-            if (middlewareResponse && middlewareResponse?.updatedResponse)
-              response = middlewareResponse.updatedResponse;
+            if (middlewareResponse && middlewareResponse?.updatedResponse) {
+              if (response instanceof StreamingResponse) {
+                logger.warn(
+                  `Middleware cannot replace a StreamingResponse for action '${actionName}'`,
+                );
+              } else {
+                response = middlewareResponse.updatedResponse;
+              }
+            }
           }
         }
       }

package/classes/StreamingResponse.ts

@@ -0,0 +1,165 @@
+/**
+ * Streaming response types for actions that need to send data incrementally.
+ * Actions return a `StreamingResponse` from `run()` to stream over HTTP (SSE or chunked),
+ * WebSocket (incremental messages), or MCP (logging messages + accumulated result).
+ */
+
+const encoder = new TextEncoder();
+
+/**
+ * Base class for streaming responses. Actions return this from `run()` to signal
+ * that the response should be streamed rather than JSON-serialized.
+ *
+ * Use the static factories `StreamingResponse.sse()` or `StreamingResponse.stream()`
+ * rather than constructing directly.
+ */
+export class StreamingResponse {
+  /** The underlying readable stream delivered to the HTTP response body. */
+  readonly stream: ReadableStream<Uint8Array>;
+  /** Content-Type header for this streaming response. */
+  readonly contentType: string;
+  /** Extra headers to include in the HTTP response. */
+  readonly headers: Record<string, string>;
+  /** Called when the stream closes (used internally for connection cleanup). */
+  onClose?: () => void;
+
+  constructor(
+    stream: ReadableStream<Uint8Array>,
+    contentType: string,
+    headers: Record<string, string> = {},
+  ) {
+    this.stream = stream;
+    this.contentType = contentType;
+    this.headers = headers;
+  }
+
+  /**
+   * Create a Server-Sent Events streaming response. Returns an `SSEResponse`
+   * with `send()` and `close()` methods for writing SSE-formatted events.
+   *
+   * @param options - Optional extra headers to include in the response.
+   * @returns A new `SSEResponse` ready to send events.
+   */
+  static sse(options?: { headers?: Record<string, string> }): SSEResponse {
+    return new SSEResponse(options?.headers);
+  }
+
+  /**
+   * Wrap an existing `ReadableStream` as a streaming response for binary or
+   * chunked transfer (e.g., file downloads, proxied responses).
+   *
+   * @param readableStream - The stream to deliver as the response body.
+   * @param options - Content type and extra headers.
+   * @returns A new `StreamingResponse` wrapping the provided stream.
+   */
+  static stream(
+    readableStream: ReadableStream<Uint8Array>,
+    options?: {
+      contentType?: string;
+      headers?: Record<string, string>;
+    },
+  ): StreamingResponse {
+    return new StreamingResponse(
+      readableStream,
+      options?.contentType ?? "application/octet-stream",
+      options?.headers ?? {},
+    );
+  }
+
+  /**
+   * Convert this streaming response into a native `Response` object, merging
+   * the provided base headers (CORS, security, session cookie, etc.) with
+   * the streaming-specific headers.
+   *
+   * @param baseHeaders - Headers from `buildHeaders()` to merge in.
+   * @returns A native `Response` with the stream as its body.
+   */
+  toResponse(baseHeaders: Record<string, string>): Response {
+    const mergedHeaders = { ...baseHeaders, ...this.headers };
+    mergedHeaders["Content-Type"] = this.contentType;
+
+    return new Response(this.stream, {
+      status: 200,
+      headers: mergedHeaders,
+    });
+  }
+}
+
+/**
+ * Server-Sent Events streaming response. Provides `send()` to emit SSE-formatted
+ * events and `close()` to end the stream.
+ *
+ * Events follow the SSE protocol: `event:`, `id:`, and `data:` fields separated
+ * by `\n`, with events delimited by `\n\n`.
+ */
+export class SSEResponse extends StreamingResponse {
+  private controller: ReadableStreamDefaultController<Uint8Array> | null = null;
+  private closed = false;
+
+  constructor(extraHeaders?: Record<string, string>) {
+    let capturedController:
+      | ReadableStreamDefaultController<Uint8Array>
+      | undefined;
+
+    const stream = new ReadableStream<Uint8Array>({
+      start(controller) {
+        capturedController = controller;
+      },
+    });
+
+    super(stream, "text/event-stream", {
+      "Cache-Control": "no-cache",
+      Connection: "keep-alive",
+      ...extraHeaders,
+    });
+
+    this.controller = capturedController!;
+  }
+
+  /**
+   * Send an SSE event to the client.
+   *
+   * @param data - The event payload. Objects are JSON-serialized; strings are sent as-is
+   *   (multiline strings are split into multiple `data:` lines per the SSE spec).
+   * @param options - Optional `event` type name and `id` for the event.
+   */
+  send(data: string | object, options?: { event?: string; id?: string }): void {
+    if (this.closed) return;
+
+    let frame = "";
+    if (options?.event) frame += `event: ${options.event}\n`;
+    if (options?.id) frame += `id: ${options.id}\n`;
+
+    const payload = typeof data === "string" ? data : JSON.stringify(data);
+    for (const line of payload.split("\n")) {
+      frame += `data: ${line}\n`;
+    }
+    frame += "\n";
+
+    this.controller?.enqueue(encoder.encode(frame));
+  }
+
+  /**
+   * Send an error event and close the stream.
+   *
+   * @param error - Error message or object to send as an `error` event.
+   */
+  sendError(error: string | object): void {
+    this.send(error, { event: "error" });
+    this.close();
+  }
+
+  /** Close the SSE stream. Fires the `onClose` callback for connection cleanup. */
+  close(): void {
+    if (this.closed) return;
+    this.closed = true;
+
+    try {
+      this.controller?.close();
+    } catch (_e) {
+      // Controller may already be closed (e.g., client disconnected)
+    }
+
+    this.onClose?.();
+  }
+}

package/index.ts

@@ -24,6 +24,7 @@ export type { ChannelMiddleware } from "./classes/Channel";
 export { CHANNEL_NAME_PATTERN } from "./classes/Channel";
 export { Connection } from "./classes/Connection";
 export { LogLevel } from "./classes/Logger";
+export { SSEResponse, StreamingResponse } from "./classes/StreamingResponse";
 export { ErrorStatusCodes, ErrorType, TypedError } from "./classes/TypedError";
 export type { KeryxConfig } from "./config";
 export type { SessionData } from "./initializers/session";

package/initializers/mcp.ts

@@ -10,6 +10,7 @@ import { api, logger } from "../api";
 import { MCP_RESPONSE_FORMAT } from "../classes/Action";
 import { Connection } from "../classes/Connection";
 import { Initializer } from "../classes/Initializer";
+import { StreamingResponse } from "../classes/StreamingResponse";
 import { ErrorType, TypedError } from "../classes/TypedError";
 import { config } from "../config";
 import pkg from "../package.json";
@@ -430,6 +431,35 @@ function createMcpServer(): McpServer {
             };
           }
 
+          // For streaming responses, consume the stream and accumulate into a single result.
+          // Send incremental chunks as MCP logging messages for real-time visibility.
+          if (response instanceof StreamingResponse) {
+            const reader = response.stream.getReader();
+            const decoder = new TextDecoder();
+            let accumulated = "";
+            try {
+              while (true) {
+                const { done, value } = await reader.read();
+                if (done) break;
+                const chunk = decoder.decode(value);
+                accumulated += chunk;
+                try {
+                  mcpServer.server.sendLoggingMessage({
+                    level: "info",
+                    data: chunk,
+                  });
+                } catch (_e) {
+                  // Logging message delivery is best-effort
+                }
+              }
+            } finally {
+              response.onClose?.();
+            }
+            return {
+              content: [{ type: "text" as const, text: accumulated }],
+            };
+          }
+
           const format = action.mcp?.responseFormat ?? MCP_RESPONSE_FORMAT.JSON;
           const text =
             format === MCP_RESPONSE_FORMAT.MARKDOWN

package/package.json

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

package/servers/web.ts

@@ -7,6 +7,7 @@ import { api, logger } from "../api";
 import { type HTTP_METHOD } from "../classes/Action";
 import { Connection } from "../classes/Connection";
 import { Server } from "../classes/Server";
+import { StreamingResponse } from "../classes/StreamingResponse";
 import { ErrorStatusCodes, ErrorType, TypedError } from "../classes/TypedError";
 import { config } from "../config";
 import type { PubSubMessage } from "../initializers/pubsub";
@@ -170,6 +171,13 @@ export class WebServer extends Server<ReturnType<typeof Bun.serve>> {
       return; // upgrade the request to a WebSocket
 
     const response = await this.handleHttpRequest(req, server, ip, id);
+
+    // 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);
+      return response;
+    }
+
     return compressResponse(response, req);
   }
 
@@ -408,6 +416,22 @@ export class WebServer extends Server<ReturnType<typeof Bun.serve>> {
       req.url,
     );
 
+    // For streaming responses, defer connection cleanup until the stream closes
+    if (response instanceof StreamingResponse) {
+      response.onClose = () => {
+        connection.destroy();
+        api.observability.http.activeConnections.add(-1);
+      };
+
+      api.observability.http.requestsTotal.add(1, {
+        method: httpMethod,
+        route: actionName ?? "unknown",
+        status: "200",
+      });
+
+      return buildResponse(connection, response, 200, requestOrigin);
+    }
+
     connection.destroy();
     api.observability.http.activeConnections.add(-1);
 

package/util/oauthTemplates.ts

@@ -126,7 +126,7 @@ export function zodToFormFields(action: Action | undefined): FormField[] {
 
 /**
  * Pre-render an array of form fields into HTML strings.
- * This avoids Mustache conditionals inside HTML tags (which breaks Prettier).
+ * This avoids Mustache conditionals inside HTML tags (which breaks formatters).
  * @param fields - Array of {@link FormField} objects.
  * @param prefix - ID prefix for field elements (e.g., "signin" or "signup").
  * @returns HTML string with label + input pairs.

package/util/webCompression.ts

@@ -74,6 +74,10 @@ export async function compressResponse(
   // No body to compress
   if (!response.body) return response;
 
+  // Never compress SSE streams
+  if (response.headers.get("Content-Type")?.includes("text/event-stream"))
+    return response;
+
   // Already compressed
   if (response.headers.get("Content-Encoding")) return response;
 

package/util/webResponse.ts

@@ -1,4 +1,5 @@
 import type { Connection } from "../classes/Connection";
+import { StreamingResponse } from "../classes/StreamingResponse";
 import { TypedError } from "../classes/TypedError";
 import { config } from "../config";
 import { buildCorsHeaders } from "../util/http";
@@ -77,6 +78,10 @@ export function buildResponse(
   status = 200,
   requestOrigin?: string,
 ) {
+  if (response instanceof StreamingResponse) {
+    return response.toResponse(buildHeaders(connection, requestOrigin));
+  }
+
   if (response instanceof Response) {
     return response;
   }

package/util/webSocket.ts

@@ -3,6 +3,7 @@ import { api, logger } from "../api";
 import type { ActionParams } from "../classes/Action";
 import { CHANNEL_NAME_PATTERN } from "../classes/Channel";
 import type { Connection } from "../classes/Connection";
+import { StreamingResponse } from "../classes/StreamingResponse";
 import { ErrorType, TypedError } from "../classes/TypedError";
 import { config } from "../config";
 import type {
@@ -40,6 +41,34 @@ export async function handleWebsocketAction(
         error: { ...buildErrorPayload(error) },
       }),
     );
+  } else if (response instanceof StreamingResponse) {
+    const reader = response.stream.getReader();
+    const decoder = new TextDecoder();
+    try {
+      while (true) {
+        const { done, value } = await reader.read();
+        if (done) break;
+        ws.send(
+          JSON.stringify({
+            messageId: formattedMessage.messageId,
+            streaming: true,
+            chunk: decoder.decode(value),
+          }),
+        );
+      }
+    } finally {
+      try {
+        ws.send(
+          JSON.stringify({
+            messageId: formattedMessage.messageId,
+            streaming: false,
+          }),
+        );
+      } catch (_e) {
+        // Connection may already be closed (e.g., client disconnected mid-stream)
+      }
+      response.onClose?.();
+    }
   } else {
     ws.send(
       JSON.stringify({