keryx 0.0.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024-present Evan Tahler
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/actions/status.ts

@@ -0,0 +1,25 @@
+import { z } from "zod";
+import { Action, api } from "../api";
+import { HTTP_METHOD } from "../classes/Action";
+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.";
+  inputs = z.object({});
+  web = { route: "/status", method: HTTP_METHOD.GET };
+
+  async run() {
+    const consumedMemoryMB =
+      Math.round((process.memoryUsage().heapUsed / 1024 / 1024) * 100) / 100;
+
+    return {
+      name: api.process.name,
+      pid: api.process.pid,
+      version: packageJSON.version,
+      uptime: new Date().getTime() - api.bootTime,
+      consumedMemoryMB,
+    };
+  }
+}

package/actions/swagger.ts

@@ -0,0 +1,170 @@
+import { z } from "zod";
+import { Action, api, config } from "../api";
+import { HTTP_METHOD } from "../classes/Action";
+import packageJSON from "../package.json";
+
+const SWAGGER_VERSION = "3.0.0";
+
+const errorResponseSchema = {
+  type: "object",
+  properties: {
+    error: { type: "string" },
+  },
+};
+
+const swaggerResponses = {
+  "200": {
+    description: "successful operation",
+    content: {
+      "application/json": {
+        schema: {},
+      },
+    },
+  },
+  "400": {
+    description: "Invalid input",
+    content: {
+      "application/json": {
+        schema: errorResponseSchema,
+      },
+    },
+  },
+  "404": {
+    description: "Not Found",
+    content: {
+      "application/json": {
+        schema: errorResponseSchema,
+      },
+    },
+  },
+  "422": {
+    description: "Missing or invalid params",
+    content: {
+      "application/json": {
+        schema: errorResponseSchema,
+      },
+    },
+  },
+  "500": {
+    description: "Server error",
+    content: {
+      "application/json": {
+        schema: errorResponseSchema,
+      },
+    },
+  },
+};
+
+export class Swagger implements Action {
+  name = "swagger";
+  description =
+    "Returns the full API documentation as an OpenAPI 3.0.0 JSON document. Includes all available endpoints with their routes, methods, request schemas, response schemas, and parameter descriptions. Does not require authentication.";
+  web = { route: "/swagger", method: HTTP_METHOD.GET };
+
+  async run() {
+    const paths: Record<string, any> = {};
+    const components: { schemas: Record<string, any> } = { schemas: {} };
+
+    for (const action of api.actions.actions) {
+      if (!action.web?.route || !action.web?.method) continue;
+      // Skip RegExp routes for swagger documentation
+      if (typeof action.web.route !== "string") continue;
+      // Convert :param format to OpenAPI {param} format
+      const path = action.web.route.replace(
+        /:\w+/g,
+        (match: string) => `{${match.slice(1)}}`,
+      );
+      const method = action.web.method.toLowerCase();
+      const tag = action.name.split(":")[0];
+      const summary = action.description || action.name;
+
+      // Extract path parameters from the original route
+      const pathParams: any[] = [];
+      const pathParamMatches = action.web.route.match(/:\w+/g) || [];
+      for (const paramMatch of pathParamMatches) {
+        const paramName = paramMatch.slice(1); // Remove the colon
+        pathParams.push({
+          name: paramName,
+          in: "path",
+          required: true,
+          schema: { type: "string" },
+          description: `The ${paramName} parameter`,
+        });
+      }
+
+      // Build requestBody if Zod inputs exist and method supports body
+      let requestBody: any = undefined;
+      if (
+        action.inputs &&
+        typeof action.inputs.parse === "function" &&
+        method !== "get" &&
+        method !== "head"
+      ) {
+        const zodSchema = action.inputs;
+        const schemaName = `${action.name.replace(/:/g, "_")}_Request`;
+        // Use io: "input" to get the input schema (before transforms)
+        // Use unrepresentable: "any" to handle refinements, async transforms, etc.
+        const jsonSchema = z.toJSONSchema(zodSchema, {
+          io: "input",
+          unrepresentable: "any",
+        });
+        // Remove $schema from component schemas (not needed in OpenAPI)
+        const { $schema, ...schemaWithout$schema } = jsonSchema as any;
+        components.schemas[schemaName] = schemaWithout$schema;
+        requestBody = {
+          required: true,
+          content: {
+            "application/json": {
+              schema: { $ref: `#/components/schemas/${schemaName}` },
+            },
+          },
+        };
+      }
+
+      // 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;
+        responses["200"] = {
+          description: "successful operation",
+          content: {
+            "application/json": {
+              schema: { $ref: `#/components/schemas/${schemaName}` },
+            },
+          },
+        };
+      }
+
+      // Add path/method
+      if (!paths[path]) paths[path] = {};
+      paths[path][method] = {
+        summary,
+        ...(pathParams.length > 0 ? { parameters: pathParams } : {}),
+        ...(requestBody ? { requestBody } : {}),
+        responses,
+        tags: [tag],
+      };
+    }
+
+    const document = {
+      openapi: SWAGGER_VERSION,
+      info: {
+        version: packageJSON.version,
+        title: packageJSON.name,
+        license: { name: packageJSON.license },
+        description: packageJSON.description,
+      },
+      servers: [
+        {
+          url: config.server.web.applicationUrl + config.server.web.apiRoute,
+          description: packageJSON.description,
+        },
+      ],
+      paths,
+      components,
+    };
+    return document;
+  }
+}

