@objectstack/plugin-hono-server 4.0.4 → 4.1.0

package/objectstack.config.ts

@@ -1,240 +0,0 @@
-// Copyright (c) 2025 ObjectStack. Licensed under the Apache-2.0 license.
-
-import { ObjectStackManifest } from '@objectstack/spec/system';
-
-/**
- * Hono Server Plugin Manifest
- * 
- * HTTP server adapter plugin using the Hono framework.
- * Provides northbound HTTP/REST API gateway capabilities.
- */
-const HonoServerPlugin: ObjectStackManifest = {
-  id: 'com.objectstack.server.hono',
-  name: 'Hono Server Adapter',
-  version: '1.0.0',
-  type: 'adapter',
-  description: 'HTTP server adapter using Hono framework. Exposes ObjectStack Runtime Protocol via REST API endpoints.',
-  
-  configuration: {
-    title: 'Hono Server Configuration',
-    properties: {
-      port: {
-        type: 'number',
-        default: 3000,
-        description: 'HTTP server port',
-      },
-      staticRoot: {
-        type: 'string',
-        description: 'Path to static files directory (optional)',
-      },
-    },
-  },
-
-  // Plugin Capability Declaration
-  capabilities: {
-    // Protocols This Plugin Implements
-    implements: [
-      {
-        protocol: {
-          id: 'com.objectstack.protocol.http.v1',
-          label: 'HTTP Server Protocol v1',
-          version: { major: 1, minor: 0, patch: 0 },
-          description: 'Standard HTTP server capabilities',
-        },
-        conformance: 'full',
-        certified: false,
-      },
-      {
-        protocol: {
-          id: 'com.objectstack.protocol.api.rest.v1',
-          label: 'REST API Protocol v1',
-          version: { major: 1, minor: 0, patch: 0 },
-          description: 'RESTful API endpoint implementation',
-        },
-        conformance: 'full',
-        features: [
-          {
-            name: 'meta_protocol',
-            enabled: true,
-            description: 'Metadata discovery endpoints',
-          },
-          {
-            name: 'data_protocol',
-            enabled: true,
-            description: 'CRUD data operations',
-          },
-          {
-            name: 'ui_protocol',
-            enabled: true,
-            description: 'UI view metadata endpoints',
-          },
-        ],
-        certified: false,
-      },
-    ],
-
-    // Interfaces This Plugin Provides
-    provides: [
-      {
-        id: 'com.objectstack.server.hono.interface.http_server',
-        name: 'IHttpServer',
-        description: 'HTTP server service interface',
-        version: { major: 1, minor: 0, patch: 0 },
-        stability: 'stable',
-        methods: [
-          {
-            name: 'get',
-            description: 'Register GET route handler',
-            parameters: [
-              {
-                name: 'path',
-                type: 'string',
-                required: true,
-                description: 'Route path pattern',
-              },
-              {
-                name: 'handler',
-                type: 'Function',
-                required: true,
-                description: 'Route handler function',
-              },
-            ],
-            returnType: 'void',
-            async: false,
-          },
-          {
-            name: 'post',
-            description: 'Register POST route handler',
-            parameters: [
-              {
-                name: 'path',
-                type: 'string',
-                required: true,
-                description: 'Route path pattern',
-              },
-              {
-                name: 'handler',
-                type: 'Function',
-                required: true,
-                description: 'Route handler function',
-              },
-            ],
-            returnType: 'void',
-            async: false,
-          },
-          {
-            name: 'patch',
-            description: 'Register PATCH route handler',
-            parameters: [
-              {
-                name: 'path',
-                type: 'string',
-                required: true,
-                description: 'Route path pattern',
-              },
-              {
-                name: 'handler',
-                type: 'Function',
-                required: true,
-                description: 'Route handler function',
-              },
-            ],
-            returnType: 'void',
-            async: false,
-          },
-          {
-            name: 'delete',
-            description: 'Register DELETE route handler',
-            parameters: [
-              {
-                name: 'path',
-                type: 'string',
-                required: true,
-                description: 'Route path pattern',
-              },
-              {
-                name: 'handler',
-                type: 'Function',
-                required: true,
-                description: 'Route handler function',
-              },
-            ],
-            returnType: 'void',
-            async: false,
-          },
-          {
-            name: 'listen',
-            description: 'Start the HTTP server',
-            parameters: [
-              {
-                name: 'port',
-                type: 'number',
-                required: true,
-                description: 'Port number',
-              },
-            ],
-            returnType: 'Promise<void>',
-            async: true,
-          },
-          {
-            name: 'close',
-            description: 'Stop the HTTP server',
-            parameters: [],
-            returnType: 'void',
-            async: false,
-          },
-        ],
-      },
-    ],
-
-    // Dependencies on Other Plugins/Services
-    requires: [
-      {
-        pluginId: 'com.objectstack.engine.objectql',
-        version: '^0.6.0',
-        optional: true,
-        reason: 'ObjectStack Runtime Protocol implementation service',
-        requiredCapabilities: [
-          'com.objectstack.protocol.runtime.v1',
-        ],
-      },
-    ],
-
-    // Extension Points This Plugin Defines
-    extensionPoints: [
-      {
-        id: 'com.objectstack.server.hono.extension.middleware',
-        name: 'HTTP Middleware',
-        description: 'Register custom HTTP middleware',
-        type: 'hook',
-        cardinality: 'multiple',
-        contract: {
-          signature: '(req: Request, res: Response, next: Function) => void | Promise<void>',
-        },
-      },
-      {
-        id: 'com.objectstack.server.hono.extension.route',
-        name: 'Custom Routes',
-        description: 'Register custom API routes',
-        type: 'action',
-        cardinality: 'multiple',
-        contract: {
-          input: 'RouteDefinition',
-          signature: '(app: HonoApp) => void',
-        },
-      },
-    ],
-
-    // No extensions contributed to other plugins
-    extensions: [],
-  },
-
-  contributes: {
-    // System Events
-    events: [
-      'kernel:ready',
-    ],
-  },
-};
-
-export default HonoServerPlugin;

