Merge pull request #487 from objectstack-ai/copilot/refactor-plugin-hono-server

xuyushun441-sys · web-flow · commit 080c48ea1819 · 2026-02-02T16:46:45.000+08:00
diff --git a/packages/plugins/plugin-hono-server/README.md b/packages/plugins/plugin-hono-server/README.md
@@ -77,9 +77,130 @@ interface HonoPluginOptions {
    * Path to static files directory (optional)
    */
   staticRoot?: string;
+  
+  /**
+   * REST server configuration
+   * Controls automatic endpoint generation and API behavior
+   */
+  restConfig?: RestServerConfig;
+  
+  /**
+   * Whether to register standard ObjectStack CRUD endpoints
+   * @default true
+   */
+  registerStandardEndpoints?: boolean;
+  
+  /**
+   * Whether to load endpoints from API Registry
+   * When enabled, routes are loaded dynamically from the API Registry
+   * When disabled, uses legacy static route registration
+   * @default true
+   */
+  useApiRegistry?: boolean;
 }
 ```
 
+### Using API Registry (New in v0.9.0)
+
+The plugin now integrates with the ObjectStack API Registry for centralized endpoint management:
+
+```typescript
+import { createApiRegistryPlugin } from '@objectstack/core';
+import { HonoServerPlugin } from '@objectstack/plugin-hono-server';
+
+const kernel = new ObjectKernel();
+
+// 1. Register API Registry Plugin first
+kernel.use(createApiRegistryPlugin({
+  conflictResolution: 'priority' // Handle route conflicts by priority
+}));
+
+// 2. Register Hono Server Plugin
+kernel.use(new HonoServerPlugin({
+  port: 3000,
+  useApiRegistry: true,
+  registerStandardEndpoints: true,
+  restConfig: {
+    api: {
+      version: 'v1',
+      basePath: '/api',
+      enableCrud: true,
+      enableMetadata: true,
+      enableBatch: true
+    }
+  }
+}));
+
+await kernel.bootstrap();
+```
+
+**Benefits of API Registry Integration:**
+- 📋 Centralized endpoint registration and discovery
+- 🔀 Priority-based route conflict resolution
+- 🧩 Support for plugin-registered custom endpoints
+- ⚙️ Configurable endpoint generation via `RestServerConfig`
+- 🔍 API introspection and documentation generation
+
+### Configuring REST Server Behavior
+
+Use `restConfig` to control which endpoints are automatically generated:
+
+```typescript
+new HonoServerPlugin({
+  restConfig: {
+    api: {
+      version: 'v2',
+      basePath: '/api',
+      enableCrud: true,
+      enableMetadata: true,
+      enableBatch: true,
+      enableDiscovery: true
+    },
+    crud: {
+      dataPrefix: '/data',
+      operations: {
+        create: true,
+        read: true,
+        update: true,
+        delete: true,
+        list: true
+      }
+    },
+    metadata: {
+      prefix: '/meta',
+      enableCache: true,
+      cacheTtl: 3600
+    },
+    batch: {
+      maxBatchSize: 200,
+      operations: {
+        createMany: true,
+        updateMany: true,
+        deleteMany: true,
+        upsertMany: true
+      }
+    }
+  }
+})
+```
+
+### Legacy Mode (Without API Registry)
+
+If the API Registry plugin is not registered, the server automatically falls back to legacy mode:
+
+```typescript
+// No API Registry needed for simple setups
+const kernel = new ObjectKernel();
+
+kernel.use(new HonoServerPlugin({
+  port: 3000,
+  useApiRegistry: false  // Explicitly disable API Registry
+}));
+
+await kernel.bootstrap();
+// All standard routes registered statically
+```
+
 ## API Endpoints
 
 The plugin automatically exposes the following ObjectStack REST API endpoints:
@@ -164,6 +285,60 @@ export class MyPlugin implements Plugin {
 }
 ```
 