package/api.ts

@@ -0,0 +1,45 @@
+import { API } from "./classes/API";
+import type { Logger } from "./classes/Logger";
+import { config as Config } from "./config";
+
+export {
+  Action,
+  type ActionConstructorInputs,
+  type ActionParams,
+  type ActionResponse,
+  type McpActionConfig,
+  type OAuthActionResponse,
+} from "./classes/Action";
+export { API, RUN_MODE } from "./classes/API";
+export {
+  Channel,
+  type ChannelConstructorInputs,
+  type ChannelMiddleware,
+} from "./classes/Channel";
+export { Connection } from "./classes/Connection";
+export { Initializer } from "./classes/Initializer";
+export { Logger } from "./classes/Logger";
+export { Server } from "./classes/Server";
+export type {
+  FanOutJob,
+  FanOutOptions,
+  FanOutResult,
+  FanOutStatus,
+} from "./initializers/actionts";
+
+declare namespace globalThis {
+  let api: API;
+  let logger: Logger;
+  let config: typeof Config;
+}
+
+if (!globalThis.api) {
+  // @ts-ignore — augmented API properties (db, redis, etc.) are set later by initializers at runtime
+  globalThis.api = new API();
+  globalThis.logger = globalThis.api.logger;
+  globalThis.config = Config;
+}
+
+export const api = globalThis.api;
+export const logger = globalThis.logger;
+export const config = globalThis.config;

package/classes/API.ts

