@donkeylabs/server 0.3.0 → 0.3.1

package/src/server.ts

@@ -1,7 +1,7 @@
 import { z } from "zod";
 import { PluginManager, type CoreServices, type ConfiguredPlugin } from "./core";
-import { Router as RouterImpl, type IRouter, type RouteDefinition, type ServerContext } from "./router";
-import { Handlers, type HandlerRuntime } from "./handlers";
+import { type IRouter, type RouteDefinition, type ServerContext } from "./router";
+import { Handlers } from "./handlers";
 import type { MiddlewareRuntime, MiddlewareDefinition } from "./middleware";
 import {
   createLogger,
@@ -22,14 +22,13 @@ import {
   type SSEConfig,
   type RateLimiterConfig,
   type ErrorsConfig,
-  type JobDefinition,
-  type CronTaskDefinition,
 } from "./core/index";
 
 export interface ServerConfig {
   port?: number;
   db: CoreServices["db"];
   config?: Record<string, any>;
+  // Core service configurations
   logger?: LoggerConfig;
   cache?: CacheConfig;
   events?: EventsConfig;
@@ -40,54 +39,22 @@ export interface ServerConfig {
   errors?: ErrorsConfig;
 }
 
-export interface ServerInspection {
-  port: number;
-  plugins: Array<{
-    name: string;
-    version?: string;
-    dependencies: string[];
-    hasHandlers: boolean;
-    hasMiddleware: boolean;
-    hasEvents: boolean;
-    hasSseChannels: boolean;
-    hasJobs: boolean;
-    hasCronTasks: boolean;
-    hasCustomErrors: boolean;
-  }>;
-  routes: Array<{ name: string; handler: string }>;
-  handlers: string[];
-  events: string[];
-  sseChannels: string[];
-  jobs: Array<{ name: string; pluginName?: string; description?: string }>;
-  cronTasks: Array<{
-    id: string;
-    name: string;
-    expression: string;
-    enabled: boolean;
-    pluginName?: string;
-    description?: string;
-    lastRun?: Date;
-    nextRun?: Date;
-  }>;
-  rateLimitRules: Array<{ pattern: string; limit: number; window: string | number }>;
-}
-
 export class AppServer {
   private port: number;
   private manager: PluginManager;
   private routers: IRouter[] = [];
   private routeMap: Map<string, RouteDefinition> = new Map();
-  private customHandlers: Map<string, HandlerRuntime<any>> = new Map();
   private coreServices: CoreServices;
 
   constructor(options: ServerConfig) {
     this.port = options.port ?? 3000;
 
+    // Initialize core services
     const logger = createLogger(options.logger);
     const cache = createCache(options.cache);
     const events = createEvents(options.events);
     const cron = createCron(options.cron);
-    const jobs = createJobs({ ...options.jobs, events });
+    const jobs = createJobs({ ...options.jobs, events }); // Jobs can emit events
     const sse = createSSE(options.sse);
     const rateLimiter = createRateLimiter(options.rateLimiter);
     const errors = createErrors(options.errors);
@@ -108,248 +75,58 @@ export class AppServer {
     this.manager = new PluginManager(this.coreServices);
   }
 
-  registerPlugin(plugin: ConfiguredPlugin): this {
-    this.manager.register(plugin);
-    return this;
-  }
-
   /**
-   * Register a custom handler for use in routes.
-   *
-   * @example
-   * server.registerHandler("echo", EchoHandler);
-   * // Then in routes:
-   * router.route("test").echo({ handle: ... });
+   * Register a plugin.
+   * For plugins with config, call the plugin factory first: registerPlugin(authPlugin({ key: "..." }))
+   * Plugins are initialized in dependency order when start() is called.
    */
-  registerHandler(name: string, handler: HandlerRuntime<any>): this {
-    this.customHandlers.set(name, handler);
-    return this;
-  }
-
-  /**
-   * Register an event schema for validation.
-   * Events must be registered before they can be emitted.
-   *
-   * @example
-   * server.registerEvent("user.created", z.object({ userId: z.string() }));
-   */
-  registerEvent<T>(name: string, schema: z.ZodType<T>): this {
-    this.coreServices.events.register(name, schema);
-    return this;
-  }
-
-  /**
-   * Register multiple event schemas.
-   */
-  registerEvents(schemas: Record<string, z.ZodType<any>>): this {
-    this.coreServices.events.registerMany(schemas);
-    return this;
-  }
-
-  /**
-   * Register an SSE channel with optional event schemas.
-   * Channels must be registered before broadcasting.
-   *
-   * @example
-   * server.registerSSEChannel("notifications", {
-   *   events: { "new": z.object({ id: z.string(), message: z.string() }) }
-   * });
-   */
-  registerSSEChannel(name: string, config?: { events?: Record<string, z.ZodType<any>>; pattern?: boolean }): this {
-    this.coreServices.sse.registerChannel(name, config);
-    return this;
-  }
-
-  /**
-   * Register multiple SSE channels.
-   */
-  registerSSEChannels(channels: Record<string, { events?: Record<string, z.ZodType<any>>; pattern?: boolean }>): this {
-    this.coreServices.sse.registerChannels(channels);
-    return this;
-  }
-
-  /**
-   * Register a rate limit rule for a route pattern.
-   * Rules are auto-enforced in the request handler.
-   *
-   * @example
-   * server.registerRateLimit("auth.login", { limit: 5, window: "15m" });
-   * server.registerRateLimit("api.*", { limit: 100, window: "1m" });
-   */
-  registerRateLimit(pattern: string, rule: {
-    limit: number;
-    window: string | number;
-    keyFn?: (ctx: { ip: string; route: string; user?: any }) => string;
-    skip?: (ctx: { ip: string; route: string; user?: any }) => boolean;
-    message?: string;
-  }): this {
-    this.coreServices.rateLimiter.registerRule(pattern, rule);
-    return this;
-  }
-
-  /**
-   * Register multiple rate limit rules.
-   */
-  registerRateLimits(rules: Record<string, {
-    limit: number;
-    window: string | number;
-    keyFn?: (ctx: { ip: string; route: string; user?: any }) => string;
-    skip?: (ctx: { ip: string; route: string; user?: any }) => boolean;
-    message?: string;
-  }>): this {
-    this.coreServices.rateLimiter.registerRules(rules);
-    return this;
-  }
-
-  /**
-   * Register a job with schema validation.
-   *
-   * @example
-   * server.registerJob("email.send", {
-   *   schema: z.object({ to: z.string().email(), subject: z.string() }),
-   *   handler: async (data) => { await sendEmail(data); }
-   * });
-   */
-  registerJob<T = any, R = any>(name: string, definition: JobDefinition<T, R>): this {
-    this.coreServices.jobs.registerJob(name, definition);
-    return this;
-  }
-
-  /**
-   * Register multiple jobs at once.
-   */
-  registerJobs(jobs: Record<string, JobDefinition>): this {
-    this.coreServices.jobs.registerJobs(jobs);
+  registerPlugin(plugin: ConfiguredPlugin): this {
+    this.manager.register(plugin);
     return this;
   }
 
   /**
-   * Register a cron task.
-   *
-   * @example
-   * server.registerCronTask("cleanup.daily", {
-   *   expression: "0 0 * * *",
-   *   handler: async () => { await cleanupOldRecords(); },
-   *   description: "Clean up old records daily at midnight"
-   * });
+   * Add a router to handle RPC routes.
    */
-  registerCronTask(name: string, definition: CronTaskDefinition): this {
-    this.coreServices.cron.registerTask(name, definition);
+  use(router: IRouter): this {
+    this.routers.push(router);
     return this;
   }
 
   /**
-   * Register multiple cron tasks at once.
+   * Get plugin services (for testing or advanced use cases).
    */
-  registerCronTasks(tasks: Record<string, CronTaskDefinition>): this {
-    this.coreServices.cron.registerTasks(tasks);
-    return this;
-  }
-
-  /** Create a new router with prefix or register an existing router */
-  router(prefixOrRouter: string | IRouter): IRouter {
-    if (typeof prefixOrRouter === "string") {
-      const newRouter = new RouterImpl(prefixOrRouter);
-      this.routers.push(newRouter);
-      return newRouter;
-    }
-    this.routers.push(prefixOrRouter);
-    return prefixOrRouter;
-  }
-
   getServices(): any {
     return this.manager.getServices();
   }
 
-  getDb(): CoreServices["db"] {
-    return this.manager.getCore().db;
-  }
-
   /**
-   * Introspect all registered services, handlers, routes, and plugins.
-   * Useful for debugging and documentation generation.
+   * Get the database instance.
    */
-  inspect(): ServerInspection {
-    const plugins = this.manager.getPlugins().map(p => ({
-      name: p.name,
-      version: p.version,
-      dependencies: p.dependencies ? [...p.dependencies] : [],
-      hasHandlers: !!p.handlers && Object.keys(p.handlers).length > 0,
-      hasMiddleware: !!p.middleware,
-      hasEvents: !!p.events && Object.keys(p.events).length > 0,
-      hasSseChannels: !!p.sseChannels && Object.keys(p.sseChannels).length > 0,
-      hasJobs: !!p.jobs && Object.keys(p.jobs).length > 0,
-      hasCronTasks: !!p.cronTasks && Object.keys(p.cronTasks).length > 0,
-      hasCustomErrors: !!p.customErrors && Object.keys(p.customErrors).length > 0,
-    }));
-
-    const routes = this.getRoutes();
-
-    const handlers = [
-      ...Object.keys(Handlers),
-      ...Array.from(this.customHandlers.keys()),
-      ...this.manager.getPlugins().flatMap(p =>
-        p.handlers ? Object.keys(p.handlers) : []
-      ),
-    ];
-
-    const events = this.coreServices.events.listRegistered();
-
-    const sseChannels = this.coreServices.sse.listChannels
-      ? this.coreServices.sse.listChannels()
-      : [];
-
-    const jobs = this.coreServices.jobs.listRegisteredJobs();
-
-    const cronTasks = this.coreServices.cron.list();
-
-    const rateLimitRules = this.coreServices.rateLimiter.listRules
-      ? this.coreServices.rateLimiter.listRules()
-      : [];
-
-    return {
-      port: this.port,
-      plugins,
-      routes,
-      handlers: [...new Set(handlers)],
-      events,
-      sseChannels,
-      jobs: jobs.map(j => ({
-        name: j.name,
-        pluginName: j.pluginName,
-        description: j.description,
-      })),
-      cronTasks: cronTasks.map(t => ({
-        id: t.id,
-        name: t.name,
-        expression: t.expression,
-        enabled: t.enabled,
-        pluginName: t.pluginName,
-        description: t.description,
-        lastRun: t.lastRun,
-        nextRun: t.nextRun,
-      })),
-      rateLimitRules,
-    };
+  getDb(): CoreServices["db"] {
+    return this.manager.getCore().db;
   }
 
+  // Resolve middleware runtime from plugins
   private resolveMiddleware(name: string): MiddlewareRuntime<any> | undefined {
     for (const plugin of this.manager.getPlugins()) {
-      // Use resolved middleware (from calling middleware function during init)
-      const resolvedMiddleware = (plugin as any)._resolvedMiddleware;
-      if (resolvedMiddleware && resolvedMiddleware[name]) {
-        return resolvedMiddleware[name] as MiddlewareRuntime<any>;
+      // Middleware is resolved and stored in _resolvedMiddleware during plugin init
+      const resolved = (plugin as any)._resolvedMiddleware as Record<string, MiddlewareRuntime<any>> | undefined;
+      if (resolved && resolved[name]) {
+        return resolved[name];
       }
     }
     return undefined;
   }
 
+  // Execute middleware chain, then call final handler
   private async executeMiddlewareChain(
     req: Request,
     ctx: ServerContext,
     stack: MiddlewareDefinition[],
     finalHandler: () => Promise<Response>
   ): Promise<Response> {
+    // Build chain from end to start (last middleware wraps first)
     let next = finalHandler;
 
     for (let i = stack.length - 1; i >= 0; i--) {
@@ -371,41 +148,257 @@ export class AppServer {
     return next();
   }
 
+  /**
+   * Get core services (for advanced use cases).
+   */
   getCore(): CoreServices {
     return this.coreServices;
   }
 
-  /** Get all registered routes for code generation */
-  getRoutes(): { name: string; handler: string }[] {
-    const routes: { name: string; handler: string }[] = [];
+  /**
+   * Get the internal route map for adapter introspection.
+   */
+  getRouteMap(): Map<string, RouteDefinition> {
+    return this.routeMap;
+  }
+
+  /**
+   * Check if a route name is registered.
+   */
+  hasRoute(routeName: string): boolean {
+    return this.routeMap.has(routeName);
+  }
+
+  /**
+   * Initialize server without starting HTTP server.
+   * Used by adapters (e.g., SvelteKit) that manage their own HTTP server.
+   */
+  async initialize(): Promise<void> {
+    const { logger } = this.coreServices;
+
+    await this.manager.migrate();
+    await this.manager.init();
+
+    this.coreServices.cron.start();
+    this.coreServices.jobs.start();
+    logger.info("Background services started (cron, jobs)");
+
     for (const router of this.routers) {
       for (const route of router.getRoutes()) {
-        routes.push({
-          name: route.name,
-          handler: route.handler || "typed",
+        if (this.routeMap.has(route.name)) {
+          logger.warn(`Duplicate route detected`, { route: route.name });
+        }
+        this.routeMap.set(route.name, route);
+      }
+    }
+    logger.info(`Loaded ${this.routeMap.size} RPC routes`);
+    logger.info("Server initialized (adapter mode)");
+  }
+
+  /**
+   * Handle a single API request. Used by adapters.
+   * Returns null if the route is not found.
+   */
+  async handleRequest(
+    req: Request,
+    routeName: string,
+    ip: string,
+    options?: { corsHeaders?: Record<string, string> }
+  ): Promise<Response | null> {
+    const { logger } = this.coreServices;
+    const corsHeaders = options?.corsHeaders ?? {};
+
+    const route = this.routeMap.get(routeName);
+    if (!route) {
+      return null;
+    }
+
+    const type = route.handler || "typed";
+
+    // First check core handlers
+    let handler = Handlers[type as keyof typeof Handlers];
+
+    // If not found, check plugin handlers
+    if (!handler) {
+      for (const config of this.manager.getPlugins()) {
+        if (config.handlers && config.handlers[type]) {
+          handler = config.handlers[type] as any;
+          break;
+        }
+      }
+    }
+
+    if (!handler) {
+      logger.error("Handler not found", { handler: type, route: routeName });
+      return Response.json(
+        { error: "HANDLER_NOT_FOUND", message: "Handler not found" },
+        { status: 500, headers: corsHeaders }
+      );
+    }
+
+    // Build context
+    const ctx: ServerContext = {
+      db: this.coreServices.db,
+      plugins: this.manager.getServices(),
+      core: this.coreServices,
+      errors: this.coreServices.errors,
+      config: this.coreServices.config,
+      ip,
+      requestId: crypto.randomUUID(),
+    };
+
+    // Get middleware stack
+    const middlewareStack = route.middleware || [];
+
+    // Final handler
+    const finalHandler = async () => {
+      const response = await handler.execute(req, route, route.handle, ctx);
+      // Add CORS headers if provided
+      if (Object.keys(corsHeaders).length > 0 && response instanceof Response) {
+        const newHeaders = new Headers(response.headers);
+        Object.entries(corsHeaders).forEach(([k, v]) => newHeaders.set(k, v));
+        return new Response(response.body, {
+          status: response.status,
+          statusText: response.statusText,
+          headers: newHeaders,
+        });
+      }
+      return response;
+    };
+
+    try {
+      if (middlewareStack.length > 0) {
+        return await this.executeMiddlewareChain(req, ctx, middlewareStack, finalHandler);
+      } else {
+        return await finalHandler();
+      }
+    } catch (error) {
+      if (error instanceof HttpError) {
+        logger.warn("HTTP error thrown", {
+          route: routeName,
+          status: error.status,
+          code: error.code,
+          message: error.message,
+        });
+        return Response.json(error.toJSON(), {
+          status: error.status,
+          headers: corsHeaders,
         });
       }
+      throw error;
     }
-    return routes;
   }
 
-  async start(): Promise<void> {
+  /**
+   * Call a route directly without HTTP (for SSR).
+   * This bypasses the HTTP layer and calls the route handler directly.
+   *
+   * @param routeName - The route name (e.g., "api.counter.get")
+   * @param input - The input data for the route
+   * @param ip - Client IP address (optional, defaults to "127.0.0.1")
+   * @returns The route handler result
+   */
+  async callRoute<TOutput = any>(
+    routeName: string,
+    input: any,
+    ip: string = "127.0.0.1"
+  ): Promise<TOutput> {
     const { logger } = this.coreServices;
 
-    // If running in generate mode, export routes and exit
-    if (process.env.DONKEYLABS_GENERATE === "1") {
-      const routes = this.getRoutes();
-      console.log(JSON.stringify({ routes }));
-      process.exit(0);
+    const route = this.routeMap.get(routeName);
+    if (!route) {
+      throw new Error(`Route "${routeName}" not found`);
+    }
+
+    // Build context
+    const ctx: ServerContext = {
+      db: this.coreServices.db,
+      plugins: this.manager.getServices(),
+      core: this.coreServices,
+      errors: this.coreServices.errors,
+      config: this.coreServices.config,
+      ip,
+      requestId: crypto.randomUUID(),
+    };
+
+    // Validate input if schema exists
+    if (route.input) {
+      const result = route.input.safeParse(input);
+      if (!result.success) {
+        throw new HttpError(400, "VALIDATION_ERROR", result.error.message);
+      }
+      input = result.data;
+    }
+
+    // Execute through middleware chain if present
+    const middlewareStack = route.middleware || [];
+
+    const finalHandler = async () => {
+      return route.handle(input, ctx);
+    };
+
+    try {
+      if (middlewareStack.length > 0) {
+        // Create a fake request for middleware compatibility
+        const fakeReq = new Request("http://localhost/" + routeName, {
+          method: "POST",
+          body: JSON.stringify(input),
+        });
+        const response = await this.executeMiddlewareChain(
+          fakeReq,
+          ctx,
+          middlewareStack,
+          async () => {
+            const result = await finalHandler();
+            // Return as Response for middleware chain, we'll extract later
+            return Response.json(result);
+          }
+        );
+        // Extract result from Response
+        if (response instanceof Response) {
+          return response.json();
+        }
+        return response;
+      } else {
+        return await finalHandler();
+      }
+    } catch (error) {
+      if (error instanceof HttpError) {
+        logger.warn("Route error (SSR)", {
+          route: routeName,
+          status: error.status,
+          code: error.code,
+        });
+        // Re-throw as a proper error for SSR
+        throw error;
+      }
+      throw error;
     }
+  }
+
+  /**
+   * Start the server.
+   * This will:
+   * 1. Run all plugin migrations
+   * 2. Initialize all plugins in dependency order
+   * 3. Start cron and jobs services
+   * 4. Start the HTTP server
+   */
+  async start() {
+    const { logger } = this.coreServices;
 
+    // 1. Run migrations
     await this.manager.migrate();
+
+    // 2. Initialize plugins
     await this.manager.init();
 
+    // 3. Start background services
     this.coreServices.cron.start();
     this.coreServices.jobs.start();
     logger.info("Background services started (cron, jobs)");
 
+    // 4. Build route map
     for (const router of this.routers) {
       for (const route of router.getRoutes()) {
         if (this.routeMap.has(route.name)) {
@@ -416,109 +409,133 @@ export class AppServer {
     }
     logger.info(`Loaded ${this.routeMap.size} RPC routes`);
 
+    // 5. Start HTTP server
     Bun.serve({
       port: this.port,
       fetch: async (req, server) => {
         const url = new URL(req.url);
+
+        // Extract client IP
         const ip = extractClientIP(req, server.requestIP(req)?.address);
 
-        if (req.method !== "POST") {
-          return new Response("Method Not Allowed", { status: 405 });
+        // Handle SSE endpoint
+        if (url.pathname === "/sse" && req.method === "GET") {
+          return this.handleSSE(req, ip);
         }
 
-        const actionName = url.pathname.slice(1);
-        const route = this.routeMap.get(actionName);
+        // We only allow POST for RPC routes
+        if (req.method !== "POST") return new Response("Method Not Allowed", { status: 405 });
 
-        if (!route) {
-          return new Response("Not Found", { status: 404 });
-        }
+        // Extract action from URL path (e.g., "auth.login")
+        const actionName = url.pathname.slice(1);
 
-        // Auto rate limit check against registered rules
-        const rateLimitResult = await this.coreServices.rateLimiter.checkRoute(actionName, { ip });
-        if (rateLimitResult && !rateLimitResult.allowed) {
-          const rule = this.coreServices.rateLimiter.matchRoute(actionName);
-          return Response.json(
-            {
-              error: "TOO_MANY_REQUESTS",
-              message: rule?.message ?? "Rate limit exceeded. Please try again later.",
-              retryAfter: rateLimitResult.retryAfter,
-            },
-            {
-              status: 429,
-              headers: {
-                "Retry-After": String(rateLimitResult.retryAfter),
-                "X-RateLimit-Limit": String(rateLimitResult.limit),
-                "X-RateLimit-Remaining": String(rateLimitResult.remaining),
-                "X-RateLimit-Reset": rateLimitResult.resetAt.toISOString(),
-              },
+        const route = this.routeMap.get(actionName);
+        if (route) {
+          const type = route.handler || "typed";
+
+          // First check core handlers
+          let handler = Handlers[type as keyof typeof Handlers];
+
+          // If not found, check plugin handlers
+          if (!handler) {
+            for (const config of this.manager.getPlugins()) {
+              if (config.handlers && config.handlers[type]) {
+                handler = config.handlers[type] as any;
+                break;
+              }
             }
-          );
-        }
-
-        const type = route.handler || "typed";
-        let handler: HandlerRuntime<any> | undefined = Handlers[type as keyof typeof Handlers];
-
-        // Check user-registered handlers
-        if (!handler) {
-          handler = this.customHandlers.get(type);
-        }
+          }
 
-        // Check plugin handlers
-        if (!handler) {
-          for (const plugin of this.manager.getPlugins()) {
-            if (plugin.handlers && plugin.handlers[type]) {
-              handler = plugin.handlers[type] as any;
-              break;
+          if (handler) {
+            // Build context with core services and IP
+            const ctx: ServerContext = {
+              db: this.coreServices.db,
+              plugins: this.manager.getServices(),
+              core: this.coreServices,
+              errors: this.coreServices.errors, // Convenience access
+              config: this.coreServices.config,
+              ip,
+              requestId: crypto.randomUUID(),
+            };
+
+            // Get middleware stack for this route
+            const middlewareStack = route.middleware || [];
+
+            // Final handler execution
+            const finalHandler = async () => {
+              return await handler.execute(req, route, route.handle, ctx);
+            };
+
+            // Execute middleware chain, then handler - with HttpError handling
+            try {
+              if (middlewareStack.length > 0) {
+                return await this.executeMiddlewareChain(req, ctx, middlewareStack, finalHandler);
+              } else {
+                return await finalHandler();
+              }
+            } catch (error) {
+              // Handle HttpError (thrown via ctx.errors.*)
+              if (error instanceof HttpError) {
+                logger.warn("HTTP error thrown", {
+                  route: actionName,
+                  status: error.status,
+                  code: error.code,
+                  message: error.message,
+                });
+                return Response.json(error.toJSON(), { status: error.status });
+              }
+              // Re-throw unknown errors
+              throw error;
             }
+          } else {
+            logger.error("Handler not found", { handler: type, route: actionName });
+            return new Response("Handler Not Found", { status: 500 });
           }
         }
 
-        if (!handler) {
-          logger.error("Handler not found", { handler: type, route: actionName });
-          return new Response("Handler Not Found", { status: 500 });
-        }
-
-        const ctx: ServerContext = {
-          db: this.coreServices.db,
-          plugins: this.manager.getServices(),
-          core: this.coreServices,
-          errors: this.coreServices.errors,
-          config: this.coreServices.config,
-          ip,
-          requestId: crypto.randomUUID(),
-        };
-
-        const routeMiddleware = route.middleware || [];
-        const routeHandler = async () => handler.execute(req, route, route.handle, ctx);
-
-        try {
-          if (routeMiddleware.length > 0) {
-            return await this.executeMiddlewareChain(req, ctx, routeMiddleware, routeHandler);
-          }
-          return await routeHandler();
-        } catch (error) {
-          if (error instanceof HttpError) {
-            logger.warn("HTTP error thrown", {
-              route: actionName,
-              status: error.status,
-              code: error.code,
-              message: error.message,
-            });
-            return Response.json(error.toJSON(), { status: error.status });
-          }
-          throw error;
-        }
+        return new Response("Not Found", { status: 404 });
       }
     });
 
     logger.info(`Server running at http://localhost:${this.port}`);
   }
 
-  async shutdown(): Promise<void> {
+  /**
+   * Handle SSE (Server-Sent Events) connections.
+   * Used by both standalone server and adapters.
+   */
+  handleSSE(req: Request, ip: string): Response {
+    const url = new URL(req.url);
+    const channels = url.searchParams.get("channels")?.split(",").filter(Boolean) || [];
+    const lastEventId = req.headers.get("last-event-id") || undefined;
+
+    const { client, response } = this.coreServices.sse.addClient({ lastEventId });
+
+    // Subscribe to requested channels
+    for (const channel of channels) {
+      this.coreServices.sse.subscribe(client.id, channel);
+    }
+
+    // Clean up when connection closes
+    req.signal.addEventListener("abort", () => {
+      this.coreServices.sse.removeClient(client.id);
+    });
+
+    return response;
+  }
+
+  /**
+   * Gracefully shutdown the server.
+   * Stops background services and closes SSE connections.
+   */
+  async shutdown() {
     const { logger } = this.coreServices;
     logger.info("Shutting down server...");
 
+    // Stop SSE (closes all client connections)
     this.coreServices.sse.shutdown();
+
+    // Stop background services
     await this.coreServices.jobs.stop();
     await this.coreServices.cron.stop();