@donkeylabs/server 0.1.0

package/src/core/sse.ts

@@ -0,0 +1,210 @@
+// Core SSE Service
+// Server-Sent Events for server→client push
+
+export interface SSEClient {
+  id: string;
+  channels: Set<string>;
+  controller: ReadableStreamDefaultController<Uint8Array>;
+  createdAt: Date;
+  lastEventId?: string;
+}
+
+export interface SSEConfig {
+  heartbeatInterval?: number; // ms, default 30000 (30s)
+  retryInterval?: number; // ms suggested to client, default 3000
+}
+
+export interface SSE {
+  addClient(options?: { lastEventId?: string }): { client: SSEClient; response: Response };
+  removeClient(clientId: string): void;
+  getClient(clientId: string): SSEClient | undefined;
+  subscribe(clientId: string, channel: string): boolean;
+  unsubscribe(clientId: string, channel: string): boolean;
+  broadcast(channel: string, event: string, data: any, id?: string): void;
+  broadcastAll(event: string, data: any, id?: string): void;
+  sendTo(clientId: string, event: string, data: any, id?: string): boolean;
+  getClients(): SSEClient[];
+  getClientsByChannel(channel: string): SSEClient[];
+  shutdown(): void;
+}
+
+class SSEImpl implements SSE {
+  private clients = new Map<string, SSEClient>();
+  private heartbeatInterval: number;
+  private retryInterval: number;
+  private heartbeatTimer: ReturnType<typeof setInterval> | null = null;
+  private clientCounter = 0;
+  private encoder = new TextEncoder();
+
+  constructor(config: SSEConfig = {}) {
+    this.heartbeatInterval = config.heartbeatInterval ?? 30000;
+    this.retryInterval = config.retryInterval ?? 3000;
+
+    // Start heartbeat to keep connections alive
+    this.heartbeatTimer = setInterval(() => {
+      this.sendHeartbeat();
+    }, this.heartbeatInterval);
+  }
+
+  addClient(options: { lastEventId?: string } = {}): { client: SSEClient; response: Response } {
+    const id = `sse_${++this.clientCounter}_${Date.now()}`;
+
+    let clientController: ReadableStreamDefaultController<Uint8Array>;
+
+    const stream = new ReadableStream<Uint8Array>({
+      start: (controller) => {
+        clientController = controller;
+
+        // Send retry interval to client
+        const retryMsg = `retry: ${this.retryInterval}\n\n`;
+        controller.enqueue(this.encoder.encode(retryMsg));
+      },
+      cancel: () => {
+        this.removeClient(id);
+      },
+    });
+
+    const client: SSEClient = {
+      id,
+      channels: new Set(),
+      controller: clientController!,
+      createdAt: new Date(),
+      lastEventId: options.lastEventId,
+    };
+
+    this.clients.set(id, client);
+
+    const response = new Response(stream, {
+      headers: {
+        "Content-Type": "text/event-stream",
+        "Cache-Control": "no-cache",
+        "Connection": "keep-alive",
+        "X-SSE-Client-Id": id,
+      },
+    });
+
+    return { client, response };
+  }
+
+  removeClient(clientId: string): void {
+    const client = this.clients.get(clientId);
+    if (client) {
+      try {
+        client.controller.close();
+      } catch {
+        // Controller may already be closed
+      }
+      this.clients.delete(clientId);
+    }
+  }
+
+  getClient(clientId: string): SSEClient | undefined {
+    return this.clients.get(clientId);
+  }
+
+  subscribe(clientId: string, channel: string): boolean {
+    const client = this.clients.get(clientId);
+    if (!client) return false;
+    client.channels.add(channel);
+    return true;
+  }
+
+  unsubscribe(clientId: string, channel: string): boolean {
+    const client = this.clients.get(clientId);
+    if (!client) return false;
+    return client.channels.delete(channel);
+  }
+
+  broadcast(channel: string, event: string, data: any, id?: string): void {
+    for (const client of this.clients.values()) {
+      if (client.channels.has(channel)) {
+        this.sendEvent(client, event, data, id);
+      }
+    }
+  }
+
+  broadcastAll(event: string, data: any, id?: string): void {
+    for (const client of this.clients.values()) {
+      this.sendEvent(client, event, data, id);
+    }
+  }
+
+  sendTo(clientId: string, event: string, data: any, id?: string): boolean {
+    const client = this.clients.get(clientId);
+    if (!client) return false;
+    return this.sendEvent(client, event, data, id);
+  }
+
+  getClients(): SSEClient[] {
+    return Array.from(this.clients.values());
+  }
+
+  getClientsByChannel(channel: string): SSEClient[] {
+    return Array.from(this.clients.values()).filter(c => c.channels.has(channel));
+  }
+
+  shutdown(): void {
+    if (this.heartbeatTimer) {
+      clearInterval(this.heartbeatTimer);
+      this.heartbeatTimer = null;
+    }
+
+    // Close all client connections
+    for (const client of this.clients.values()) {
+      try {
+        client.controller.close();
+      } catch {
+        // Ignore errors during shutdown
+      }
+    }
+    this.clients.clear();
+  }
+
+  private sendEvent(client: SSEClient, event: string, data: any, id?: string): boolean {
+    try {
+      let message = "";
+
+      if (id) {
+        message += `id: ${id}\n`;
+      }
+
+      message += `event: ${event}\n`;
+
+      // Handle data - serialize if object
+      const dataStr = typeof data === "string" ? data : JSON.stringify(data);
+
+      // Split data by newlines for proper SSE format
+      for (const line of dataStr.split("\n")) {
+        message += `data: ${line}\n`;
+      }
+
+      message += "\n"; // End of message
+
+      client.controller.enqueue(this.encoder.encode(message));
+      return true;
+    } catch {
+      // Client may be disconnected
+      this.removeClient(client.id);
+      return false;
+    }
+  }
+
+  private sendHeartbeat(): void {
+    // Send comment as heartbeat to keep connections alive
+    const heartbeat = `: heartbeat ${Date.now()}\n\n`;
+    const encoded = this.encoder.encode(heartbeat);
+
+    for (const client of this.clients.values()) {
+      try {
+        client.controller.enqueue(encoded);
+      } catch {
+        // Client disconnected
+        this.removeClient(client.id);
+      }
+    }
+  }
+}
+
+export function createSSE(config?: SSEConfig): SSE {
+  return new SSEImpl(config);
+}