@@ -0,0 +1,168 @@
+import path from "path";
+import { config } from "../config";
+import { globLoader } from "../util/glob";
+import type { Initializer, InitializerSortKeys } from "./Initializer";
+import { Logger } from "./Logger";
+import { ErrorType, TypedError } from "./TypedError";
+
+export enum RUN_MODE {
+  CLI = "cli",
+  SERVER = "server",
+}
+
+let flapPreventer = false;
+
+export class API {
+  rootDir: string;
+  packageDir: string;
+  initialized: boolean;
+  started: boolean;
+  stopped: boolean;
+  bootTime: number;
+  logger: Logger;
+  runMode!: RUN_MODE;
+  initializers: Initializer[];
+
+  // allow arbitrary properties to be set on the API, to be added and typed later
+  [key: string]: any;
+
+  constructor() {
+    this.bootTime = new Date().getTime();
+    this.packageDir = path.join(import.meta.path, "..", "..");
+    this.rootDir = this.packageDir;
+    this.logger = new Logger(config.logger);
+
+    this.initialized = false;
+    this.started = false;
+    this.stopped = false;
+
+    this.initializers = [];
+  }
+
+  async initialize() {
+    this.logger.warn("--- 🔄  Initializing process ---");
+    this.initialized = false;
+
+    await this.findInitializers();
+    this.sortInitializers("loadPriority");
+
+    for (const initializer of this.initializers) {
+      try {
+        this.logger.debug(`Initializing initializer ${initializer.name}`);
+        const response = await initializer.initialize?.();
+        if (response) this[initializer.name] = response;
+        this.logger.debug(`Initialized initializer ${initializer.name}`);
+      } catch (e) {
+        throw new TypedError({
+          message: `${e}`,
+          type: ErrorType.SERVER_INITIALIZATION,
+          originalError: e,
+        });
+      }
+    }
+
+    this.initialized = true;
+    this.logger.warn("--- 🔄  Initializing complete ---");
+  }
+
+  async start(runMode: RUN_MODE = RUN_MODE.SERVER) {
+    this.stopped = false;
+    this.started = false;
+    this.runMode = runMode;
+    if (!this.initialized) await this.initialize();
+
+    this.logger.warn("--- 🔼  Starting process ---");
+
+    this.sortInitializers("startPriority");
+
+    for (const initializer of this.initializers) {
+      if (!initializer.runModes.includes(runMode)) {
+        this.logger.debug(
+          `Not starting initializer ${initializer.name} in ${runMode} mode`,
+        );
+        continue;
+      }
+
+      try {
+        this.logger.debug(`Starting initializer ${initializer.name}`);
+        await initializer.start?.();
+        this.logger.debug(`Started initializer ${initializer.name}`);
+      } catch (e) {
+        throw new TypedError({
+          message: `${e}`,
+          type: ErrorType.SERVER_START,
+          originalError: e,
+        });
+      }
+    }
+
+    this.started = true;
+    this.logger.warn("--- 🔼  Starting complete ---");
+  }
+
+  async stop() {
+    if (this.stopped) {
+      this.logger.warn("API is already stopped");
+      return;
+    }
+
+    this.logger.warn("--- 🔽  Stopping process ---");
+
+    this.sortInitializers("stopPriority");
+
+    for (const initializer of this.initializers) {
+      try {
+        this.logger.debug(`Stopping initializer ${initializer.name}`);
+        await initializer.stop?.();
+        this.logger.debug(`Stopped initializer ${initializer.name}`);
+      } catch (e) {
+        throw new TypedError({
+          message: `${e}`,
+          type: ErrorType.SERVER_STOP,
+          originalError: e,
+        });
+      }
+    }
+
+    this.stopped = true;
+    this.started = false;
+    this.logger.warn("--- 🔽  Stopping complete ---");
+  }
+
+  async restart() {
+    if (flapPreventer) return;
+
+    flapPreventer = true;
+    await this.stop();
+    await this.start();
+    flapPreventer = false;
+  }
+
+  private async findInitializers() {
+    // Load framework initializers from the package directory
+    const frameworkInitializers = await globLoader<Initializer>(
+      path.join(this.packageDir, "initializers"),
+    );
+    for (const i of frameworkInitializers) {
+      this.initializers.push(i);
+    }
+
+    // Load user project initializers (if rootDir differs from packageDir)
+    if (this.rootDir !== this.packageDir) {
+      try {
+        const userInitializers = await globLoader<Initializer>(
+          path.join(this.rootDir, "initializers"),
+        );
+        for (const i of userInitializers) {
+          this.initializers.push(i);
+        }
+      } catch {
+        // user project may not have initializers, that's fine
+      }
+    }
+  }
+
+  private sortInitializers(key: InitializerSortKeys) {
+    this.initializers.sort((a, b) => a[key] - b[key]);
+  }
+}

package/classes/Action.ts

