fix: defer AuthPlugin route registration to kernel:ready hook and reorder HonoServerPlugin in CLI

Copilot · hotlong · Copilot · commit bac5f2906b06 · 2026-03-09T05:37:29.000Z
AuthPlugin now registers HTTP routes via a kernel:ready hook instead of
directly in start(). This makes it resilient to plugin loading order —
the http-server service is guaranteed to be available after all plugins
have completed their init/start phases.

The CLI serve command now registers HonoServerPlugin before config
plugins (with duplicate detection) so the http-server service is
available earlier in the lifecycle for any plugin that needs it.

Co-authored-by: hotlong &lt;50353452+hotlong@users.noreply.github.com&gt;
diff --git a/packages/cli/src/commands/serve.ts b/packages/cli/src/commands/serve.ts
@@ -200,7 +200,26 @@ export default class Serve extends Command {
         }
       }
 
-      
+      // Add HTTP server plugin BEFORE config plugins so that the
+      // http-server service is available for any plugin that needs it
+      // during init/start (e.g. AuthPlugin).
+      // Skip if config already contains a HonoServerPlugin to avoid
+      // duplicate registration.
+      const configHasHonoServer = plugins.some(
+        (p: any) => p.name === 'com.objectstack.server.hono' || p.constructor?.name === 'HonoServerPlugin'
+      );
+
+      if (flags.server && !configHasHonoServer) {
+        try {
+          const { HonoServerPlugin } = await import('@objectstack/plugin-hono-server');
+          const serverPlugin = new HonoServerPlugin({ port });
+          await kernel.use(serverPlugin);
+          trackPlugin('HonoServer');
+        } catch (e: any) {
+          console.warn(chalk.yellow(`  ⚠ HTTP server plugin not available: ${e.message}`));
+        }
+      }
+
       if (plugins.length > 0) {
         for (const plugin of plugins) {
           try {
@@ -236,18 +255,8 @@ export default class Serve extends Command {
         }
       }
 
-      // Add HTTP server plugin if not disabled
+      // Register REST API and Dispatcher plugins (consume http.server + protocol services)
       if (flags.server) {
-        try {
-          const { HonoServerPlugin } = await import('@objectstack/plugin-hono-server');
-          const serverPlugin = new HonoServerPlugin({ port });
-          await kernel.use(serverPlugin);
-          trackPlugin('HonoServer');
-        } catch (e: any) {
-          console.warn(chalk.yellow(`  ⚠ HTTP server plugin not available: ${e.message}`));
-        }
-
-        // Register REST API plugin (consumes http.server + protocol services)
         try {
           const { createRestApiPlugin } = await import('@objectstack/rest');
           await kernel.use(createRestApiPlugin());
diff --git a/packages/plugins/plugin-auth/src/auth-plugin.test.ts b/packages/plugins/plugin-auth/src/auth-plugin.test.ts
@@ -98,15 +98,36 @@ describe('AuthPlugin', () => {
   });
 
   describe('Start Phase', () => {
+    let hookHandlers: Map<string, Array<(...args: any[]) => Promise<void>>>;
+
     beforeEach(async () => {
+      hookHandlers = new Map();
       authPlugin = new AuthPlugin({
         secret: 'test-secret-at-least-32-chars-long',
         baseUrl: 'http://localhost:3000',
       });
+      // Capture hook registrations so we can trigger them in tests
+      mockContext.hook = vi.fn((name: string, handler: (...args: any[]) => Promise<void>) => {
+        if (!hookHandlers.has(name)) hookHandlers.set(name, []);
+        hookHandlers.get(name)!.push(handler);
+      });
       await authPlugin.init(mockContext);
     });
 
-    it('should register routes with HTTP server when enabled', async () => {
+    /** Helper: invoke all handlers registered for a given hook */
+    const triggerHook = async (name: string) => {
+      for (const handler of hookHandlers.get(name) || []) {
+        await handler();
+      }
+    };
+
+    it('should register a kernel:ready hook for route registration', async () => {
+      await authPlugin.start(mockContext);
+
+      expect(mockContext.hook).toHaveBeenCalledWith('kernel:ready', expect.any(Function));
+    });
+
+    it('should register routes with HTTP server on kernel:ready', async () => {
       const mockRawApp = {
         all: vi.fn(),
       };
@@ -128,6 +149,12 @@ describe('AuthPlugin', () => {
 
       await authPlugin.start(mockContext);
 
+      // Routes should NOT be registered yet (deferred to kernel:ready)
+      expect(mockRawApp.all).not.toHaveBeenCalled();
+
+      // Simulate kernel:ready
+      await triggerHook('kernel:ready');
+
       expect(mockContext.getService).toHaveBeenCalledWith('http-server');
       expect(mockHttpServer.getRawApp).toHaveBeenCalled();
       expect(mockRawApp.all).toHaveBeenCalledWith('/api/v1/auth/*', expect.any(Function));
@@ -157,6 +184,7 @@ describe('AuthPlugin', () => {
       });
 
       await authPlugin.start(mockContext);
+      await triggerHook('kernel:ready');
 
       // Extract the registered route handler
       const routeHandler = mockRawApp.all.mock.calls[0][1];
@@ -201,13 +229,15 @@ describe('AuthPlugin', () => {
       await authPlugin.init(mockContext);
       await authPlugin.start(mockContext);
 
-      expect(mockContext.getService).not.toHaveBeenCalledWith('http-server');
+      // Should not register kernel:ready hook for routes
+      expect(mockContext.hook).not.toHaveBeenCalledWith('kernel:ready', expect.any(Function));
     });
 
     it('should gracefully skip routes when http-server is not available', async () => {
       mockContext.getService = vi.fn(() => null);
 
       await authPlugin.start(mockContext);
+      await triggerHook('kernel:ready');
 
       expect(mockContext.getService).toHaveBeenCalledWith('http-server');
       expect(mockContext.logger.warn).toHaveBeenCalledWith(
@@ -222,6 +252,7 @@ describe('AuthPlugin', () => {
       });
 
       await authPlugin.start(mockContext);
+      await triggerHook('kernel:ready');
 
       expect(mockContext.logger.warn).toHaveBeenCalledWith(
         expect.stringContaining('No HTTP server available')
@@ -258,6 +289,12 @@ describe('AuthPlugin', () => {
 
   describe('Configuration Options', () => {
     it('should use custom base path', async () => {
+      const hookHandlers: Map<string, Array<(...args: any[]) => Promise<void>>> = new Map();
+      mockContext.hook = vi.fn((name: string, handler: (...args: any[]) => Promise<void>) => {
+        if (!hookHandlers.has(name)) hookHandlers.set(name, []);
+        hookHandlers.get(name)!.push(handler);
+      });
+
       authPlugin = new AuthPlugin({
         secret: 'test-secret-at-least-32-chars-long',
         baseUrl: 'http://localhost:3000',
@@ -284,6 +321,11 @@ describe('AuthPlugin', () => {
 
       await authPlugin.start(mockContext);
 
+      // Trigger kernel:ready to actually register routes
+      for (const handler of hookHandlers.get('kernel:ready') || []) {
+        await handler();
+      }
+
       expect(mockRawApp.all).toHaveBeenCalledWith(
         '/custom/auth/*',
         expect.any(Function)
diff --git a/packages/plugins/plugin-auth/src/auth-plugin.ts b/packages/plugins/plugin-auth/src/auth-plugin.ts
@@ -99,25 +99,31 @@ export class AuthPlugin implements Plugin {
       throw new Error('Auth manager not initialized');
     }
 
-    // Register HTTP routes if enabled and HTTP server is available
+    // Defer HTTP route registration to kernel:ready hook.
+    // This ensures all plugins (including HonoServerPlugin) have completed
+    // their init and start phases before we attempt to look up the
+    // http-server service — making AuthPlugin resilient to plugin
+    // loading order.
     if (this.options.registerRoutes) {
-      let httpServer: IHttpServer | null = null;
-      try {
-        httpServer = ctx.getService<IHttpServer>('http-server');
-      } catch {
-        // Service not found — expected in MSW/mock mode
-      }
+      ctx.hook('kernel:ready', async () => {
+        let httpServer: IHttpServer | null = null;
+        try {
+          httpServer = ctx.getService<IHttpServer>('http-server');
+        } catch {
+          // Service not found — expected in MSW/mock mode
+        }
 
-      if (httpServer) {
-        // Route registration errors should propagate (server misconfiguration)
-        this.registerAuthRoutes(httpServer, ctx);
-        ctx.logger.info(`Auth routes registered at ${this.options.basePath}`);
-      } else {
-        ctx.logger.warn(
-          'No HTTP server available — auth routes not registered. ' +
-          'Auth service is still available for MSW/mock environments via HttpDispatcher.'
-        );
-      }
+        if (httpServer) {
+          // Route registration errors should propagate (server misconfiguration)
+          this.registerAuthRoutes(httpServer, ctx);
+          ctx.logger.info(`Auth routes registered at ${this.options.basePath}`);
+        } else {
+          ctx.logger.warn(
+            'No HTTP server available — auth routes not registered. ' +
+            'Auth service is still available for MSW/mock environments via HttpDispatcher.'
+          );
+        }
+      });
     }
 
     // Register auth middleware on ObjectQL engine (if available)