package/src/core.ts

@@ -0,0 +1,428 @@
+import type { Kysely } from "kysely";
+import { readdir } from "node:fs/promises";
+import { join } from "node:path";
+import type { z } from "zod";
+import type { Logger } from "./core/logger";
+import type { Cache } from "./core/cache";
+import type { Events } from "./core/events";
+import type { Cron } from "./core/cron";
+import type { Jobs } from "./core/jobs";
+import type { SSE } from "./core/sse";
+import type { RateLimiter } from "./core/rate-limiter";
+import type { Errors, CustomErrorRegistry } from "./core/errors";
+
+export interface PluginRegistry {}
+
+export interface ClientConfig {
+  credentials?: "include" | "same-origin" | "omit";
+}
+
+export type EventSchemas = Record<string, z.ZodType<any>>;
+
+export type Register<
+  Service = void,
+  Schema = {},
+  Handlers = {},
+  Dependencies extends readonly string[] = readonly [],
+  Middleware = {},
+  Config = void,
+  Events extends EventSchemas = {}
+> = {
+  service: Service;
+  schema: Schema;
+  handlers: Handlers;
+  _dependencies: Dependencies;
+  middleware: Middleware;
+  config: Config;
+  events: Events;
+};
+
+export interface PluginHandlerRegistry {}
+
+export interface PluginMiddlewareRegistry {}
+
+export interface CoreServices {
+  db: Kysely<any>;
+  config: Record<string, any>;
+  logger: Logger;
+  cache: Cache;
+  events: Events;
+  cron: Cron;
+  jobs: Jobs;
+  sse: SSE;
+  rateLimiter: RateLimiter;
+  errors: Errors;
+}
+
+export class PluginContext<Deps = any, Schema = any, Config = void> {
+  constructor(
+    public readonly core: CoreServices,
+    public readonly deps: Deps,
+    public readonly config: Config
+  ) {}
+
+  get db(): Kysely<Schema> {
+    return this.core.db as unknown as Kysely<Schema>;
+  }
+}
+
+type UnionToIntersection<U> =
+  (U extends any ? (k: U) => void : never) extends ((k: infer I) => void) ? I : never;
+
+type ExtractPluginSchema<K> = K extends keyof PluginRegistry
+  ? PluginRegistry[K] extends { schema: infer S } ? S : {}
+  : {};
+
+type ExtractServices<T extends readonly (keyof PluginRegistry)[] | undefined> =
+  T extends readonly []
+    ? {}
+    : T extends readonly (infer K)[]
+      ? K extends keyof PluginRegistry
+        ? { [P in K]: PluginRegistry[P] extends { service: infer S } ? S : unknown }
+        : {}
+      : {};
+
+type ExtractSchemas<T extends readonly (keyof PluginRegistry)[] | undefined> =
+  T extends readonly []
+    ? {}
+    : T extends readonly (infer K)[]
+      ? UnionToIntersection<ExtractPluginSchema<K>>
+      : {};
+
+type SelfDependencyError<Name extends string> =
+  `Error: Plugin '${Name}' cannot depend on itself`;
+
+type PluginDependsOn<
+  PluginName extends keyof PluginRegistry,
+  Target extends string
+> = PluginRegistry[PluginName] extends { _dependencies: readonly (infer D)[] }
+  ? Target extends D
+    ? true
+    : false
+  : false;
+
+type FindCircularDep<
+  Name extends string,
+  Deps extends readonly (keyof PluginRegistry)[]
+> = {
+  [K in Deps[number]]: PluginDependsOn<K, Name> extends true ? K : never
+}[Deps[number]];
+
+type CircularDependencyError<Name extends string, CircularDep extends string> =
+  `Error: Circular dependency - '${CircularDep}' already depends on '${Name}'`;
+
+type ValidateDeps<
+  Name extends string,
+  Deps extends readonly (keyof PluginRegistry)[]
+> = Name extends Deps[number]
+  ? SelfDependencyError<Name>
+  : FindCircularDep<Name, Deps> extends never
+    ? Deps
+    : CircularDependencyError<Name, FindCircularDep<Name, Deps> & string>;
+
+export interface PluginConfig<
+  Name extends keyof PluginRegistry,
+  Deps extends readonly (keyof PluginRegistry)[] | undefined,
+  LocalSchema,
+  Service,
+  Handlers = {},
+  Middleware = {},
+  Config = void,
+  FullSchema = LocalSchema & ExtractSchemas<Deps>
+> {
+  name: Name;
+  version?: string;
+  dependencies?: Deps;
+  service: (ctx: PluginContext<ExtractServices<Deps>, FullSchema, Config>) => Promise<Service> | Service;
+  handlers?: Handlers;
+  middleware?: Middleware;
+}
+
+export type PluginFactory<Config, P extends Plugin = Plugin> = ((config: Config) => P) & {
+  _configType: Config;
+};
+
+export class PluginBuilder<LocalSchema = {}> {
+  withSchema<S>(): PluginBuilder<S> {
+    return new PluginBuilder<S>();
+  }
+
+  withConfig<C>(): ConfiguredPluginBuilder<LocalSchema, C> {
+    return new ConfiguredPluginBuilder<LocalSchema, C>();
+  }
+
+  define<
+    Name extends string,
+    const Deps extends readonly (keyof PluginRegistry)[] = readonly [],
+    const Handlers extends object = {},
+    const Middleware extends object = {},
+    const Events extends EventSchemas = {},
+    const CustomErrors extends CustomErrorRegistry = {},
+    Service = void
+  >(
+    config: {
+      name: Name;
+      version?: string;
+      dependencies?: ValidateDeps<Name, Deps> extends Deps ? Deps : ValidateDeps<Name, Deps>;
+      handlers?: Handlers;
+      middleware?: Middleware;
+      events?: Events;
+      client?: ClientConfig;
+      customErrors?: CustomErrors;
+      service: (
+        ctx: PluginContext<ExtractServices<Deps>, LocalSchema & ExtractSchemas<Deps>, void>
+      ) => Promise<Service> | Service;
+    }
+  ): Plugin & {
+    name: Name;
+    _dependencies: Deps;
+    _schema: LocalSchema;
+    _fullSchema: LocalSchema & ExtractSchemas<Deps>;
+    handlers?: Handlers;
+    middleware?: Middleware;
+    events?: Events;
+    client?: ClientConfig;
+    customErrors?: CustomErrors;
+  } {
+    return config as any;
+  }
+}
+
+export class ConfiguredPluginBuilder<LocalSchema, Config> {
+  withSchema<S>(): ConfiguredPluginBuilder<S, Config> {
+    return new ConfiguredPluginBuilder<S, Config>();
+  }
+
+  define<
+    Name extends string,
+    const Deps extends readonly (keyof PluginRegistry)[] = readonly [],
+    const Handlers extends object = {},
+    const Middleware extends object = {},
+    const Events extends EventSchemas = {},
+    const CustomErrors extends CustomErrorRegistry = {},
+    Service = void
+  >(
+    pluginDef: {
+      name: Name;
+      version?: string;
+      dependencies?: ValidateDeps<Name, Deps> extends Deps ? Deps : ValidateDeps<Name, Deps>;
+      handlers?: Handlers;
+      middleware?: Middleware;
+      events?: Events;
+      client?: ClientConfig;
+      customErrors?: CustomErrors;
+      service: (
+        ctx: PluginContext<ExtractServices<Deps>, LocalSchema & ExtractSchemas<Deps>, Config>
+      ) => Promise<Service> | Service;
+    }
+  ): PluginFactory<Config, Plugin & {
+    name: Name;
+    _dependencies: Deps;
+    _schema: LocalSchema;
+    _fullSchema: LocalSchema & ExtractSchemas<Deps>;
+    _config: Config;
+    handlers?: Handlers;
+    middleware?: Middleware;
+    events?: Events;
+    client?: ClientConfig;
+    customErrors?: CustomErrors;
+  }> {
+    const factory = (config: Config) => ({
+      ...pluginDef,
+      _boundConfig: config,
+    });
+    return factory as any;
+  }
+}
+
+export const createPlugin: PluginBuilder<{}> = new PluginBuilder();
+
+type UnwrapPluginFactory<T> = T extends (config: any) => infer P ? P : T;
+
+export type InferService<T> = UnwrapPluginFactory<T> extends { service: (ctx: any) => Promise<infer S> | infer S }
+  ? S
+  : UnwrapPluginFactory<T> extends { service: (...args: any[]) => infer S }
+  ? Awaited<S>
+  : never;
+export type InferSchema<T> = UnwrapPluginFactory<T> extends { _schema: infer S } ? S : never;
+export type InferHandlers<T> = UnwrapPluginFactory<T> extends { handlers?: infer H } ? H : {};
+export type InferMiddleware<T> = UnwrapPluginFactory<T> extends { middleware?: infer M } ? M : {};
+export type InferDependencies<T> = UnwrapPluginFactory<T> extends { _dependencies: infer D } ? D : readonly [];
+export type InferConfig<T> = T extends (config: infer C) => any ? C : void;
+export type InferEvents<T> = UnwrapPluginFactory<T> extends { events?: infer E } ? E : {};
+export type InferClientConfig<T> = UnwrapPluginFactory<T> extends { client?: infer C } ? C : undefined;
+export type InferCustomErrors<T> = UnwrapPluginFactory<T> extends { customErrors?: infer E } ? E : {};
+
+export type { ExtractServices, ExtractSchemas };
+
+export type Plugin = {
+    name: string;
+    version?: string;
+    dependencies?: readonly string[];
+    handlers?: Record<string, any>;
+    middleware?: Record<string, any>;
+    events?: Record<string, any>;
+    client?: ClientConfig;
+    customErrors?: CustomErrorRegistry;
+    service: (ctx: any) => any;
+};
+
+export type PluginWithConfig<Config = void> = Plugin & {
+    _config?: Config;
+};
+
+export type ConfiguredPlugin = Plugin & { _boundConfig?: any };
+
+export class PluginManager {
+  private plugins: Map<string, ConfiguredPlugin> = new Map();
+  private services: Record<string, any> = {};
+  private core: CoreServices;
+
+  constructor(core: CoreServices) {
+    this.core = core;
+  }
+
+  getServices(): any {
+      return this.services;
+  }
+
+  getCore(): CoreServices {
+      return this.core;
+  }
+
+  getPlugins(): Plugin[] {
+      return Array.from(this.plugins.values());
+  }
+
+  register(plugin: ConfiguredPlugin): void {
+    if (this.plugins.has(plugin.name)) {
+      throw new Error(`Plugin ${plugin.name} is already registered.`);
+    }
+    this.plugins.set(plugin.name, plugin);
+  }
+
+  async migrate(): Promise<void> {
+    console.log("Running migrations (File-System Based)...");
+    const sortedPlugins = this.resolveOrder();
+
+    for (const plugin of sortedPlugins) {
+        const pluginName = plugin.name;
+        const possibleMigrationDirs = [
+          join(process.cwd(), "examples/basic-server/src/plugins", pluginName, "migrations"),
+          join(process.cwd(), "src/plugins", pluginName, "migrations"),
+          join(process.cwd(), "plugins", pluginName, "migrations"),
+        ];
+
+        let migrationDir = "";
+        for (const dir of possibleMigrationDirs) {
+          try {
+            await readdir(dir);
+            migrationDir = dir;
+            break;
+          } catch {
+            continue;
+          }
+        }
+
+        if (!migrationDir) continue;
+
+        try {
+             const files = await readdir(migrationDir);
+             const migrationFiles = files.filter(f => f.endsWith(".ts"));
+
+             if (migrationFiles.length > 0) {
+                 console.log(`[Migration] checking plugin: ${pluginName} at ${migrationDir}`);
+
+                 for (const file of migrationFiles.sort()) {
+                     console.log(`  - Executing migration: ${file}`);
+                     const migrationPath = join(migrationDir, file);
+                     const migration = await import(migrationPath);
+
+                     if (migration.up) {
+                         try {
+                              await migration.up(this.core.db);
+                              console.log(`    Success`);
+                         } catch (e) {
+                             console.error(`    Failed to run ${file}:`, e);
+                         }
+                     }
+                 }
+             }
+        } catch {
+            // Migration directory doesn't exist, skip
+        }
+    }
+  }
+
+  async init(): Promise<void> {
+    for (const plugin of this.plugins.values()) {
+      const deps = plugin.dependencies || [];
+      for (const dep of deps) {
+        if (!this.plugins.has(dep)) {
+          throw new Error(`Plugin '${plugin.name}' depends on '${dep}', but it is not registered.`);
+        }
+      }
+    }
+
+    const sortedPlugins = this.resolveOrder();
+
+    for (const plugin of sortedPlugins) {
+        console.log(`Initializing plugin: ${plugin.name}`);
+
+        if (plugin.customErrors) {
+            for (const [errorName, errorDef] of Object.entries(plugin.customErrors)) {
+                this.core.errors.register(errorName, errorDef);
+                console.log(`[${plugin.name}] Registered custom error: ${errorName}`);
+            }
+        }
+
+        const pluginDeps: Record<string, unknown> = {};
+        if (plugin.dependencies) {
+            for (const depName of plugin.dependencies) {
+                pluginDeps[depName] = this.services[depName];
+            }
+        }
+
+        const pluginConfig = (plugin as ConfiguredPlugin)._boundConfig;
+        const ctx = new PluginContext(this.core, pluginDeps, pluginConfig);
+        const service = await plugin.service(ctx);
+
+        if (service) {
+            this.services[plugin.name] = service;
+            console.log(`[${plugin.name}] Service registered.`);
+        }
+    }
+
+    console.log("All plugins initialized.");
+  }
+
+  private resolveOrder(): Plugin[] {
+    const visited = new Set<string>();
+    const sorted: Plugin[] = [];
+    const visiting = new Set<string>();
+
+    const visit = (plugin: Plugin) => {
+        const name = plugin.name;
+        if (visited.has(name)) return;
+        if (visiting.has(name)) throw new Error(`Circular dependency detected: ${name}`);
+
+        visiting.add(name);
+
+        const deps = plugin.dependencies || [];
+        for (const depName of deps) {
+            const depPlugin = this.plugins.get(depName);
+            if (depPlugin) visit(depPlugin);
+        }
+
+        visiting.delete(name);
+        visited.add(name);
+        sorted.push(plugin);
+    };
+
+    for (const plugin of this.plugins.values()) {
+        visit(plugin);
+    }
+
+    return sorted;
+  }
+}