@objectstack/runtime 0.6.1 → 0.7.1

package/dist/route-manager.d.ts

@@ -0,0 +1,153 @@
+import { RouteHandler, IHttpServer } from '@objectstack/core';
+import { System, Shared } from '@objectstack/spec';
+type RouteHandlerMetadata = System.RouteHandlerMetadata;
+type HttpMethod = Shared.HttpMethod;
+/**
+ * Route Entry
+ * Internal representation of registered routes
+ */
+export interface RouteEntry {
+    method: HttpMethod;
+    path: string;
+    handler: RouteHandler;
+    metadata?: RouteHandlerMetadata['metadata'];
+    security?: RouteHandlerMetadata['security'];
+}
+/**
+ * RouteManager
+ *
+ * Manages route registration and organization for HTTP servers.
+ * Provides:
+ * - Route registration with metadata
+ * - Route lookup and querying
+ * - Bulk route registration
+ * - Route grouping by prefix
+ *
+ * @example
+ * const manager = new RouteManager(server);
+ *
+ * // Register individual route
+ * manager.register({
+ *   method: 'GET',
+ *   path: '/api/users/:id',
+ *   handler: getUserHandler,
+ *   metadata: {
+ *     summary: 'Get user by ID',
+ *     tags: ['users']
+ *   }
+ * });
+ *
+ * // Register route group
+ * manager.group('/api/users', (group) => {
+ *   group.get('/', listUsersHandler);
+ *   group.post('/', createUserHandler);
+ *   group.get('/:id', getUserHandler);
+ * });
+ */
+export declare class RouteManager {
+    private server;
+    private routes;
+    constructor(server: IHttpServer);
+    /**
+     * Register a route
+     * @param entry - Route entry with method, path, handler, and metadata
+     */
+    register(entry: Omit<RouteEntry, 'handler'> & {
+        handler: RouteHandler | string;
+    }): void;
+    /**
+     * Register multiple routes
+     * @param entries - Array of route entries
+     */
+    registerMany(entries: Array<Omit<RouteEntry, 'handler'> & {
+        handler: RouteHandler | string;
+    }>): void;
+    /**
+     * Unregister a route
+     * @param method - HTTP method
+     * @param path - Route path
+     */
+    unregister(method: HttpMethod, path: string): void;
+    /**
+     * Get route by method and path
+     * @param method - HTTP method
+     * @param path - Route path
+     */
+    get(method: HttpMethod, path: string): RouteEntry | undefined;
+    /**
+     * Get all routes
+     */
+    getAll(): RouteEntry[];
+    /**
+     * Get routes by method
+     * @param method - HTTP method
+     */
+    getByMethod(method: HttpMethod): RouteEntry[];
+    /**
+     * Get routes by path prefix
+     * @param prefix - Path prefix
+     */
+    getByPrefix(prefix: string): RouteEntry[];
+    /**
+     * Get routes by tag
+     * @param tag - Tag name
+     */
+    getByTag(tag: string): RouteEntry[];
+    /**
+     * Create a route group with common prefix
+     * @param prefix - Common path prefix
+     * @param configure - Function to configure routes in the group
+     */
+    group(prefix: string, configure: (group: RouteGroupBuilder) => void): void;
+    /**
+     * Get route count
+     */
+    count(): number;
+    /**
+     * Clear all routes
+     */
+    clear(): void;
+    /**
+     * Get route key for storage
+     */
+    private getRouteKey;
+    /**
+     * Register route with underlying server
+     */
+    private registerWithServer;
+}
+/**
+ * RouteGroupBuilder
+ *
+ * Builder for creating route groups with common prefix
+ */
+export declare class RouteGroupBuilder {
+    private manager;
+    private prefix;
+    constructor(manager: RouteManager, prefix: string);
+    /**
+     * Register GET route in group
+     */
+    get(path: string, handler: RouteHandler, metadata?: RouteHandlerMetadata['metadata']): this;
+    /**
+     * Register POST route in group
+     */
+    post(path: string, handler: RouteHandler, metadata?: RouteHandlerMetadata['metadata']): this;
+    /**
+     * Register PUT route in group
+     */
+    put(path: string, handler: RouteHandler, metadata?: RouteHandlerMetadata['metadata']): this;
+    /**
+     * Register PATCH route in group
+     */
+    patch(path: string, handler: RouteHandler, metadata?: RouteHandlerMetadata['metadata']): this;
+    /**
+     * Register DELETE route in group
+     */
+    delete(path: string, handler: RouteHandler, metadata?: RouteHandlerMetadata['metadata']): this;
+    /**
+     * Resolve full path with prefix
+     */
+    private resolvePath;
+}
+export {};

