@donkeylabs/server 1.1.4 → 1.1.8

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@donkeylabs/server",
-  "version": "1.1.4",
+  "version": "1.1.8",
   "type": "module",
   "description": "Type-safe plugin system for building RPC-style APIs with Bun",
   "main": "./src/index.ts",

package/src/client/base.ts

@@ -177,6 +177,23 @@ export interface SSEOptions {
   reconnectDelay?: number;
 }
 
+/**
+ * SSE subscription returned by route-specific SSE methods.
+ * Provides typed event handling for the route's defined events.
+ */
+export interface SSESubscription<TEvents extends Record<string, any>> {
+  /** Subscribe to a typed event. Returns unsubscribe function. */
+  on<E extends keyof TEvents>(event: E, handler: (data: TEvents[E]) => void): () => void;
+  /** Subscribe to an event once. Returns unsubscribe function. */
+  once<E extends keyof TEvents>(event: E, handler: (data: TEvents[E]) => void): () => void;
+  /** Remove all handlers for an event. */
+  off<E extends keyof TEvents>(event: E): void;
+  /** Close the SSE connection. */
+  close(): void;
+  /** Whether the connection is currently open. */
+  readonly connected: boolean;
+}
+
 // ============================================
 // Base Client Implementation
 // ============================================
@@ -268,10 +285,209 @@ export class ApiClientBase<TEvents extends Record<string, any> = Record<string,
     });
   }
 
+  /**
+   * Make a stream/html request with validated input, returns raw Response
+   */
+  protected async streamRequest<TInput>(
+    route: string,
+    input: TInput
+  ): Promise<Response> {
+    const fetchFn = this.options.fetch || fetch;
+
+    return fetchFn(`${this.baseUrl}/${route}`, {
+      method: "POST",
+      headers: {
+        "Content-Type": "application/json",
+        ...this.options.headers,
+      },
+      credentials: this.options.credentials,
+      body: JSON.stringify(input),
+    });
+  }
+
+  /**
+   * Upload form data with files
+   */
+  protected async uploadFormData<TFields, TOutput>(
+    route: string,
+    fields: TFields,
+    files?: File[]
+  ): Promise<TOutput> {
+    const fetchFn = this.options.fetch || fetch;
+    const formData = new FormData();
+
+    // Add fields as JSON values
+    for (const [key, value] of Object.entries(fields as Record<string, any>)) {
+      formData.append(key, typeof value === "string" ? value : JSON.stringify(value));
+    }
+
+    // Add files
+    if (files) {
+      for (const file of files) {
+        formData.append("file", file);
+      }
+    }
+
+    const response = await fetchFn(`${this.baseUrl}/${route}`, {
+      method: "POST",
+      headers: {
+        ...this.options.headers,
+        // Don't set Content-Type - browser will set it with boundary
+      },
+      credentials: this.options.credentials,
+      body: formData,
+    });
+
+    if (!response.ok) {
+      const body = (await response.json().catch(() => ({}))) as Record<string, any>;
+      if (response.status === 400 && body.details?.issues) {
+        throw new ValidationError(body.details.issues);
+      }
+      throw new ApiError(response.status, body, body.message);
+    }
+
+    if (response.status === 204) {
+      return undefined as TOutput;
+    }
+
+    return response.json() as Promise<TOutput>;
+  }
+
   // ==========================================
   // SSE Connection Methods
   // ==========================================
 
