@donkeylabs/server 1.1.3 → 1.1.7

package/package.json

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

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/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.
@@ -766,104 +813,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 });
+    };
+
+    // Try to start server, retrying with different ports if port is in use
+    let currentPort = this.port;
+    let lastError: Error | null = null;
 
-        return new Response("Not Found", { status: 404 });
+    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}`
+    );
   }
 
   /**