package/dist/route-manager.js

@@ -0,0 +1,251 @@
+/**
+ * RouteManager
+ *
+ * Manages route registration and organization for HTTP servers.
+ * Provides:
+ * - Route registration with metadata
+ * - Route lookup and querying
+ * - Bulk route registration
+ * - Route grouping by prefix
+ *
+ * @example
+ * const manager = new RouteManager(server);
+ *
+ * // Register individual route
+ * manager.register({
+ *   method: 'GET',
+ *   path: '/api/users/:id',
+ *   handler: getUserHandler,
+ *   metadata: {
+ *     summary: 'Get user by ID',
+ *     tags: ['users']
+ *   }
+ * });
+ *
+ * // Register route group
+ * manager.group('/api/users', (group) => {
+ *   group.get('/', listUsersHandler);
+ *   group.post('/', createUserHandler);
+ *   group.get('/:id', getUserHandler);
+ * });
+ */
+export class RouteManager {
+    constructor(server) {
+        this.server = server;
+        this.routes = new Map();
+    }
+    /**
+     * Register a route
+     * @param entry - Route entry with method, path, handler, and metadata
+     */
+    register(entry) {
+        // Validate handler type - string handlers not yet supported
+        if (typeof entry.handler === 'string') {
+            throw new Error(`String-based route handlers are not supported yet. ` +
+                `Received handler identifier "${entry.handler}". ` +
+                `Please provide a RouteHandler function instead.`);
+        }
+        const handler = entry.handler;
+        const routeEntry = {
+            method: entry.method,
+            path: entry.path,
+            handler,
+            metadata: entry.metadata,
+            security: entry.security,
+        };
+        const key = this.getRouteKey(entry.method, entry.path);
+        this.routes.set(key, routeEntry);
+        // Register with underlying server
+        this.registerWithServer(routeEntry);
+    }
+    /**
+     * Register multiple routes
+     * @param entries - Array of route entries
+     */
+    registerMany(entries) {
+        entries.forEach(entry => this.register(entry));
+    }
+    /**
+     * Unregister a route
+     * @param method - HTTP method
+     * @param path - Route path
+     */
+    unregister(method, path) {
+        const key = this.getRouteKey(method, path);
+        this.routes.delete(key);
+        // Note: Most server frameworks don't support unregistering routes at runtime
+        // This just removes it from our registry
+    }
+    /**
+     * Get route by method and path
+     * @param method - HTTP method
+     * @param path - Route path
+     */
+    get(method, path) {
+        const key = this.getRouteKey(method, path);
+        return this.routes.get(key);
+    }
+    /**
+     * Get all routes
+     */
+    getAll() {
+        return Array.from(this.routes.values());
+    }
+    /**
+     * Get routes by method
+     * @param method - HTTP method
+     */
+    getByMethod(method) {
+        return this.getAll().filter(route => route.method === method);
+    }
+    /**
+     * Get routes by path prefix
+     * @param prefix - Path prefix
+     */
+    getByPrefix(prefix) {
+        return this.getAll().filter(route => route.path.startsWith(prefix));
+    }
+    /**
+     * Get routes by tag
+     * @param tag - Tag name
+     */
+    getByTag(tag) {
+        return this.getAll().filter(route => route.metadata?.tags?.includes(tag));
+    }
+    /**
+     * Create a route group with common prefix
+     * @param prefix - Common path prefix
+     * @param configure - Function to configure routes in the group
+     */
+    group(prefix, configure) {
+        const builder = new RouteGroupBuilder(this, prefix);
+        configure(builder);
+    }
+    /**
+     * Get route count
+     */
+    count() {
+        return this.routes.size;
+    }
+    /**
+     * Clear all routes
+     */
+    clear() {
+        this.routes.clear();
+    }
+    /**
+     * Get route key for storage
+     */
+    getRouteKey(method, path) {
+        return `${method}:${path}`;
+    }
+    /**
+     * Register route with underlying server
+     */
+    registerWithServer(entry) {
+        const { method, path, handler } = entry;
+        switch (method) {
+            case 'GET':
+                this.server.get(path, handler);
+                break;
+            case 'POST':
+                this.server.post(path, handler);
+                break;
+            case 'PUT':
+                this.server.put(path, handler);
+                break;
+            case 'DELETE':
+                this.server.delete(path, handler);
+                break;
+            case 'PATCH':
+                this.server.patch(path, handler);
+                break;
+            default:
+                throw new Error(`Unsupported HTTP method: ${method}`);
+        }
+    }
+}
+/**
+ * RouteGroupBuilder
+ *
+ * Builder for creating route groups with common prefix
+ */
+export class RouteGroupBuilder {
+    constructor(manager, prefix) {
+        this.manager = manager;
+        this.prefix = prefix;
+    }
+    /**
+     * Register GET route in group
+     */
+    get(path, handler, metadata) {
+        this.manager.register({
+            method: 'GET',
+            path: this.resolvePath(path),
+            handler,
+            metadata,
+        });
+        return this;
+    }
+    /**
+     * Register POST route in group
+     */
+    post(path, handler, metadata) {
+        this.manager.register({
+            method: 'POST',
+            path: this.resolvePath(path),
+            handler,
+            metadata,
+        });
+        return this;
+    }
+    /**
+     * Register PUT route in group
+     */
+    put(path, handler, metadata) {
+        this.manager.register({
+            method: 'PUT',
+            path: this.resolvePath(path),
+            handler,
+            metadata,
+        });
+        return this;
+    }
+    /**
+     * Register PATCH route in group
+     */
+    patch(path, handler, metadata) {
+        this.manager.register({
+            method: 'PATCH',
+            path: this.resolvePath(path),
+            handler,
+            metadata,
+        });
+        return this;
+    }
+    /**
+     * Register DELETE route in group
+     */
+    delete(path, handler, metadata) {
+        this.manager.register({
+            method: 'DELETE',
+            path: this.resolvePath(path),
+            handler,
+            metadata,
+        });
+        return this;
+    }
+    /**
+     * Resolve full path with prefix
+     */
+    resolvePath(path) {
+        // Normalize slashes
+        const normalizedPrefix = this.prefix.endsWith('/')
+            ? this.prefix.slice(0, -1)
+            : this.prefix;
+        const normalizedPath = path.startsWith('/')
+            ? path
+            : '/' + path;
+        return normalizedPrefix + normalizedPath;
+    }
+}