+  /**
+   * Connect to a specific SSE route endpoint.
+   * Used by generated client methods for .sse() routes.
+   * @returns SSE subscription with typed event handlers
+   */
+  protected connectToSSERoute<TEvents extends Record<string, any>>(
+    route: string,
+    input: Record<string, any> = {},
+    options: Omit<SSEOptions, "endpoint" | "channels"> = {}
+  ): SSESubscription<TEvents> {
+    const url = new URL(`${this.baseUrl}/${route}`);
+
+    // Add input as query params
+    for (const [key, value] of Object.entries(input)) {
+      if (value !== undefined && value !== null) {
+        url.searchParams.set(key, typeof value === "string" ? value : JSON.stringify(value));
+      }
+    }
+
+    const eventSource = new EventSource(url.toString(), {
+      withCredentials: true,
+    });
+
+    const handlers = new Map<string, Set<(data: any) => void>>();
+    let onConnectCallback: (() => void) | undefined = options.onConnect;
+    let onDisconnectCallback: (() => void) | undefined = options.onDisconnect;
+    let onErrorCallback: ((error: Event) => void) | undefined = options.onError;
+    let reconnectTimeout: ReturnType<typeof setTimeout> | null = null;
+    const autoReconnect = options.autoReconnect ?? true;
+    const reconnectDelay = options.reconnectDelay ?? 3000;
+
+    const dispatchEvent = (eventName: string, rawData: string) => {
+      const eventHandlers = handlers.get(eventName);
+      if (!eventHandlers?.size) return;
+
+      let data: any;
+      try {
+        data = JSON.parse(rawData);
+      } catch {
+        data = rawData;
+      }
+
+      for (const handler of eventHandlers) {
+        try {
+          handler(data);
+        } catch (error) {
+          console.error(`Error in SSE event handler for "${eventName}":`, error);
+        }
+      }
+    };
+
+    const scheduleReconnect = () => {
+      if (reconnectTimeout) return;
+      reconnectTimeout = setTimeout(() => {
+        reconnectTimeout = null;
+        // Reconnect by creating new subscription
+        const newSub = this.connectToSSERoute<TEvents>(route, input, options);
+        // Transfer handlers
+        for (const [event, eventHandlers] of handlers) {
+          for (const handler of eventHandlers) {
+            newSub.on(event as keyof TEvents, handler);
+          }
+        }
+      }, reconnectDelay);
+    };
+
+    eventSource.onopen = () => {
+      onConnectCallback?.();
+    };
+
+    eventSource.onerror = (event) => {
+      onErrorCallback?.(event);
+      if (eventSource.readyState === 2) {
+        onDisconnectCallback?.();
+        if (autoReconnect) {
+          scheduleReconnect();
+        }
+      }
+    };
+
+    eventSource.onmessage = (event) => {
+      dispatchEvent("message", event.data);
+    };
+
+    const subscription: SSESubscription<TEvents> = {
+      on: <E extends keyof TEvents>(event: E, handler: (data: TEvents[E]) => void) => {
+        const eventName = String(event);
+        let eventHandlers = handlers.get(eventName);
+        if (!eventHandlers) {
+          eventHandlers = new Set();
+          handlers.set(eventName, eventHandlers);
+          // Add listener to EventSource
+          if (eventName !== "message") {
+            eventSource.addEventListener(eventName, (e) => {
+              if ("data" in e) {
+                dispatchEvent(eventName, (e as SSEMessageEvent).data);
+              }
+            });
+          }
+        }
+        eventHandlers.add(handler as (data: any) => void);
+        return () => {
+          eventHandlers?.delete(handler as (data: any) => void);
+        };
+      },
+      once: <E extends keyof TEvents>(event: E, handler: (data: TEvents[E]) => void) => {
+        const unsubscribe = subscription.on(event, (data) => {
+          unsubscribe();
+          handler(data);
+        });
+        return unsubscribe;
+      },
+      off: <E extends keyof TEvents>(event: E) => {
+        handlers.delete(String(event));
+      },
+      close: () => {
+        if (reconnectTimeout) {
+          clearTimeout(reconnectTimeout);
+          reconnectTimeout = null;
+        }
+        eventSource.close();
+        onDisconnectCallback?.();
+      },
+      get connected() {
+        return eventSource.readyState === 1;
+      },
+    };
+
+    return subscription;
+  }
+
   /**
    * Connect to SSE endpoint for real-time updates
    */

package/src/core.ts

@@ -1,5 +1,4 @@
 import { sql, type Kysely } from "kysely";
-import { existsSync } from "node:fs";
 import { readdir } from "node:fs/promises";
 import { join, dirname } from "node:path";
 import { fileURLToPath } from "node:url";