package/src/adapter.ts

@@ -1,228 +0,0 @@
-// Copyright (c) 2025 ObjectStack. Licensed under the Apache-2.0 license.
-
-// Export IHttpServer from core
-export * from '@objectstack/core';
-
-import {
-    IHttpServer,
-    RouteHandler,
-    Middleware
-} from '@objectstack/core';
-import { Hono } from 'hono';
-import { serve } from '@hono/node-server';
-import { serveStatic } from '@hono/node-server/serve-static';
-
-export interface HonoCorsOptions {
-    enabled?: boolean;
-    origins?: string | string[];
-    methods?: string[];
-    credentials?: boolean;
-    maxAge?: number;
-}
-
-/**
- * Hono Implementation of IHttpServer
- */
-export class HonoHttpServer implements IHttpServer {
-    private app: Hono;
-    private server: any;
-    private listeningPort: number | undefined;
-
-    constructor(
-        private port: number = 3000,
-        private staticRoot?: string
-    ) {
-        this.app = new Hono();
-    }
-
-    // internal helper to convert standard handler to Hono handler
-    private wrap(handler: RouteHandler) {
-        return async (c: any) => {
-            let body: any = {};
-
-            // Try to parse JSON body first if content-type is JSON
-            if (c.req.header('content-type')?.includes('application/json')) {
-                try {
-                    body = await c.req.json();
-                } catch(e) {
-                    // If JSON parsing fails, try parseBody
-                    try {
-                        body = await c.req.parseBody();
-                    } catch(e2) {}
-                }
-            } else {
-                // For non-JSON content types, use parseBody
-                try {
-                    body = await c.req.parseBody();
-                } catch(e) {}
-            }
-
-            const req = {
-                params: c.req.param(),
-                query: c.req.query(),
-                body,
-                headers: c.req.header(),
-                method: c.req.method,
-                path: c.req.path
-            };
-
-            let capturedResponse: any;
-            let streamController: ReadableStreamDefaultController | null = null;
-            let streamEncoder: TextEncoder | null = null;
-            let streamHeaders: Record<string, string> = {};
-            let isStreaming = false;
-
-            const res = {
-                json: (data: any) => { capturedResponse = c.json(data); },
-                send: (data: string) => { capturedResponse = c.html(data); },
-                status: (code: number) => { c.status(code); return res; },
-                header: (name: string, value: string) => {
-                    c.header(name, value);
-                    streamHeaders[name] = value;
-                    return res;
-                },
-                write: (chunk: string | Uint8Array) => {
-                    isStreaming = true;
-                    if (streamController && streamEncoder) {
-                        const data = typeof chunk === 'string' ? streamEncoder.encode(chunk) : chunk;
-                        streamController.enqueue(data);
-                    }
-                },
-                end: () => {
-                    if (streamController) {
-                        streamController.close();
-                    }
-                },
-            };
-
-            // Create a streaming response wrapper — if handler calls res.write(),
-            // we return a ReadableStream; otherwise fall back to capturedResponse.
-            const streamPromise = new Promise<Response | null>((resolve) => {
-                const stream = new ReadableStream({
-                    start(controller) {
-                        streamController = controller;
-                        streamEncoder = new TextEncoder();
-                    },
-                });
-
-                // Run the handler; once it's done, check if streaming was used
-                const result = handler(req as any, res as any);
-                const done = result instanceof Promise ? result : Promise.resolve(result);
-                done.then(() => {
-                    if (isStreaming) {
-                        resolve(new Response(stream, {
-                            status: 200,
-                            headers: streamHeaders,
-                        }));
-                    } else {
-                        // Not streaming — close the unused stream and return null
-                        streamController?.close();
-                        resolve(null);
-                    }
-                }).catch(() => {
-                    streamController?.close();
-                    resolve(null);
-                });
-            });
-
-            const streamResponse = await streamPromise;
-            return streamResponse ?? capturedResponse;
-        };
-    }
-
-    get(path: string, handler: RouteHandler) {
-        this.app.get(path, this.wrap(handler));
-    }
-    post(path: string, handler: RouteHandler) {
-        this.app.post(path, this.wrap(handler));
-    }
-    put(path: string, handler: RouteHandler) {
-        this.app.put(path, this.wrap(handler));
-    }
-    delete(path: string, handler: RouteHandler) {
-        this.app.delete(path, this.wrap(handler));
-    }
-    patch(path: string, handler: RouteHandler) {
-        this.app.patch(path, this.wrap(handler));
-    }
-
-    use(pathOrHandler: string | Middleware, handler?: Middleware) {
-        if (typeof pathOrHandler === 'string' && handler) {
-             // Path based middleware
-             // Hono middleware signature is different (c, next) => ...
-             this.app.use(pathOrHandler, async (c, next) => {
-                 // Simplistic conversion
-                 await handler({} as any, {} as any, next);
-             });
-        } else if (typeof pathOrHandler === 'function') {
-             // Global middleware
-             this.app.use('*', async (c, next) => {
-                 await pathOrHandler({} as any, {} as any, next);
-             });
-        }
-    }
-
-    /**
-     * Mount a sub-application or router
-     */
-    mount(path: string, subApp: Hono) {
-        this.app.route(path, subApp);
-    }
-
-
-    async listen(port: number) {
-        if (this.staticRoot) {
-            this.app.get('/*', serveStatic({ root: this.staticRoot }));
-        }
-
-        const targetPort = port || this.port;
-        const maxRetries = 20;
-
-        for (let attempt = 0; attempt < maxRetries; attempt++) {
-            const tryPort = targetPort + attempt;
-            try {
-                await this.tryListen(tryPort);
-                return;
-            } catch (err: any) {
-                if (err.code === 'EADDRINUSE' && attempt < maxRetries - 1) {
-                    if (this.server && typeof this.server.close === 'function') {
-                        this.server.close();
-                    }
-                    continue;
-                }
-                throw err;
-            }
-        }
-    }
-
-    private tryListen(port: number): Promise<void> {
-        return new Promise<void>((resolve, reject) => {
-            const server = serve({
-                fetch: this.app.fetch,
-                port
-            }, (info) => {
-                this.listeningPort = info.port;
-                resolve();
-            });
-            this.server = server;
-            server.on('error', (err: any) => {
-                reject(err);
-            });
-        });
-    }
-
-    getPort() {
-        return this.listeningPort || this.port;
-    }
-
-    // Expose raw app for scenarios where standard interface is not enough
-    getRawApp() {
-        return this.app;
-    }
-
-    async close() {
-        if (this.server && typeof this.server.close === 'function') {
-            this.server.close();
-        }
-    }
-}

