keryx 0.7.0 → 0.8.1

package/api.ts

@@ -18,7 +18,7 @@ export {
 } from "./classes/Channel";
 export { Connection } from "./classes/Connection";
 export { Initializer } from "./classes/Initializer";
-export { Logger } from "./classes/Logger";
+export { LogFormat, Logger } from "./classes/Logger";
 export { Server } from "./classes/Server";
 export type {
   FanOutJob,

package/classes/Connection.ts

@@ -7,6 +7,7 @@ import type { SessionData } from "../initializers/session";
 import type { RateLimitInfo } from "../middleware/rateLimit";
 import { isSecret } from "../util/zodMixins";
 import type { Action, ActionParams } from "./Action";
+import { LogFormat } from "./Logger";
 import { ErrorType, TypedError } from "./TypedError";
 
 /**
@@ -21,6 +22,8 @@ export class Connection<T extends Record<string, any> = Record<string, any>> {
   identifier: string;
   /** Unique connection ID (UUID by default). Used as the key in `api.connections`. */
   id: string;
+  /** Session ID used for Redis session lookup. Defaults to `id` but may differ for WebSocket connections where the session cookie differs from the connection map key. */
+  sessionId: string;
   /** The connection's session data, lazily loaded on first action invocation. */
   session?: SessionData<T>;
   /** Set of channel names this connection is currently subscribed to. */
@@ -41,16 +44,19 @@ export class Connection<T extends Record<string, any> = Record<string, any>> {
    * @param identifier - Human-readable identifier, typically the remote IP address.
    * @param id - Unique connection ID. Defaults to a random UUID.
    * @param rawConnection - The underlying transport handle (e.g., Bun `ServerWebSocket`).
+   * @param sessionId - Session ID for Redis session lookup. Defaults to `id`. Use a different value when the connection map key should differ from the session cookie (e.g., WebSocket connections).
    */
   constructor(
     type: string,
     identifier: string,
     id = randomUUID() as string,
     rawConnection: any = undefined,
+    sessionId?: string,
   ) {
     this.type = type;
     this.identifier = identifier;
     this.id = id;
+    this.sessionId = sessionId ?? id;
     this.sessionLoaded = false;
     this.subscriptions = new Set();
     this.rawConnection = rawConnection;
@@ -152,35 +158,28 @@ export class Connection<T extends Record<string, any> = Record<string, any>> {
             });
     }
 
-    // Note: we want the params object to remain on the same line as the message, so we stringify
-    const sanitizedParams = sanitizeParams(params, action);
-    const loggingParams = config.logger.colorize
-      ? colors.gray(JSON.stringify(sanitizedParams))
-      : JSON.stringify(sanitizedParams);
-
-    const statusMessage = `[ACTION:${this.type.toUpperCase()}:${loggerResponsePrefix}]`;
-    const messagePrefix = config.logger.colorize
-      ? loggerResponsePrefix === "OK"
-        ? colors.bgBlue(statusMessage)
-        : colors.bgMagenta(statusMessage)
-      : statusMessage;
-
     const duration = new Date().getTime() - reqStartTime;
 
-    const errorStack =
-      error && error.stack
-        ? config.logger.colorize
-          ? "\r\n" + colors.gray(error.stack)
-          : "\r\n" + error.stack
-        : "";
-
-    const correlationIdTag = this.correlationId
-      ? ` [cor:${this.correlationId}]`
-      : "";
+    api.observability.action.executionsTotal.add(1, {
+      action: actionName ?? "unknown",
+      status: loggerResponsePrefix === "OK" ? "success" : "error",
+    });
+    api.observability.action.duration.record(duration, {
+      action: actionName ?? "unknown",
+    });
 
-    logger.info(
-      `${messagePrefix} ${actionName} (${duration}ms) ${method.length > 0 ? `[${method}]` : ""} ${this.identifier}${url.length > 0 ? `(${url})` : ""}${correlationIdTag} ${error ? error : ""} ${loggingParams} ${errorStack}`,
-    );
+    logAction({
+      actionName,
+      connectionType: this.type,
+      status: loggerResponsePrefix,
+      duration,
+      params: sanitizeParams(params, action),
+      method,
+      url,
+      identifier: this.identifier,
+      correlationId: this.correlationId,
+      error,
+    });
 
     return { response, error };
   }