@@ -484,9 +483,8 @@ export class PluginManager {
 
     for (const service of coreServices) {
       const migrationDir = join(coreMigrationsDir, service);
-      if (existsSync(migrationDir)) {
-        await this.runMigrationsForPlugin(`@core/${service}`, migrationDir);
-      }
+      // runMigrationsForPlugin handles missing directories gracefully (ENOENT)
+      await this.runMigrationsForPlugin(`@core/${service}`, migrationDir);
     }
 
     console.log("Core migrations complete.");

package/src/generator/index.ts

@@ -440,7 +440,7 @@ export function generateClientCode(
     const namespaceName = prefix === "_root" ? "Root" : toPascalCase(prefix);
     const methodName = prefix === "_root" ? "_root" : prefix;
 
-    const typeEntries = prefixRoutes
+    const typedTypeEntries = prefixRoutes
       .filter((r) => r.handler === "typed")
       .map((r) => {
         const inputType = zodToTypeScript(r.inputSource);
@@ -453,6 +453,51 @@ export function generateClientCode(
     export type ${routeNs} = { Input: ${routeNs}.Input; Output: ${routeNs}.Output };`;
       });
 
+    const formDataTypeEntries = prefixRoutes
+      .filter((r) => r.handler === "formData")
+      .map((r) => {
+        const inputType = zodToTypeScript(r.inputSource);
+        const outputType = zodToTypeScript(r.outputSource);
+        const routeNs = toPascalCase(r.routeName);
+        return `    export namespace ${routeNs} {
+      export type Input = ${inputType};
+      export type Output = ${outputType};
+    }
+    export type ${routeNs} = { Input: ${routeNs}.Input; Output: ${routeNs}.Output };`;
+      });
+
+    const streamTypeEntries = prefixRoutes
+      .filter((r) => r.handler === "stream" || r.handler === "html")
+      .map((r) => {
+        const inputType = zodToTypeScript(r.inputSource);
+        const routeNs = toPascalCase(r.routeName);
+        return `    export namespace ${routeNs} {
+      export type Input = ${inputType};
+    }
+    export type ${routeNs} = { Input: ${routeNs}.Input };`;
+      });
+
+    const sseTypeEntries = prefixRoutes
+      .filter((r) => r.handler === "sse")
+      .map((r) => {
+        const inputType = zodToTypeScript(r.inputSource);
+        const routeNs = toPascalCase(r.routeName);
+        // Generate Events type from eventsSource
+        const eventsEntries = r.eventsSource
+          ? Object.entries(r.eventsSource)
+              .map(([eventName, eventType]) => `      "${eventName}": ${zodToTypeScript(eventType)};`)
+              .join("\n")
+          : "";
+        const eventsType = eventsEntries ? `{\n${eventsEntries}\n    }` : "Record<string, unknown>";
+        return `    export namespace ${routeNs} {
+      export type Input = ${inputType};
+      export type Events = ${eventsType};
+    }
+    export type ${routeNs} = { Input: ${routeNs}.Input; Events: ${routeNs}.Events };`;
+      });
+
+    const typeEntries = [...typedTypeEntries, ...formDataTypeEntries, ...streamTypeEntries, ...sseTypeEntries];
+
     if (typeEntries.length > 0) {
       routeTypeBlocks.push(`  export namespace ${namespaceName} {
 ${typeEntries.join("\n\n")}
@@ -475,7 +520,37 @@ ${typeEntries.join("\n\n")}
       this.rawRequest("${r.name}", init)`;
       });
 
-    const allMethods = [...methodEntries, ...rawMethodEntries];
+    const sseMethodEntries = prefixRoutes
+      .filter((r) => r.handler === "sse")
+      .map((r) => {
+        const inputType = r.inputSource
+          ? `Routes.${namespaceName}.${toPascalCase(r.routeName)}.Input`
+          : "Record<string, any>";
+        const eventsType = `Routes.${namespaceName}.${toPascalCase(r.routeName)}.Events`;
+        return `    ${toCamelCase(r.routeName)}: (input: ${inputType}, options?: Omit<SSEOptions, "endpoint" | "channels">): SSESubscription<${eventsType}> =>
+      this.connectToSSERoute("${r.name}", input, options)`;
+      });
+
+    const streamMethodEntries = prefixRoutes
+      .filter((r) => r.handler === "stream" || r.handler === "html")
+      .map((r) => {
+        const inputType = r.inputSource
+          ? `Routes.${namespaceName}.${toPascalCase(r.routeName)}.Input`
+          : "Record<string, any>";
+        return `    ${toCamelCase(r.routeName)}: (input: ${inputType}): Promise<Response> =>
+      this.streamRequest("${r.name}", input)`;
+      });
+
+    const formDataMethodEntries = prefixRoutes
+      .filter((r) => r.handler === "formData")
+      .map((r) => {
+        const inputType = `Routes.${namespaceName}.${toPascalCase(r.routeName)}.Input`;
+        const outputType = `Routes.${namespaceName}.${toPascalCase(r.routeName)}.Output`;
+        return `    ${toCamelCase(r.routeName)}: (fields: ${inputType}, files?: File[]): Promise<${outputType}> =>
+      this.uploadFormData("${r.name}", fields, files)`;
+      });
+
+    const allMethods = [...methodEntries, ...rawMethodEntries, ...sseMethodEntries, ...streamMethodEntries, ...formDataMethodEntries];
 
     if (allMethods.length > 0) {
       routeNamespaceBlocks.push(`  ${methodName} = {
@@ -512,6 +587,7 @@ import {
   type RequestOptions,
   type ApiClientOptions,
   type SSEOptions,
+  type SSESubscription,
 } from "./base";${additionalImportsStr}
 
 // ============================================
@@ -560,7 +636,7 @@ export function createApiClient(config: ApiClientConfig): ApiClient {
 }
 
 // Re-export base types for convenience
-export { ApiError, ValidationError, type RequestOptions, type SSEOptions };
+export { ApiError, ValidationError, type RequestOptions, type SSEOptions, type SSESubscription };
 `;
 }
 

package/src/server.ts

@@ -55,7 +55,10 @@ export interface TypeGenerationConfig {
 }
 
 export interface ServerConfig {
+  /** Server port. Can also be set via PORT environment variable. Default: 3000 */
   port?: number;
+  /** Maximum port attempts if port is in use. Default: 5 */
+  maxPortAttempts?: number;
   db: CoreServices["db"];
   config?: Record<string, any>;
   /** Auto-generate client types on startup in dev mode */
@@ -83,6 +86,7 @@ export interface ServerConfig {
 
 export class AppServer {
   private port: number;
+  private maxPortAttempts: number;
   private manager: PluginManager;
   private routers: IRouter[] = [];
   private routeMap: Map<string, RouteDefinition<keyof HandlerRegistry>> = new Map();
@@ -90,7 +94,10 @@ export class AppServer {
   private typeGenConfig?: TypeGenerationConfig;
 
   constructor(options: ServerConfig) {
-    this.port = options.port ?? 3000;
+    // Port priority: explicit config > PORT env var > default 3000
+    const envPort = process.env.PORT ? parseInt(process.env.PORT, 10) : undefined;
+    this.port = options.port ?? envPort ?? 3000;
+    this.maxPortAttempts = options.maxPortAttempts ?? 5;
 
     // Determine if we should use legacy databases
     const useLegacy = options.useLegacyCoreDatabases ?? false;
@@ -257,6 +264,46 @@ export class AppServer {
     return this.routeMap.has(routeName);
   }
 
+  /**
+   * Handle CLI type generation mode.
+   * Call this at the end of your server entry file after registering all routes.
+   * If DONKEYLABS_GENERATE=1 is set, outputs route metadata and exits.
+   * Otherwise, does nothing.
+   *
+   * @example
+   * ```ts
+   * server.use(routes);
+   * server.handleGenerateMode(); // Add this line at the end
+   * ```
+   */
+  handleGenerateMode(): void {
+    if (process.env.DONKEYLABS_GENERATE === "1") {
+      this.outputRoutesForGeneration();
+      process.exit(0);
+    }
+  }
+
+  /**
+   * Output route metadata as JSON for CLI type generation.
+   * Called when DONKEYLABS_GENERATE=1 environment variable is set.
+   */
+  private outputRoutesForGeneration(): void {
+    const routes = [];
+
+    for (const router of this.routers) {
+      for (const route of router.getRoutes()) {
+        routes.push({
+          name: route.name,
+          handler: route.handler || "typed",
+          inputType: route.input ? zodSchemaToTs(route.input) : undefined,
+          outputType: route.output ? zodSchemaToTs(route.output) : undefined,
+        });
+      }
+    }
+
+    console.log(JSON.stringify({ routes }));
+  }
+
   /**
    * Generate client types from registered routes.
    * Called automatically on startup in dev mode if generateTypes config is provided.
@@ -277,9 +324,10 @@ export class AppServer {
       name: string;
       prefix: string;
       routeName: string;
-      handler: "typed" | "raw";
+      handler: "typed" | "raw" | "sse" | "stream" | "formData" | "html";
       inputSource?: string;
       outputSource?: string;
+      eventsSource?: Record<string, string>;
     }> = [];
 
     const routesWithoutOutput: string[] = [];
@@ -295,13 +343,23 @@ export class AppServer {
           routesWithoutOutput.push(route.name);
         }
 
+        // Extract SSE event schemas
+        let eventsSource: Record<string, string> | undefined;
+        if (route.handler === "sse" && route.events) {
+          eventsSource = {};
+          for (const [eventName, eventSchema] of Object.entries(route.events)) {
+            eventsSource[eventName] = zodSchemaToTs(eventSchema as any);
+          }
+        }
+
         routes.push({
           name: route.name,
           prefix,
           routeName,
-          handler: (route.handler || "typed") as "typed" | "raw",
+          handler: (route.handler || "typed") as "typed" | "raw" | "sse" | "stream" | "formData" | "html",
           inputSource: route.input ? zodSchemaToTs(route.input) : undefined,
           outputSource: route.output ? zodSchemaToTs(route.output) : undefined,
+          eventsSource,
         });
       }
     }
@@ -336,9 +394,10 @@ export class AppServer {
       name: string;
       prefix: string;
       routeName: string;
-      handler: "typed" | "raw";
+      handler: "typed" | "raw" | "sse" | "stream" | "formData" | "html";
       inputSource?: string;
       outputSource?: string;
+      eventsSource?: Record<string, string>;
     }>
   ): string {
     const baseImport =
@@ -401,19 +460,43 @@ export function createApi(options?: ClientOptions) {
     // Recursive function to generate Type definitions
     function generateTypeBlock(node: RouteNode, indent: string): string {
       const blocks: string[] = [];
-      
+
       // 1. Valid Input/Output types for routes at this level
       if (node.routes.length > 0) {
         const routeTypes = node.routes.map(r => {
-           if (r.handler !== "typed") return "";
            const routeNs = toPascalCase(r.routeName);
            const inputType = r.inputSource ?? "Record<string, never>";
-           const outputType = r.outputSource ?? "void";
-           return `${indent}export namespace ${routeNs} {
+
+           if (r.handler === "typed" || r.handler === "formData") {
+             // typed and formData have Input and Output
+             const outputType = r.outputSource ?? "void";
+             return `${indent}export namespace ${routeNs} {
 ${indent}  export type Input = Expand<${inputType}>;
 ${indent}  export type Output = Expand<${outputType}>;
 ${indent}}
 ${indent}export type ${routeNs} = { Input: ${routeNs}.Input; Output: ${routeNs}.Output };`;
+           } else if (r.handler === "stream" || r.handler === "html") {
+             // stream and html have Input only (returns Response/string)
+             return `${indent}export namespace ${routeNs} {
+${indent}  export type Input = Expand<${inputType}>;
+${indent}}
+${indent}export type ${routeNs} = { Input: ${routeNs}.Input };`;
+           } else if (r.handler === "sse") {
+             // Generate Events type from eventsSource
+             const eventsEntries = r.eventsSource
+               ? Object.entries(r.eventsSource)
+                   .map(([eventName, eventType]) => `${indent}    "${eventName}": ${eventType};`)
+                   .join("\n")
+               : "";
+             const eventsType = eventsEntries ? `{\n${eventsEntries}\n${indent}  }` : "Record<string, unknown>";
+             return `${indent}export namespace ${routeNs} {
+${indent}  export type Input = Expand<${inputType}>;
+${indent}  export type Events = Expand<${eventsType}>;
+${indent}}
+${indent}export type ${routeNs} = { Input: ${routeNs}.Input; Events: ${routeNs}.Events };`;
+           }
+           // raw handler has no types
+           return "";
         }).filter(Boolean);
         if (routeTypes.length) blocks.push(routeTypes.join("\n\n"));
       }
@@ -434,15 +517,28 @@ ${indent}export type ${routeNs} = { Input: ${routeNs}.Input; Output: ${routeNs}.
       const methods = node.routes.map(r => {
          const methodName = toCamelCase(r.routeName);
          // r.name is the full path e.g. "api.v1.users.get"
-         
+         const pathParts = r.name.split(".");
+         const typePath = ["Routes", ...pathParts.slice(0, -1).map(toPascalCase), toPascalCase(r.routeName)];
+
          if (r.handler === "typed") {
-            const pathParts = r.name.split(".");
-            const typePath = ["Routes", ...pathParts.slice(0, -1).map(toPascalCase), toPascalCase(r.routeName)];
             const inputType = typePath.join(".") + ".Input";
             const outputType = typePath.join(".") + ".Output";
-            
             return `${indent}${methodName}: (input: ${inputType}): Promise<${outputType}> => this.request("${r.name}", input)`;
+         } else if (r.handler === "formData") {
+            const inputType = typePath.join(".") + ".Input";
+            const outputType = typePath.join(".") + ".Output";
+            // formData needs to send multipart form data
+            return `${indent}${methodName}: (fields: ${inputType}, files?: File[]): Promise<${outputType}> => this.uploadFormData("${r.name}", fields, files)`;
+         } else if (r.handler === "stream" || r.handler === "html") {
+            // stream and html have validated input but return Response
+            const inputType = typePath.join(".") + ".Input";
+            return `${indent}${methodName}: (input: ${inputType}): Promise<Response> => this.streamRequest("${r.name}", input)`;
+         } else if (r.handler === "sse") {
+            const inputType = typePath.join(".") + ".Input";
+            const eventsType = typePath.join(".") + ".Events";
+            return `${indent}${methodName}: (input: ${inputType}, options?: Omit<SSEOptions, "endpoint" | "channels">): SSESubscription<${eventsType}> => this.connectToSSERoute("${r.name}", input, options)`;
          } else {
+            // raw handler
             return `${indent}${methodName}: (init?: RequestInit): Promise<Response> => this.rawRequest("${r.name}", init)`;
          }
       });
@@ -468,10 +564,16 @@ ${indent}export type ${routeNs} = { Input: ${routeNs}.Input; Output: ${routeNs}.
     // rootNode children are top-level namespaces (api, health) -> Top Level Class Properties
     const methodBlocks: string[] = [generateMethodBlock(rootNode, "  ", "", true)];
 
+    // Check if we have any SSE routes to know if we need SSE type imports
+    const hasSSERoutes = routes.some(r => r.handler === "sse");
+    const sseImports = hasSSERoutes
+      ? '\nimport { type SSEOptions, type SSESubscription } from "@donkeylabs/server/client";'
+      : "";
+
     return `// Auto-generated by @donkeylabs/server
 // DO NOT EDIT MANUALLY
 
-${baseImport}
+${baseImport}${sseImports}
 
 // Utility type that forces TypeScript to expand types on hover
 type Expand<T> = T extends infer O ? { [K in keyof O]: O[K] } : never;
@@ -766,104 +868,137 @@ ${factoryFunction}
     }
     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);
+    // 5. Start HTTP server with port retry logic
+    const fetchHandler = async (req: Request, server: ReturnType<typeof Bun.serve>) => {
+      const url = new URL(req.url);
 
-        // Extract client IP
-        const ip = extractClientIP(req, server.requestIP(req)?.address);
+      // Extract client IP
+      const ip = extractClientIP(req, server.requestIP(req)?.address);
 
-        // Handle SSE endpoint
-        if (url.pathname === "/sse" && req.method === "GET") {
-          return this.handleSSE(req, ip);
-        }
+      // Handle SSE endpoint
+      if (url.pathname === "/sse" && req.method === "GET") {
+        return this.handleSSE(req, ip);
+      }
 
-        // Extract action from URL path (e.g., "auth.login")
-        const actionName = url.pathname.slice(1);
+      // Extract action from URL path (e.g., "auth.login")
+      const actionName = url.pathname.slice(1);
 
-        const route = this.routeMap.get(actionName);
-        if (route) {
-          const handlerType = route.handler || "typed";
+      const route = this.routeMap.get(actionName);
+      if (route) {
+        const handlerType = route.handler || "typed";
 
-          // Handlers that accept GET requests (for browser compatibility)
-          const getEnabledHandlers = ["stream", "sse", "html", "raw"];
+        // Handlers that accept GET requests (for browser compatibility)
+        const getEnabledHandlers = ["stream", "sse", "html", "raw"];
 
-          // Check method based on handler type
-          if (req.method === "GET" && !getEnabledHandlers.includes(handlerType)) {
-            return new Response("Method Not Allowed", { status: 405 });
-          }
-          if (req.method !== "GET" && req.method !== "POST") {
-            return new Response("Method Not Allowed", { status: 405 });
-          }
-          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;
-              }
+        // Check method based on handler type
+        if (req.method === "GET" && !getEnabledHandlers.includes(handlerType)) {
+          return new Response("Method Not Allowed", { status: 405 });
+        }
+        if (req.method !== "GET" && req.method !== "POST") {
+          return new Response("Method Not Allowed", { status: 405 });
+        }
+        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) {
-            // 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 as any, 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;
+        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 as any, 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();
             }
-          } else {
-            logger.error("Handler not found", { handler: type, route: actionName });
-            return new Response("Handler Not Found", { status: 500 });
+          } 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 });
         }
+      }
 
-        return new Response("Not Found", { status: 404 });
+      return new Response("Not Found", { status: 404 });
+    };
+
+    // Try to start server, retrying with different ports if port is in use
+    let currentPort = this.port;
+    let lastError: Error | null = null;
+
+    for (let attempt = 0; attempt < this.maxPortAttempts; attempt++) {
+      try {
+        Bun.serve({
+          port: currentPort,
+          fetch: fetchHandler,
+        });
+        // Update the actual port we're running on
+        this.port = currentPort;
+        logger.info(`Server running at http://localhost:${this.port}`);
+        return;
+      } catch (error) {
+        const isPortInUse =
+          error instanceof Error &&
+          (error.message.includes("EADDRINUSE") ||
+            error.message.includes("address already in use") ||
+            error.message.includes("port") && error.message.includes("in use"));
+
+        if (isPortInUse && attempt < this.maxPortAttempts - 1) {
+          logger.warn(`Port ${currentPort} is already in use, trying port ${currentPort + 1}...`);
+          currentPort++;
+          lastError = error as Error;
+        } else {
+          throw error;
+        }
       }
-    });
+    }
 
-    logger.info(`Server running at http://localhost:${this.port}`);
+    // If we get here, all attempts failed
+    throw new Error(
+      `Failed to start server after ${this.maxPortAttempts} attempts. ` +
+        `Ports ${this.port}-${currentPort} are all in use. ` +
+        `Last error: ${lastError?.message}`
+    );
   }
 
   /**