+### Registering Custom Endpoints via API Registry
+
+Plugins can register their own endpoints through the API Registry:
+
+```typescript
+export class MyApiPlugin implements Plugin {
+  name = 'my-api-plugin';
+  version = '1.0.0';
+  
+  async init(ctx: PluginContext) {
+    const apiRegistry = ctx.getService<ApiRegistry>('api-registry');
+    
+    apiRegistry.registerApi({
+      id: 'my_custom_api',
+      name: 'My Custom API',
+      type: 'rest',
+      version: 'v1',
+      basePath: '/api/v1/custom',
+      endpoints: [
+        {
+          id: 'get_custom_data',
+          method: 'GET',
+          path: '/api/v1/custom/data',
+          summary: 'Get custom data',
+          priority: 500, // Lower than core endpoints (950)
+          responses: [{
+            statusCode: 200,
+            description: 'Custom data retrieved'
+          }]
+        }
+      ],
+      metadata: {
+        pluginSource: 'my-api-plugin',
+        status: 'active',
+        tags: ['custom']
+      }
+    });
+    
+    ctx.logger.info('Custom API endpoints registered');
+  }
+  
+  async start(ctx: PluginContext) {
+    // Bind the actual handler implementation
+    const httpServer = ctx.getService<IHttpServer>('http-server');
+    
+    httpServer.get('/api/v1/custom/data', async (req, res) => {
+      res.json({ data: 'my custom data' });
+    });
+  }
+}
+```
+
+**Note:** The Hono Server Plugin loads routes from the API Registry sorted by priority (highest first), ensuring core endpoints take precedence over plugin endpoints.
+
 ### Extending with Middleware
 
 The plugin provides extension points for adding custom middleware:
diff --git a/packages/plugins/plugin-hono-server/src/hono-plugin.test.ts b/packages/plugins/plugin-hono-server/src/hono-plugin.test.ts
@@ -1,11 +1,12 @@
 import { describe, it, expect, vi, beforeEach } from 'vitest';
 import { HonoServerPlugin } from './hono-plugin';