@@ -0,0 +1,128 @@
+import { z } from "zod";
+import type { Connection } from "./Connection";
+import type { TypedError } from "./TypedError";
+
+export enum HTTP_METHOD {
+  "GET" = "GET",
+  "POST" = "POST",
+  "PUT" = "PUT",
+  "DELETE" = "DELETE",
+  "PATCH" = "PATCH",
+  "OPTIONS" = "OPTIONS",
+}
+
+export const DEFAULT_QUEUE = "default";
+
+export type OAuthActionResponse = {
+  user: { id: number };
+};
+
+export type McpActionConfig = {
+  /** Expose this action as an MCP tool (default true) */
+  enabled?: boolean;
+  /** Tag as the OAuth login action */
+  isLoginAction?: boolean;
+  /** Tag as the OAuth signup action */
+  isSignupAction?: boolean;
+};
+
+export type ActionConstructorInputs = {
+  /** Unique action name (also used for default routes, etc.) */
+  name: string;
+
+  /** Human-friendly description (defaults to `An Action: ${name}`) */
+  description?: string;
+
+  /** Zod schema used to validate/coerce inputs (and for type inference) */
+  inputs?: z.ZodType<any>;
+
+  /** Middleware hooks to run before/after `run()` */
+  middleware?: ActionMiddleware[];
+
+  /** Expose this action via the MCP server (defaults to `{ enabled: true }`) */
+  mcp?: McpActionConfig;
+
+  /** Expose this action via HTTP (defaults: route `/${name}`, method `GET`) */
+  web?: {
+    /** HTTP route pattern (string with `:params` or a `RegExp`) */
+    route?: RegExp | string;
+    /** HTTP method to bind the route to */
+    method?: HTTP_METHOD;
+  };
+
+  /** Configure this action as a background task/job */
+  task?: {
+    /** Optional recurring frequency in milliseconds */
+    frequency?: number;
+    /** Queue name to enqueue jobs onto (defaults to `"default"`) */
+    queue: string;
+  };
+};
+
+export type ActionMiddlewareResponse = {
+  updatedParams?: ActionParams<Action>;
+  updatedResponse?: any;
+};
+
+export type ActionMiddleware = {
+  runBefore?: (
+    params: ActionParams<Action>,
+    connection: Connection,
+  ) => Promise<ActionMiddlewareResponse | void>;
+  runAfter?: (
+    params: ActionParams<Action>,
+    connection: Connection,
+  ) => Promise<ActionMiddlewareResponse | void>;
+};
+
+export abstract class Action {
+  name: string;
+  description?: string;
+  inputs?: z.ZodType<any>;
+  middleware?: ActionMiddleware[];
+  mcp?: McpActionConfig;
+  web?: {
+    route: RegExp | string;
+    method: HTTP_METHOD;
+  };
+  task?: {
+    frequency?: number;
+    queue: string;
+  };
+
+  constructor(args: ActionConstructorInputs) {
+    this.name = args.name;
+    this.description = args.description ?? `An Action: ${this.name}`;
+    this.inputs = args.inputs;
+    this.middleware = args.middleware ?? [];
+    this.mcp = { enabled: true, ...args.mcp };
+    this.web = {
+      route: args.web?.route ?? `/${this.name}`,
+      method: args.web?.method ?? HTTP_METHOD.GET,
+    };
+    this.task = {
+      frequency: args.task?.frequency,
+      queue: args.task?.queue ?? DEFAULT_QUEUE,
+    };
+  }
+
+  /**
+   * The main "do something" method for this 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`
+   * @throws {TypedError} All errors thrown should be TypedError instances
+   */
+  abstract run(
+    params: ActionParams<Action>,
+    connection?: Connection,
+  ): Promise<any>;
+}
+
+export type ActionParams<A extends Action> =
+  A["inputs"] extends z.ZodType<any>
+    ? z.infer<A["inputs"]>
+    : Record<string, unknown>;
+
+export type ActionResponse<A extends Action> = Awaited<ReturnType<A["run"]>> &
+  Partial<{ error?: TypedError }>;

package/classes/Channel.ts

@@ -0,0 +1,81 @@
+import type { Connection } from "./Connection";
+
+export const CHANNEL_NAME_PATTERN = /^[a-zA-Z0-9:._-]{1,200}$/;
+
+export type ChannelMiddlewareResponse = void;
+
+export type ChannelMiddleware = {
+  /**
+   * Runs before a connection is allowed to subscribe to a channel.
+   * Throw a TypedError to deny subscription.
+   */
+  runBefore?: (
+    channel: string,
+    connection: Connection,
+  ) => Promise<ChannelMiddlewareResponse>;
+
+  /**
+   * Runs after a connection unsubscribes from a channel.
+   * Useful for cleanup or presence tracking.
+   */
+  runAfter?: (
+    channel: string,
+    connection: Connection,
+  ) => Promise<ChannelMiddlewareResponse>;
+};
+
+export type ChannelConstructorInputs = {
+  /**
+   * The name or pattern of the channel.
+   * Can be a string for exact match or a RegExp for pattern matching.
+   * Examples:
+   * - "messages" - matches only "messages"
+   * - /^room:.*$/ - matches "room:123", "room:abc", etc.
+   */
+  name: string | RegExp;
+  description?: string;
+  middleware?: ChannelMiddleware[];
+};
+
+export abstract class Channel {
+  name: string | RegExp;
+  description?: string;
+  middleware: ChannelMiddleware[];
+
+  constructor(args: ChannelConstructorInputs) {
+    this.name = args.name;
+    this.description = args.description ?? `A Channel: ${this.name}`;
+    this.middleware = args.middleware ?? [];
+  }
+
+  /**
+   * Check if this channel definition matches the requested channel name.
+   */
+  matches(channelName: string): boolean {
+    if (typeof this.name === "string") {
+      return this.name === channelName;
+    }
+    return this.name.test(channelName);
+  }
+
+  /**
+   * Optional authorization method that can be overridden for custom logic.
+   * Called after middleware runs, provides access to the parsed channel name.
+   * Throw a TypedError to deny subscription.
+   */
+  async authorize(
+    _channelName: string,
+    _connection: Connection,
+  ): Promise<void> {
+    // Default implementation allows all subscriptions
+  }
+
+  /**
+   * Returns the presence identifier for a connection in this channel.
+   * Override to use a custom key (e.g. user ID from session).
+   * Defaults to `connection.id`.
+   */
+  async presenceKey(connection: Connection): Promise<string> {
+    return connection.id;
+  }
+}