package/src/hono-plugin.test.ts

@@ -1,236 +0,0 @@
-import { describe, it, expect, vi, beforeEach } from 'vitest';
-import { HonoServerPlugin } from './hono-plugin';
-import { PluginContext } from '@objectstack/core';
-import { HonoHttpServer } from './adapter';
-
-vi.mock('fs', async (importOriginal) => {
-    const actual = await importOriginal<typeof import('fs')>();
-    return {
-        ...actual,
-        existsSync: vi.fn().mockReturnValue(true)
-    };
-});
-
-vi.mock('@hono/node-server/serve-static', () => ({
-    serveStatic: vi.fn(() => (c: any, next: any) => next())
-}));
-
-vi.mock('./adapter', () => ({
-    HonoHttpServer: vi.fn(function() {
-        return {
-            mount: vi.fn(),
-            start: vi.fn(),
-            stop: vi.fn(),
-            getApp: vi.fn(),
-            listen: vi.fn(),
-            getPort: vi.fn().mockReturnValue(3000),
-            close: vi.fn(),
-            getRawApp: vi.fn().mockReturnValue({
-                get: vi.fn(),
-                use: vi.fn(),
-            })
-        };
-    })
-}));
-
-describe('HonoServerPlugin', () => {
-    let context: any;
-    let logger: any;
-    let kernel: any;
-
-    beforeEach(() => {
-        vi.clearAllMocks();
-
-        logger = {
-            info: vi.fn(),
-            debug: vi.fn(),
-            warn: vi.fn(),
-            error: vi.fn()
-        };
-
-        kernel = {
-            getService: vi.fn(),
-        };
-
-        context = {
-            logger,
-            getKernel: vi.fn().mockReturnValue(kernel),
-            registerService: vi.fn(),
-            hook: vi.fn(),
-            getService: vi.fn()
-        };
-    });
-
-    it('should initialize and register server', async () => {
-        const plugin = new HonoServerPlugin();
-        await plugin.init(context as PluginContext);
-        
-        expect(context.registerService).toHaveBeenCalledWith('http-server', expect.any(Object));
-        expect(HonoHttpServer).toHaveBeenCalled();
-    });
-
-    it('should register IHttpServer service on init', async () => {
-        const plugin = new HonoServerPlugin();
-        await plugin.init(context as PluginContext);
-        
-        expect(context.registerService).toHaveBeenCalledWith('http.server', expect.any(Object));
-        expect(context.registerService).toHaveBeenCalledWith('http-server', expect.any(Object));
-    });
-
-    it('should start without errors', async () => {
-        const plugin = new HonoServerPlugin();
-        await plugin.init(context as PluginContext);
-        await plugin.start(context as PluginContext);
-        
-        // Plugin should register kernel:ready hook to start listening
-        expect(context.hook).toHaveBeenCalledWith('kernel:ready', expect.any(Function));
-    });
-
-    it('should handle errors gracefully on start', async () => {
-        // Simulate a start that doesn't crash even without routes
-        const plugin = new HonoServerPlugin();
-        await plugin.init(context as PluginContext);
-        await expect(plugin.start(context as PluginContext)).resolves.not.toThrow();
-    });
-
-    it('should configure static files and SPA fallback when enabled', async () => {
-        const plugin = new HonoServerPlugin({
-            staticRoot: './public',
-            spaFallback: true
-        });
-
-        await plugin.init(context as PluginContext);
-        await plugin.start(context as PluginContext);
-
-        const serverInstance = (HonoHttpServer as any).mock.instances[0];
-        const rawApp = serverInstance.getRawApp();
-        
-        expect(serverInstance.getRawApp).toHaveBeenCalled();
-        // Should register static files middleware
-        expect(rawApp.get).toHaveBeenCalledWith('/*', expect.anything());
-        // Should register SPA fallback middleware
-        expect(rawApp.get).toHaveBeenCalledWith('/*', expect.anything());
-    });
-
-    describe('CORS wildcard pattern matching', () => {
-        beforeEach(() => {
-            vi.clearAllMocks();
-        });
-
-        it('should enable CORS middleware with wildcard subdomain patterns', async () => {
-            const plugin = new HonoServerPlugin({
-                cors: {
-                    origins: ['https://*.objectui.org', 'https://*.objectstack.ai'],
-                    credentials: true
-                }
-            });
-
-            await plugin.init(context as PluginContext);
-
-            const serverInstance = (HonoHttpServer as any).mock.instances[0];
-            const rawApp = serverInstance.getRawApp();
-
-            // CORS middleware should be registered
-            expect(rawApp.use).toHaveBeenCalledWith('*', expect.any(Function));
-        });
-
-        it('should enable CORS middleware with port wildcard patterns', async () => {
-            const plugin = new HonoServerPlugin({
-                cors: {
-                    origins: 'http://localhost:*',
-                }
-            });
-
-            await plugin.init(context as PluginContext);
-
-            const serverInstance = (HonoHttpServer as any).mock.instances[0];
-            const rawApp = serverInstance.getRawApp();
-
-            expect(rawApp.use).toHaveBeenCalledWith('*', expect.any(Function));
-        });
-
-        it('should support comma-separated wildcard patterns', async () => {
-            const plugin = new HonoServerPlugin({
-                cors: {
-                    origins: 'https://*.objectui.org,https://*.objectstack.ai',
-                }
-            });
-
-            await plugin.init(context as PluginContext);
-
-            const serverInstance = (HonoHttpServer as any).mock.instances[0];
-            const rawApp = serverInstance.getRawApp();
-
-            expect(rawApp.use).toHaveBeenCalledWith('*', expect.any(Function));
-        });
-
-        it('should support exact origins without wildcards', async () => {
-            const plugin = new HonoServerPlugin({
-                cors: {
-                    origins: ['https://app.example.com', 'https://api.example.com'],
-                }
-            });
-
-            await plugin.init(context as PluginContext);
-
-            const serverInstance = (HonoHttpServer as any).mock.instances[0];
-            const rawApp = serverInstance.getRawApp();
-
-            expect(rawApp.use).toHaveBeenCalledWith('*', expect.any(Function));
-        });
-
-        it('should support CORS_ORIGIN environment variable with wildcards', async () => {
-            const originalEnv = process.env.CORS_ORIGIN;
-            process.env.CORS_ORIGIN = 'https://*.objectui.org,https://*.objectstack.ai';
-
-            const plugin = new HonoServerPlugin();
-            await plugin.init(context as PluginContext);
-
-            const serverInstance = (HonoHttpServer as any).mock.instances[0];
-            const rawApp = serverInstance.getRawApp();
-
-            expect(rawApp.use).toHaveBeenCalledWith('*', expect.any(Function));
-
-            // Restore environment
-            if (originalEnv !== undefined) {
-                process.env.CORS_ORIGIN = originalEnv;
-            } else {
-                delete process.env.CORS_ORIGIN;
-            }
-        });
-
-        it('should disable CORS when cors option is false', async () => {
-            const plugin = new HonoServerPlugin({
-                cors: false
-            });
-
-            await plugin.init(context as PluginContext);
-
-            const serverInstance = (HonoHttpServer as any).mock.instances[0];
-            const rawApp = serverInstance.getRawApp();
-
-            // CORS middleware should NOT be registered
-            expect(rawApp.use).not.toHaveBeenCalled();
-        });
-
-        it('should disable CORS when CORS_ENABLED env is false', async () => {
-            const originalEnv = process.env.CORS_ENABLED;
-            process.env.CORS_ENABLED = 'false';
-
-            const plugin = new HonoServerPlugin();
-            await plugin.init(context as PluginContext);
-
-            const serverInstance = (HonoHttpServer as any).mock.instances[0];
-            const rawApp = serverInstance.getRawApp();
-
-            expect(rawApp.use).not.toHaveBeenCalled();
-
-            // Restore environment
-            if (originalEnv !== undefined) {
-                process.env.CORS_ENABLED = originalEnv;
-            } else {
-                delete process.env.CORS_ENABLED;
-            }
-        });
-    });
-});