-import { PluginContext } from '@objectstack/core';
+import { PluginContext, ApiRegistry } from '@objectstack/core';
 
 describe('HonoServerPlugin', () => {
     let context: any;
     let logger: any;
     let protocol: any;
+    let apiRegistry: any;
 
     beforeEach(() => {
         logger = {
@@ -16,14 +17,38 @@ describe('HonoServerPlugin', () => {
         };
         
         protocol = {
-            findData: vi.fn(),
-            createData: vi.fn()
+            getDiscovery: vi.fn().mockResolvedValue({ version: 'v1', apiName: 'ObjectStack' }),
+            getMetaTypes: vi.fn().mockResolvedValue({ types: ['object', 'plugin'] }),
+            getMetaItems: vi.fn().mockResolvedValue({ type: 'object', items: [] }),
+            findData: vi.fn().mockResolvedValue({ object: 'test', records: [] }),
+            getData: vi.fn().mockResolvedValue({ object: 'test', id: '1', record: {} }),
+            createData: vi.fn().mockResolvedValue({ object: 'test', id: '1', record: {} }),
+            updateData: vi.fn().mockResolvedValue({ object: 'test', id: '1', record: {} }),
+            deleteData: vi.fn().mockResolvedValue({ object: 'test', id: '1', success: true }),
+            batchData: vi.fn().mockResolvedValue({ total: 0, succeeded: 0, failed: 0 }),
+            createManyData: vi.fn().mockResolvedValue({ object: 'test', records: [], count: 0 }),
+            updateManyData: vi.fn().mockResolvedValue({ total: 0, succeeded: 0, failed: 0 }),
+            deleteManyData: vi.fn().mockResolvedValue({ total: 0, succeeded: 0, failed: 0 }),
+            getMetaItemCached: vi.fn().mockResolvedValue({ data: {}, notModified: false }),
+            getUiView: vi.fn().mockResolvedValue({ object: 'test', type: 'list' })
+        };
+
+        apiRegistry = {
+            registerApi: vi.fn(),
+            getRegistry: vi.fn().mockReturnValue({
+                version: '1.0.0',
+                conflictResolution: 'error',
+                apis: [],
+                totalApis: 0,
+                totalEndpoints: 0
+            })
         };
 
         context = {
             logger,
             getService: vi.fn((service) => {
                 if (service === 'protocol') return protocol;
+                if (service === 'api-registry') throw new Error('Not found');
                 return null;
             }),
             registerService: vi.fn(),
@@ -47,11 +72,119 @@ describe('HonoServerPlugin', () => {
         expect(context.hook).toHaveBeenCalledWith('kernel:ready', expect.any(Function));
     });
 
-    it('should register CRUD routes', async () => {
+    it('should register CRUD routes in legacy mode when API Registry not available', async () => {
         const plugin = new HonoServerPlugin();
         await plugin.init(context as PluginContext);
         await plugin.start(context as PluginContext);
         
         expect(context.getService).toHaveBeenCalledWith('protocol');
+        expect(context.getService).toHaveBeenCalledWith('api-registry');
+        expect(logger.debug).toHaveBeenCalledWith('API Registry not found, using legacy route registration');
+    });
+
+    it('should use API Registry when available', async () => {
+        context.getService = vi.fn((service) => {
+            if (service === 'protocol') return protocol;
+            if (service === 'api-registry') return apiRegistry;
+            return null;
+        });
+
+        const plugin = new HonoServerPlugin();
+        await plugin.init(context as PluginContext);
+        await plugin.start(context as PluginContext);
+        
+        expect(context.getService).toHaveBeenCalledWith('api-registry');
+        expect(apiRegistry.registerApi).toHaveBeenCalled();
+    });
+
+    it('should register standard endpoints to API Registry', async () => {
+        context.getService = vi.fn((service) => {
+            if (service === 'protocol') return protocol;
+            if (service === 'api-registry') return apiRegistry;
+            return null;
+        });
+
+        const plugin = new HonoServerPlugin();
+        await plugin.init(context as PluginContext);
+        await plugin.start(context as PluginContext);
+        
+        expect(apiRegistry.registerApi).toHaveBeenCalledWith(
+            expect.objectContaining({
+                id: 'objectstack_core_api',
+                name: 'ObjectStack Core API',
+                type: 'rest',
+                version: 'v1'
+            })
+        );
+    });
+
+    it('should skip standard endpoint registration when disabled', async () => {
+        context.getService = vi.fn((service) => {
+            if (service === 'protocol') return protocol;
+            if (service === 'api-registry') return apiRegistry;
+            return null;
+        });
+
+        const plugin = new HonoServerPlugin({ registerStandardEndpoints: false });
+        await plugin.init(context as PluginContext);
+        await plugin.start(context as PluginContext);
+        
+        expect(apiRegistry.registerApi).not.toHaveBeenCalled();
+    });
+
+    it('should use legacy routes when useApiRegistry is disabled', async () => {
+        context.getService = vi.fn((service) => {
+            if (service === 'protocol') return protocol;
+            if (service === 'api-registry') return apiRegistry;
+            return null;
+        });
+
+        const plugin = new HonoServerPlugin({ useApiRegistry: false });
+        await plugin.init(context as PluginContext);
+        await plugin.start(context as PluginContext);
+        
+        expect(apiRegistry.getRegistry).not.toHaveBeenCalled();
+        expect(logger.debug).toHaveBeenCalledWith('Using legacy route registration');
+    });
+
+    it('should respect REST server configuration', async () => {
+        context.getService = vi.fn((service) => {
+            if (service === 'protocol') return protocol;
+            if (service === 'api-registry') return apiRegistry;
+            return null;
+        });
+
+        const plugin = new HonoServerPlugin({
+            restConfig: {
+                api: {
+                    version: 'v2',
+                    basePath: '/custom',
+                    enableCrud: true,
+                    enableMetadata: true,
+                    enableBatch: true
+                }
+            }
+        });
+        
+        await plugin.init(context as PluginContext);
+        await plugin.start(context as PluginContext);
+        
+        expect(apiRegistry.registerApi).toHaveBeenCalledWith(
+            expect.objectContaining({
+                version: 'v2'
+            })
+        );
+    });
+
+    it('should handle protocol service not found gracefully', async () => {
+        context.getService = vi.fn(() => {
+            throw new Error('Service not found');
+        });
+
+        const plugin = new HonoServerPlugin();
+        await plugin.init(context as PluginContext);
+        await plugin.start(context as PluginContext);
+        
+        expect(logger.warn).toHaveBeenCalledWith('Protocol service not found, skipping protocol routes');
     });
 });
diff --git a/packages/plugins/plugin-hono-server/src/hono-plugin.ts b/packages/plugins/plugin-hono-server/src/hono-plugin.ts