package/package.json

@@ -1,14 +1,14 @@
 {
   "name": "@objectstack/runtime",
-  "version": "0.6.1",
+  "version": "0.7.1",
   "description": "ObjectStack Core Runtime & Query Engine",
   "type": "module",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
   "dependencies": {
-    "@objectstack/core": "0.6.1",
-    "@objectstack/types": "0.6.1",
-    "@objectstack/spec": "0.6.1"
+    "@objectstack/core": "0.7.1",
+    "@objectstack/types": "0.7.1",
+    "@objectstack/spec": "0.7.1"
   },
   "devDependencies": {
     "typescript": "^5.0.0"

package/src/app-plugin.ts

@@ -29,41 +29,72 @@ export class AppPlugin implements Plugin {
         const sys = this.bundle.manifest || this.bundle;
         const appId = sys.id || sys.name;
 
-        ctx.logger?.log(`[AppPlugin] Registering App Service: ${appId}`);
+        ctx.logger.info('Registering App Service', { 
+            appId, 
+            pluginName: this.name,
+            version: this.version 
+        });
         
         // Register the app manifest as a service
         // ObjectQLPlugin will discover this and call ql.registerApp()
         const serviceName = `app.${appId}`;
-        ctx.registerService(serviceName, this.bundle.manifest || this.bundle);
+
+        // Merge manifest with the bundle to ensure objects/apps are accessible at root
+        // This supports both Legacy Manifests and new Stack Definitions
+        const servicePayload = this.bundle.manifest 
+            ? { ...this.bundle.manifest, ...this.bundle }
+            : this.bundle;
+
+        ctx.registerService(serviceName, servicePayload);
     }
 
     async start(ctx: PluginContext) {
+        const sys = this.bundle.manifest || this.bundle;
+        const appId = sys.id || sys.name;
+        
         // Execute Runtime Step
         // Retrieve ObjectQL engine from services
         // We cast to any/ObjectQL because ctx.getService returns unknown
         const ql = ctx.getService('objectql') as any;
         
         if (!ql) {
-            ctx.logger?.warn(`[AppPlugin] ObjectQL engine service not found for app: ${this.name}`);
+            ctx.logger.warn('ObjectQL engine service not found', { 
+                appName: this.name,
+                appId 
+            });
             return;
         }
 
+        ctx.logger.debug('Retrieved ObjectQL engine service', { appId });
+
         const runtime = this.bundle.default || this.bundle;
         
         if (runtime && typeof runtime.onEnable === 'function') {
-             ctx.logger?.log(`[AppPlugin] Executing runtime.onEnable for: ${this.name}`);
+             ctx.logger.info('Executing runtime.onEnable', { 
+                 appName: this.name,
+                 appId 
+             });
              
              // Construct the Host Context (mirroring old ObjectQL.use logic)
              const hostContext = {
                 ...ctx,
                 ql,
-                logger: ctx.logger || console,
+                logger: ctx.logger,
                 drivers: {
-                    register: (driver: any) => ql.registerDriver(driver)
+                    register: (driver: any) => {
+                        ctx.logger.debug('Registering driver via app runtime', { 
+                            driverName: driver.name,
+                            appId 
+                        });
+                        ql.registerDriver(driver);
+                    }
                 },
              };
              
              await runtime.onEnable(hostContext);
+             ctx.logger.debug('Runtime.onEnable completed', { appId });
+        } else {
+             ctx.logger.debug('No runtime.onEnable function found', { appId });
         }
     }
 }

package/src/driver-plugin.ts

@@ -30,11 +30,15 @@ export class DriverPlugin implements Plugin {
         // Register driver as a service instead of directly to objectql
         const serviceName = `driver.${this.driver.name || 'unknown'}`;
         ctx.registerService(serviceName, this.driver);
-        ctx.logger.log(`[DriverPlugin] Registered driver service: ${serviceName}`);
+        ctx.logger.info('Driver service registered', { 
+            serviceName, 
+            driverName: this.driver.name,
+            driverVersion: this.driver.version 
+        });
     }
 
     async start(ctx: PluginContext) {
         // Drivers don't need start phase, initialization happens in init
-        ctx.logger.log(`[DriverPlugin] Driver ready: ${this.driver.name || 'unknown'}`);
+        ctx.logger.debug('Driver plugin started', { driverName: this.driver.name || 'unknown' });
     }
 }