@@ -334,6 +333,66 @@ export class Connection<T extends Record<string, any> = Record<string, any>> {
   }
 }
 
+function logAction(opts: {
+  actionName: string | undefined;
+  connectionType: string;
+  status: "OK" | "ERROR";
+  duration: number;
+  params: Record<string, any>;
+  method: string;
+  url: string;
+  identifier: string;
+  correlationId: string | undefined;
+  error: TypedError | undefined;
+}) {
+  if (config.logger.format === LogFormat.json) {
+    const data: Record<string, any> = {
+      action: opts.actionName,
+      connectionType: opts.connectionType,
+      status: opts.status,
+      duration: opts.duration,
+      params: opts.params,
+    };
+    if (opts.method) data.method = opts.method;
+    if (opts.url) data.url = opts.url;
+    if (opts.identifier) data.identifier = opts.identifier;
+    if (opts.correlationId) data.correlationId = opts.correlationId;
+    if (opts.error) {
+      data.error = opts.error.message;
+      data.errorType = opts.error.type;
+      if (opts.error.stack) data.errorStack = opts.error.stack;
+    }
+
+    logger.info(`action: ${opts.actionName}`, data);
+  } else {
+    const loggingParams = config.logger.colorize
+      ? colors.gray(JSON.stringify(opts.params))
+      : JSON.stringify(opts.params);
+
+    const statusMessage = `[ACTION:${opts.connectionType.toUpperCase()}:${opts.status}]`;
+    const messagePrefix = config.logger.colorize
+      ? opts.status === "OK"
+        ? colors.bgBlue(statusMessage)
+        : colors.bgMagenta(statusMessage)
+      : statusMessage;
+
+    const errorStack =
+      opts.error && opts.error.stack
+        ? config.logger.colorize
+          ? "\r\n" + colors.gray(opts.error.stack)
+          : "\r\n" + opts.error.stack
+        : "";
+
+    const correlationIdTag = opts.correlationId
+      ? ` [cor:${opts.correlationId}]`
+      : "";
+
+    logger.info(
+      `${messagePrefix} ${opts.actionName} (${opts.duration}ms) ${opts.method.length > 0 ? `[${opts.method}]` : ""} ${opts.identifier}${opts.url.length > 0 ? `(${opts.url})` : ""}${correlationIdTag} ${opts.error ? opts.error : ""} ${loggingParams} ${errorStack}`,
+    );
+  }
+}
+
 const REDACTED = "[[secret]]" as const;
 
 const sanitizeParams = (params: FormData, action: Action | undefined) => {

package/classes/Logger.ts

@@ -11,22 +11,30 @@ export enum LogLevel {
   "fatal" = "fatal",
 }
 
+export enum LogFormat {
+  "text" = "text",
+  "json" = "json",
+}
+
 /**
- * The Logger Class.  I write to stdout or stderr, and can be colorized.
+ * The Logger Class. Writes to stdout/stderr in either human-readable text format
+ * (with optional ANSI colors) or structured NDJSON format for log aggregation systems.
  */
 export class Logger {
   /** Minimum log level to output. Messages below this level are silently dropped. */
   level: LogLevel;
-  /** Whether to apply ANSI color codes to the output. */
+  /** Whether to apply ANSI color codes to the output (text format only). */
   colorize: boolean;
   /** Whether to prepend an ISO-8601 timestamp to each log line. */
   includeTimestamps: boolean;
-  /** Indentation spaces used when JSON-stringifying the optional object argument. */
+  /** Indentation spaces used when JSON-stringifying the optional data argument in text mode. */
   jSONObjectParsePadding: number;
   /** When `true`, all logging is suppressed (used by CLI mode). */
   quiet: boolean;
   /** The output function — defaults to `console.log`. Override for custom transports. */
   outputStream: typeof console.log;
+  /** Output format: `"text"` for human-readable colored output, `"json"` for structured NDJSON. */
+  format: LogFormat;
 
   constructor(config: typeof configLogger) {
     this.level = config.level;
@@ -35,17 +43,23 @@ export class Logger {
     this.jSONObjectParsePadding = 4;
     this.quiet = false;
     this.outputStream = console.log;
+    this.format = config.format;
   }
 
   /**
    * Core logging method. Formats and writes a log line to `outputStream` if the given
-   * level meets the minimum threshold. Optionally includes a timestamp and pretty-printed object.
+   * level meets the minimum threshold.
+   *
+   * In text mode, outputs a human-readable string with optional timestamp, colors, and
+   * pretty-printed data object. In JSON mode, outputs a single NDJSON line with structured
+   * fields including `timestamp`, `level`, `message`, `pid`, and any fields from `data`.
    *
    * @param level - The severity level of this log entry.
    * @param message - The log message string.
-   * @param object - An optional object to JSON-stringify and append to the log line.
+   * @param data - Optional structured data to include. In text mode, JSON-stringified and
+   *   appended to the log line. In JSON mode, merged into the output object.
    */
-  log(level: LogLevel, message: string, object?: any) {
+  log(level: LogLevel, message: string, data?: any) {
     if (this.quiet) return;
 
     if (
@@ -55,84 +69,111 @@ export class Logger {
       return;
     }
 
-    let timestamp = this.includeTimestamps ? `${new Date().toISOString()}` : "";
-    if (this.colorize && timestamp.length > 0) {
-      timestamp = colors.gray(timestamp);
-    }
-
-    let formattedLevel = `[${level}]`;
-    if (this.colorize) {
-      formattedLevel = this.colorFromLopLevel(level)(formattedLevel);
-    }
-
-    let prettyObject =
-      object !== undefined
-        ? JSON.stringify(object, null, this.jSONObjectParsePadding)
-        : "";
-    if (this.colorize && prettyObject.length > 0) {
-      prettyObject = colors.cyan(prettyObject);
+    if (this.format === LogFormat.json) {
+      this.logJson(level, message, data);
+    } else {
+      this.logText(level, message, data);
     }
-
-    this.outputStream(
-      `${timestamp} ${formattedLevel} ${message} ${prettyObject}`,
-    );
   }
 
   /**
    * Log a trace message.
    * @param message - The message to log.
-   * @param object - The object to log.
+   * @param data - Optional structured data to include in the log entry.
    */
-  trace(message: string, object?: any) {
-    this.log(LogLevel.trace, message, object);
+  trace(message: string, data?: any) {
+    this.log(LogLevel.trace, message, data);
   }
 
   /**
    * Log a debug message.
    * @param message - The message to log.
-   * @param object - The object to log.
+   * @param data - Optional structured data to include in the log entry.
    */
-  debug(message: string, object?: any) {
-    this.log(LogLevel.debug, message, object);
+  debug(message: string, data?: any) {
+    this.log(LogLevel.debug, message, data);
   }
 
   /**
    * Log an info message.
    * @param message - The message to log.
-   * @param object - The object to log.
+   * @param data - Optional structured data to include in the log entry.
    */
-  info(message: string, object?: any) {
-    this.log(LogLevel.info, message, object);
+  info(message: string, data?: any) {
+    this.log(LogLevel.info, message, data);
   }
 
   /**
    * Log a warning.
    * @param message - The message to log.
-   * @param object - The object to log.
+   * @param data - Optional structured data to include in the log entry.
    */
-  warn(message: string, object?: any) {
-    this.log(LogLevel.warn, message, object);
+  warn(message: string, data?: any) {
+    this.log(LogLevel.warn, message, data);
   }
 
   /**
    * Log an error.
    * @param message - The message to log.
-   * @param object - The object to log.
+   * @param data - Optional structured data to include in the log entry.
    */
-  error(message: string, object?: any) {
-    this.log(LogLevel.error, message, object);
+  error(message: string, data?: any) {
+    this.log(LogLevel.error, message, data);
   }
 
   /**
    * Log a fatal error.
    * @param message - The message to log.
-   * @param object - The object to log.
+   * @param data - Optional structured data to include in the log entry.
    */
-  fatal(message: string, object?: any) {
-    this.log(LogLevel.fatal, message, object);
+  fatal(message: string, data?: any) {
+    this.log(LogLevel.fatal, message, data);
+  }
+
+  private logText(level: LogLevel, message: string, data?: any) {
+    let timestamp = this.includeTimestamps ? `${new Date().toISOString()}` : "";
+    if (this.colorize && timestamp.length > 0) {
+      timestamp = colors.gray(timestamp);
+    }
+
+    let formattedLevel = `[${level}]`;
+    if (this.colorize) {
+      formattedLevel = this.colorFromLogLevel(level)(formattedLevel);
+    }
+
+    let prettyObject =
+      data !== undefined
+        ? JSON.stringify(data, null, this.jSONObjectParsePadding)
+        : "";
+    if (this.colorize && prettyObject.length > 0) {
+      prettyObject = colors.cyan(prettyObject);
+    }
+
+    this.outputStream(
+      `${timestamp} ${formattedLevel} ${message} ${prettyObject}`,
+    );
+  }
+
+  private logJson(level: LogLevel, message: string, data?: any) {
+    const entry: Record<string, any> = {
+      timestamp: new Date().toISOString(),
+      level,
+      message,
+      pid: process.pid,
+    };
+
+    if (data !== undefined && data !== null) {
+      if (typeof data === "object" && !Array.isArray(data)) {
+        Object.assign(entry, data);
+      } else {
+        entry.data = data;
+      }
+    }
+
+    this.outputStream(JSON.stringify(entry));
   }
 
-  private colorFromLopLevel(level: LogLevel) {
+  private colorFromLogLevel(level: LogLevel) {
     switch (level) {
       case LogLevel.trace:
         return colors.gray;

package/config/index.ts

@@ -2,6 +2,7 @@ import { configActions } from "./actions";
 import { configChannels } from "./channels";
 import { configDatabase } from "./database";
 import { configLogger } from "./logger";
+import { configObservability } from "./observability";
 import { configProcess } from "./process";
 import { configRateLimit } from "./rateLimit";
 import { configRedis } from "./redis";
@@ -17,6 +18,7 @@ export const config = {
   process: configProcess,
   logger: configLogger,
   database: configDatabase,
+  observability: configObservability,
   redis: configRedis,
   rateLimit: configRateLimit,
   session: configSession,

package/config/logger.ts

@@ -1,8 +1,9 @@
-import { LogLevel } from "../classes/Logger";
+import { LogFormat, LogLevel } from "../classes/Logger";
 import { loadFromEnvIfSet } from "../util/config";
 
 export const configLogger = {
   level: await loadFromEnvIfSet<LogLevel>("LOG_LEVEL", LogLevel.info),
   includeTimestamps: await loadFromEnvIfSet("LOG_INCLUDE_TIMESTAMPS", true),
   colorize: await loadFromEnvIfSet("LOG_COLORIZE", true),
+  format: await loadFromEnvIfSet<LogFormat>("LOG_FORMAT", LogFormat.text),
 };

package/config/observability.ts

@@ -0,0 +1,7 @@
+import { loadFromEnvIfSet } from "../util/config";
+
+export const configObservability = {
+  enabled: await loadFromEnvIfSet("OTEL_METRICS_ENABLED", false),
+  metricsRoute: await loadFromEnvIfSet("OTEL_METRICS_ROUTE", "/metrics"),
+  serviceName: await loadFromEnvIfSet("OTEL_SERVICE_NAME", ""),
+};

package/config/server/web.ts

@@ -21,30 +21,25 @@ export const configServerWeb = {
     "WEB_SERVER_ALLOWED_HEADERS",
     "Content-Type",
   ),
-  staticFilesEnabled: await loadFromEnvIfSet("WEB_SERVER_STATIC_ENABLED", true),
-  staticFilesDirectory: await loadFromEnvIfSet(
-    "WEB_SERVER_STATIC_DIRECTORY",
-    "assets",
-  ),
-  staticFilesRoute: await loadFromEnvIfSet("WEB_SERVER_STATIC_ROUTE", "/"),
-  staticFilesCacheControl: await loadFromEnvIfSet(
-    "WEB_SERVER_STATIC_CACHE_CONTROL",
-    "public, max-age=3600",
-  ),
-  staticFilesEtag: await loadFromEnvIfSet("WEB_SERVER_STATIC_ETAG", true),
-  websocketMaxPayloadSize: await loadFromEnvIfSet(
-    "WS_MAX_PAYLOAD_SIZE",
-    65_536,
-  ),
-  websocketMaxMessagesPerSecond: await loadFromEnvIfSet(
-    "WS_MAX_MESSAGES_PER_SECOND",
-    20,
-  ),
-  websocketMaxSubscriptions: await loadFromEnvIfSet(
-    "WS_MAX_SUBSCRIPTIONS",
-    100,
-  ),
-  websocketDrainTimeout: await loadFromEnvIfSet("WS_DRAIN_TIMEOUT", 5000),
+  staticFiles: {
+    enabled: await loadFromEnvIfSet("WEB_SERVER_STATIC_ENABLED", true),
+    directory: await loadFromEnvIfSet("WEB_SERVER_STATIC_DIRECTORY", "assets"),
+    route: await loadFromEnvIfSet("WEB_SERVER_STATIC_ROUTE", "/"),
+    cacheControl: await loadFromEnvIfSet(
+      "WEB_SERVER_STATIC_CACHE_CONTROL",
+      "public, max-age=3600",
+    ),
+    etag: await loadFromEnvIfSet("WEB_SERVER_STATIC_ETAG", true),
+  },
+  websocket: {
+    maxPayloadSize: await loadFromEnvIfSet("WS_MAX_PAYLOAD_SIZE", 65_536),
+    maxMessagesPerSecond: await loadFromEnvIfSet(
+      "WS_MAX_MESSAGES_PER_SECOND",
+      20,
+    ),
+    maxSubscriptions: await loadFromEnvIfSet("WS_MAX_SUBSCRIPTIONS", 100),
+    drainTimeout: await loadFromEnvIfSet("WS_DRAIN_TIMEOUT", 5000),
+  },
   includeStackInErrors: await loadFromEnvIfSet(
     "WEB_SERVER_INCLUDE_STACK_IN_ERRORS",
     (Bun.env.NODE_ENV ?? "development") !== "production",
@@ -71,6 +66,11 @@ export const configServerWeb = {
       "strict-origin-when-cross-origin",
     ),
   } as Record<string, string>,
+  compression: {
+    enabled: await loadFromEnvIfSet("WEB_COMPRESSION_ENABLED", true),
+    threshold: await loadFromEnvIfSet("WEB_COMPRESSION_THRESHOLD", 1024),
+    encodings: ["br", "gzip"] as ("br" | "gzip")[],
+  },
   correlationId: {
     header: await loadFromEnvIfSet("WEB_CORRELATION_ID_HEADER", "X-Request-Id"),
     trustProxy: await loadFromEnvIfSet("WEB_CORRELATION_ID_TRUST_PROXY", false),

package/index.ts

@@ -7,6 +7,7 @@ import "./initializers/connections";
 import "./initializers/db";
 import "./initializers/mcp";
 import "./initializers/oauth";
+import "./initializers/observability";
 import "./initializers/process";
 import "./initializers/pubsub";
 import "./initializers/redis";

package/initializers/actionts.ts

@@ -93,6 +93,10 @@ export class Actions extends Initializer {
       });
     }
     queue = queue ?? action?.task?.queue ?? DEFAULT_QUEUE;
+    api.observability.task.enqueuedTotal.add(1, {
+      action: actionName,
+      queue,
+    });
     return api.resque.queue.enqueue(queue, actionName, [inputs]);
   };