package/src/http-server.ts

@@ -0,0 +1,140 @@
+import { IHttpServer, RouteHandler, Middleware } from '@objectstack/core';
+
+/**
+ * HttpServer - Unified HTTP Server Abstraction
+ * 
+ * Provides a framework-agnostic HTTP server interface that wraps
+ * underlying server implementations (Hono, Express, Fastify, etc.)
+ * 
+ * This class serves as an adapter between the IHttpServer interface
+ * and concrete server implementations, allowing plugins to register
+ * routes and middleware without depending on specific frameworks.
+ * 
+ * Features:
+ * - Unified route registration API
+ * - Middleware management with ordering
+ * - Request/response lifecycle hooks
+ * - Framework-agnostic abstractions
+ */
+export class HttpServer implements IHttpServer {
+    protected server: IHttpServer;
+    protected routes: Map<string, RouteHandler>;
+    protected middlewares: Middleware[];
+    
+    /**
+     * Create an HTTP server wrapper
+     * @param server - The underlying server implementation (Hono, Express, etc.)
+     */
+    constructor(server: IHttpServer) {
+        this.server = server;
+        this.routes = new Map();
+        this.middlewares = [];
+    }
+    
+    /**
+     * Register a GET route handler
+     * @param path - Route path (e.g., '/api/users/:id')
+     * @param handler - Route handler function
+     */
+    get(path: string, handler: RouteHandler): void {
+        const key = `GET:${path}`;
+        this.routes.set(key, handler);
+        this.server.get(path, handler);
+    }
+    
+    /**
+     * Register a POST route handler
+     * @param path - Route path
+     * @param handler - Route handler function
+     */
+    post(path: string, handler: RouteHandler): void {
+        const key = `POST:${path}`;
+        this.routes.set(key, handler);
+        this.server.post(path, handler);
+    }
+    
+    /**
+     * Register a PUT route handler
+     * @param path - Route path
+     * @param handler - Route handler function
+     */
+    put(path: string, handler: RouteHandler): void {
+        const key = `PUT:${path}`;
+        this.routes.set(key, handler);
+        this.server.put(path, handler);
+    }
+    
+    /**
+     * Register a DELETE route handler
+     * @param path - Route path
+     * @param handler - Route handler function
+     */
+    delete(path: string, handler: RouteHandler): void {
+        const key = `DELETE:${path}`;
+        this.routes.set(key, handler);
+        this.server.delete(path, handler);
+    }
+    
+    /**
+     * Register a PATCH route handler
+     * @param path - Route path
+     * @param handler - Route handler function
+     */
+    patch(path: string, handler: RouteHandler): void {
+        const key = `PATCH:${path}`;
+        this.routes.set(key, handler);
+        this.server.patch(path, handler);
+    }
+    
+    /**
+     * Register middleware
+     * @param path - Optional path to apply middleware to (if omitted, applies globally)
+     * @param handler - Middleware function
+     */
+    use(path: string | Middleware, handler?: Middleware): void {
+        if (typeof path === 'function') {
+            // Global middleware
+            this.middlewares.push(path);
+            this.server.use(path);
+        } else if (handler) {
+            // Path-specific middleware
+            this.middlewares.push(handler);
+            this.server.use(path, handler);
+        }
+    }
+    
+    /**
+     * Start the HTTP server
+     * @param port - Port number to listen on
+     * @returns Promise that resolves when server is ready
+     */
+    async listen(port: number): Promise<void> {
+        await this.server.listen(port);
+    }
+    
+    /**
+     * Stop the HTTP server
+     * @returns Promise that resolves when server is stopped
+     */
+    async close(): Promise<void> {
+        if (this.server.close) {
+            await this.server.close();
+        }
+    }
+    
+    /**
+     * Get registered routes
+     * @returns Map of route keys to handlers
+     */
+    getRoutes(): Map<string, RouteHandler> {
+        return new Map(this.routes);
+    }
+    
+    /**
+     * Get registered middlewares
+     * @returns Array of middleware functions
+     */
+    getMiddlewares(): Middleware[] {
+        return [...this.middlewares];
+    }
+}

package/src/index.ts

@@ -2,10 +2,17 @@
 export { ObjectKernel } from '@objectstack/core';
 
 // Export Plugins
-export { DriverPlugin } from './driver-plugin';
-export { AppPlugin } from './app-plugin';
+export { DriverPlugin } from './driver-plugin.js';
+export { AppPlugin } from './app-plugin.js';
+
+// Export HTTP Server Components
+export { HttpServer } from './http-server.js';
+export { RestServer } from './rest-server.js';
+export { RouteManager, RouteGroupBuilder } from './route-manager.js';
+export { MiddlewareManager } from './middleware.js';
 
 // Export Types
 export * from '@objectstack/core';
 
 
+