@objectstack/runtime 1.0.4 → 1.0.5

package/dist/index.cjs

@@ -0,0 +1,1586 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __reExport = (target, mod, secondTarget) => (__copyProps(target, mod, "default"), secondTarget && __copyProps(secondTarget, mod, "default"));
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var index_exports = {};
+__export(index_exports, {
+  AppPlugin: () => AppPlugin,
+  DriverPlugin: () => DriverPlugin,
+  HttpDispatcher: () => HttpDispatcher,
+  HttpServer: () => HttpServer,
+  MiddlewareManager: () => MiddlewareManager,
+  ObjectKernel: () => import_core3.ObjectKernel,
+  RestServer: () => RestServer,
+  RouteGroupBuilder: () => RouteGroupBuilder,
+  RouteManager: () => RouteManager,
+  Runtime: () => Runtime,
+  createApiRegistryPlugin: () => createApiRegistryPlugin
+});
+module.exports = __toCommonJS(index_exports);
+var import_core3 = require("@objectstack/core");
+
+// src/runtime.ts
+var import_core = require("@objectstack/core");
+
+// src/route-manager.ts
+var RouteManager = class {
+  constructor(server) {
+    this.server = server;
+    this.routes = /* @__PURE__ */ new Map();
+  }
+  /**
+   * Register a route
+   * @param entry - Route entry with method, path, handler, and metadata
+   */
+  register(entry) {
+    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);
+    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);
+  }
+  /**
+   * 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}`);
+    }
+  }
+};
+var RouteGroupBuilder = class {
+  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) {
+    const normalizedPrefix = this.prefix.endsWith("/") ? this.prefix.slice(0, -1) : this.prefix;
+    const normalizedPath = path.startsWith("/") ? path : "/" + path;
+    return normalizedPrefix + normalizedPath;
+  }
+};
+
+// src/rest-server.ts
+var RestServer = class {
+  constructor(server, protocol, config = {}) {
+    this.protocol = protocol;
+    this.config = this.normalizeConfig(config);
+    this.routeManager = new RouteManager(server);
+  }
+  /**
+   * Normalize configuration with defaults
+   */
+  normalizeConfig(config) {
+    const api = config.api ?? {};
+    const crud = config.crud ?? {};
+    const metadata = config.metadata ?? {};
+    const batch = config.batch ?? {};
+    const routes = config.routes ?? {};
+    return {
+      api: {
+        version: api.version ?? "v1",
+        basePath: api.basePath ?? "/api",
+        apiPath: api.apiPath,
+        enableCrud: api.enableCrud ?? true,
+        enableMetadata: api.enableMetadata ?? true,
+        enableBatch: api.enableBatch ?? true,
+        enableDiscovery: api.enableDiscovery ?? true,
+        documentation: api.documentation,
+        responseFormat: api.responseFormat
+      },
+      crud: {
+        operations: crud.operations ?? {
+          create: true,
+          read: true,
+          update: true,
+          delete: true,
+          list: true
+        },
+        patterns: crud.patterns,
+        dataPrefix: crud.dataPrefix ?? "/data",
+        objectParamStyle: crud.objectParamStyle ?? "path"
+      },
+      metadata: {
+        prefix: metadata.prefix ?? "/meta",
+        enableCache: metadata.enableCache ?? true,
+        cacheTtl: metadata.cacheTtl ?? 3600,
+        endpoints: metadata.endpoints ?? {
+          types: true,
+          items: true,
+          item: true,
+          schema: true
+        }
+      },
+      batch: {
+        maxBatchSize: batch.maxBatchSize ?? 200,
+        enableBatchEndpoint: batch.enableBatchEndpoint ?? true,
+        operations: batch.operations ?? {
+          createMany: true,
+          updateMany: true,
+          deleteMany: true,
+          upsertMany: true
+        },
+        defaultAtomic: batch.defaultAtomic ?? true
+      },
+      routes: {
+        includeObjects: routes.includeObjects,
+        excludeObjects: routes.excludeObjects,
+        nameTransform: routes.nameTransform ?? "none",
+        overrides: routes.overrides
+      }
+    };
+  }
+  /**
+   * Get the full API base path
+   */
+  getApiBasePath() {
+    const { api } = this.config;
+    return api.apiPath ?? `${api.basePath}/${api.version}`;
+  }
+  /**
+   * Register all REST API routes
+   */
+  registerRoutes() {
+    const basePath = this.getApiBasePath();
+    if (this.config.api.enableDiscovery) {
+      this.registerDiscoveryEndpoints(basePath);
+    }
+    if (this.config.api.enableMetadata) {
+      this.registerMetadataEndpoints(basePath);
+    }
+    if (this.config.api.enableCrud) {
+      this.registerCrudEndpoints(basePath);
+    }
+    if (this.config.api.enableBatch) {
+      this.registerBatchEndpoints(basePath);
+    }
+  }
+  /**
+   * Register discovery endpoints
+   */
+  registerDiscoveryEndpoints(basePath) {
+    this.routeManager.register({
+      method: "GET",
+      path: basePath,
+      handler: async (_req, res) => {
+        try {
+          const discovery = await this.protocol.getDiscovery({});
+          res.json(discovery);
+        } catch (error) {
+          res.status(500).json({ error: error.message });
+        }
+      },
+      metadata: {
+        summary: "Get API discovery information",
+        tags: ["discovery"]
+      }
+    });
+  }
+  /**
+   * Register metadata endpoints
+   */
+  registerMetadataEndpoints(basePath) {
+    const { metadata } = this.config;
+    const metaPath = `${basePath}${metadata.prefix}`;
+    if (metadata.endpoints.types !== false) {
+      this.routeManager.register({
+        method: "GET",
+        path: metaPath,
+        handler: async (_req, res) => {
+          try {
+            const types = await this.protocol.getMetaTypes({});
+            res.json(types);
+          } catch (error) {
+            res.status(500).json({ error: error.message });
+          }
+        },
+        metadata: {
+          summary: "List all metadata types",
+          tags: ["metadata"]
+        }
+      });
+    }
+    if (metadata.endpoints.items !== false) {
+      this.routeManager.register({
+        method: "GET",
+        path: `${metaPath}/:type`,
+        handler: async (req, res) => {
+          try {
+            const items = await this.protocol.getMetaItems({ type: req.params.type });
+            res.json(items);
+          } catch (error) {
+            res.status(404).json({ error: error.message });
+          }
+        },
+        metadata: {
+          summary: "List metadata items of a type",
+          tags: ["metadata"]
+        }
+      });
+    }
+    if (metadata.endpoints.item !== false) {
+      this.routeManager.register({
+        method: "GET",
+        path: `${metaPath}/:type/:name`,
+        handler: async (req, res) => {
+          try {
+            if (metadata.enableCache && this.protocol.getMetaItemCached) {
+              const cacheRequest = {
+                ifNoneMatch: req.headers["if-none-match"],
+                ifModifiedSince: req.headers["if-modified-since"]
+              };
+              const result = await this.protocol.getMetaItemCached({
+                type: req.params.type,
+                name: req.params.name,
+                cacheRequest
+              });
+              if (result.notModified) {
+                res.status(304).send();
+                return;
+              }
+              if (result.etag) {
+                const etagValue = result.etag.weak ? `W/"${result.etag.value}"` : `"${result.etag.value}"`;
+                res.header("ETag", etagValue);
+              }
+              if (result.lastModified) {
+                res.header("Last-Modified", new Date(result.lastModified).toUTCString());
+              }
+              if (result.cacheControl) {
+                const directives = result.cacheControl.directives.join(", ");
+                const maxAge = result.cacheControl.maxAge ? `, max-age=${result.cacheControl.maxAge}` : "";
+                res.header("Cache-Control", directives + maxAge);
+              }
+              res.json(result.data);
+            } else {
+              const item = await this.protocol.getMetaItem({ type: req.params.type, name: req.params.name });
+              res.json(item);
+            }
+          } catch (error) {
+            res.status(404).json({ error: error.message });
+          }
+        },
+        metadata: {
+          summary: "Get specific metadata item",
+          tags: ["metadata"]
+        }
+      });
+    }
+    this.routeManager.register({
+      method: "PUT",
+      path: `${metaPath}/:type/:name`,
+      handler: async (req, res) => {
+        try {
+          if (!this.protocol.saveMetaItem) {
+            res.status(501).json({ error: "Save operation not supported by protocol implementation" });
+            return;
+          }
+          const result = await this.protocol.saveMetaItem({
+            type: req.params.type,
+            name: req.params.name,
+            item: req.body
+          });
+          res.json(result);
+        } catch (error) {
+          res.status(400).json({ error: error.message });
+        }
+      },
+      metadata: {
+        summary: "Save specific metadata item",
+        tags: ["metadata"]
+      }
+    });
+  }
+  /**
+   * Register CRUD endpoints for data operations
+   */
+  registerCrudEndpoints(basePath) {
+    const { crud } = this.config;
+    const dataPath = `${basePath}${crud.dataPrefix}`;
+    const operations = crud.operations;
+    if (operations.list) {
+      this.routeManager.register({
+        method: "GET",
+        path: `${dataPath}/:object`,
+        handler: async (req, res) => {
+          try {
+            const result = await this.protocol.findData({
+              object: req.params.object,
+              query: req.query
+            });
+            res.json(result);
+          } catch (error) {
+            res.status(400).json({ error: error.message });
+          }
+        },
+        metadata: {
+          summary: "Query records",
+          tags: ["data", "crud"]
+        }
+      });
+    }
+    if (operations.read) {
+      this.routeManager.register({
+        method: "GET",
+        path: `${dataPath}/:object/:id`,
+        handler: async (req, res) => {
+          try {
+            const result = await this.protocol.getData({
+              object: req.params.object,
+              id: req.params.id
+            });
+            res.json(result);
+          } catch (error) {
+            res.status(404).json({ error: error.message });
+          }
+        },
+        metadata: {
+          summary: "Get record by ID",
+          tags: ["data", "crud"]
+        }
+      });
+    }
+    if (operations.create) {
+      this.routeManager.register({
+        method: "POST",
+        path: `${dataPath}/:object`,
+        handler: async (req, res) => {
+          try {
+            const result = await this.protocol.createData({
+              object: req.params.object,
+              data: req.body
+            });
+            res.status(201).json(result);
+          } catch (error) {
+            res.status(400).json({ error: error.message });
+          }
+        },
+        metadata: {
+          summary: "Create record",
+          tags: ["data", "crud"]
+        }
+      });
+    }
+    if (operations.update) {
+      this.routeManager.register({
+        method: "PATCH",
+        path: `${dataPath}/:object/:id`,
+        handler: async (req, res) => {
+          try {
+            const result = await this.protocol.updateData({
+              object: req.params.object,
+              id: req.params.id,
+              data: req.body
+            });
+            res.json(result);
+          } catch (error) {
+            res.status(400).json({ error: error.message });
+          }
+        },
+        metadata: {
+          summary: "Update record",
+          tags: ["data", "crud"]
+        }
+      });
+    }
+    if (operations.delete) {
+      this.routeManager.register({
+        method: "DELETE",
+        path: `${dataPath}/:object/:id`,
+        handler: async (req, res) => {
+          try {
+            const result = await this.protocol.deleteData({
+              object: req.params.object,
+              id: req.params.id
+            });
+            res.json(result);
+          } catch (error) {
+            res.status(400).json({ error: error.message });
+          }
+        },
+        metadata: {
+          summary: "Delete record",
+          tags: ["data", "crud"]
+        }
+      });
+    }
+  }
+  /**
+   * Register batch operation endpoints
+   */
+  registerBatchEndpoints(basePath) {
+    const { crud, batch } = this.config;
+    const dataPath = `${basePath}${crud.dataPrefix}`;
+    const operations = batch.operations;
+    if (batch.enableBatchEndpoint && this.protocol.batchData) {
+      this.routeManager.register({
+        method: "POST",
+        path: `${dataPath}/:object/batch`,
+        handler: async (req, res) => {
+          try {
+            const result = await this.protocol.batchData({
+              object: req.params.object,
+              request: req.body
+            });
+            res.json(result);
+          } catch (error) {
+            res.status(400).json({ error: error.message });
+          }
+        },
+        metadata: {
+          summary: "Batch operations",
+          tags: ["data", "batch"]
+        }
+      });
+    }
+    if (operations.createMany && this.protocol.createManyData) {
+      this.routeManager.register({
+        method: "POST",
+        path: `${dataPath}/:object/createMany`,
+        handler: async (req, res) => {
+          try {
+            const result = await this.protocol.createManyData({
+              object: req.params.object,
+              records: req.body || []
+            });
+            res.status(201).json(result);
+          } catch (error) {
+            res.status(400).json({ error: error.message });
+          }
+        },
+        metadata: {
+          summary: "Create multiple records",
+          tags: ["data", "batch"]
+        }
+      });
+    }
+    if (operations.updateMany && this.protocol.updateManyData) {
+      this.routeManager.register({
+        method: "POST",
+        path: `${dataPath}/:object/updateMany`,
+        handler: async (req, res) => {
+          try {
+            const result = await this.protocol.updateManyData({
+              object: req.params.object,
+              ...req.body
+            });
+            res.json(result);
+          } catch (error) {
+            res.status(400).json({ error: error.message });
+          }
+        },
+        metadata: {
+          summary: "Update multiple records",
+          tags: ["data", "batch"]
+        }
+      });
+    }
+    if (operations.deleteMany && this.protocol.deleteManyData) {
+      this.routeManager.register({
+        method: "POST",
+        path: `${dataPath}/:object/deleteMany`,
+        handler: async (req, res) => {
+          try {
+            const result = await this.protocol.deleteManyData({
+              object: req.params.object,
+              ...req.body
+            });
+            res.json(result);
+          } catch (error) {
+            res.status(400).json({ error: error.message });
+          }
+        },
+        metadata: {
+          summary: "Delete multiple records",
+          tags: ["data", "batch"]
+        }
+      });
+    }
+  }
+  /**
+   * Get the route manager
+   */
+  getRouteManager() {
+    return this.routeManager;
+  }
+  /**
+   * Get all registered routes
+   */
+  getRoutes() {
+    return this.routeManager.getAll();
+  }
+};
+
+// src/api-registry-plugin.ts
+function createApiRegistryPlugin(config = {}) {
+  return {
+    name: "com.objectstack.runtime.api-registry",
+    version: "1.0.0",
+    init: async (_ctx) => {
+    },
+    start: async (ctx) => {
+      const serverService = config.serverServiceName || "http.server";
+      const protocolService = config.protocolServiceName || "protocol";
+      let server;
+      let protocol;
+      try {
+        server = ctx.getService(serverService);
+      } catch (e) {
+      }
+      try {
+        protocol = ctx.getService(protocolService);
+      } catch (e) {
+      }
+      if (!server) {
+        ctx.logger.warn(`ApiRegistryPlugin: HTTP Server service '${serverService}' not found. REST routes skipped.`);
+        return;
+      }
+      if (!protocol) {
+        ctx.logger.warn(`ApiRegistryPlugin: Protocol service '${protocolService}' not found. REST routes skipped.`);
+        return;
+      }
+      ctx.logger.info("Hydrating REST API from Protocol...");
+      try {
+        const restServer = new RestServer(server, protocol, config.api);
+        restServer.registerRoutes();
+        ctx.logger.info("REST API successfully registered");
+      } catch (err) {
+        ctx.logger.error("Failed to register REST API routes", { error: err.message });
+        throw err;
+      }
+    }
+  };
+}
+
+// src/runtime.ts
+var Runtime = class {
+  constructor(config = {}) {
+    this.kernel = new import_core.ObjectKernel(config.kernel);
+    if (config.server) {
+      this.kernel.registerService("http.server", config.server);
+    }
+    this.kernel.use(createApiRegistryPlugin(config.api));
+  }
+  /**
+   * Register a plugin
+   */
+  use(plugin) {
+    this.kernel.use(plugin);
+    return this;
+  }
+  /**
+   * Start the runtime
+   * 1. Initializes all plugins (init phase)
+   * 2. Starts all plugins (start phase)
+   */
+  async start() {
+    await this.kernel.bootstrap();
+    return this;
+  }
+  /**
+   * Get the kernel instance
+   */
+  getKernel() {
+    return this.kernel;
+  }
+};
+
+// src/driver-plugin.ts
+var DriverPlugin = class {
+  constructor(driver, driverName) {
+    this.version = "1.0.0";
+    this.init = async (ctx) => {
+      const serviceName = `driver.${this.driver.name || "unknown"}`;
+      ctx.registerService(serviceName, this.driver);
+      ctx.logger.info("Driver service registered", {
+        serviceName,
+        driverName: this.driver.name,
+        driverVersion: this.driver.version
+      });
+    };
+    this.start = async (ctx) => {
+      ctx.logger.debug("Driver plugin started", { driverName: this.driver.name || "unknown" });
+    };
+    this.driver = driver;
+    this.name = `com.objectstack.driver.${driverName || driver.name || "unknown"}`;
+  }
+};
+
+// src/app-plugin.ts
+var AppPlugin = class {
+  constructor(bundle) {
+    this.init = async (ctx) => {
+      const sys = this.bundle.manifest || this.bundle;
+      const appId = sys.id || sys.name;
+      ctx.logger.info("Registering App Service", {
+        appId,
+        pluginName: this.name,
+        version: this.version
+      });
+      const serviceName = `app.${appId}`;
+      const servicePayload = this.bundle.manifest ? { ...this.bundle.manifest, ...this.bundle } : this.bundle;
+      ctx.registerService(serviceName, servicePayload);
+    };
+    this.start = async (ctx) => {
+      const sys = this.bundle.manifest || this.bundle;
+      const appId = sys.id || sys.name;
+      const ql = ctx.getService("objectql");
+      if (!ql) {
+        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.info("Executing runtime.onEnable", {
+          appName: this.name,
+          appId
+        });
+        const hostContext = {
+          ...ctx,
+          ql,
+          logger: ctx.logger,
+          drivers: {
+            register: (driver) => {
+              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 });
+      }
+    };
+    this.bundle = bundle;
+    const sys = bundle.manifest || bundle;
+    const appId = sys.id || sys.name || "unnamed-app";
+    this.name = `plugin.app.${appId}`;
+    this.version = sys.version;
+  }
+};
+
+// src/http-server.ts
+var HttpServer = class {
+  /**
+   * Create an HTTP server wrapper
+   * @param server - The underlying server implementation (Hono, Express, etc.)
+   */
+  constructor(server) {
+    this.server = server;
+    this.routes = /* @__PURE__ */ 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, handler) {
+    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, handler) {
+    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, handler) {
+    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, handler) {
+    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, handler) {
+    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, handler) {
+    if (typeof path === "function") {
+      this.middlewares.push(path);
+      this.server.use(path);
+    } else if (handler) {
+      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) {
+    await this.server.listen(port);
+  }
+  /**
+   * Stop the HTTP server
+   * @returns Promise that resolves when server is stopped
+   */
+  async close() {
+    if (this.server.close) {
+      await this.server.close();
+    }
+  }
+  /**
+   * Get registered routes
+   * @returns Map of route keys to handlers
+   */
+  getRoutes() {
+    return new Map(this.routes);
+  }
+  /**
+   * Get registered middlewares
+   * @returns Array of middleware functions
+   */
+  getMiddlewares() {
+    return [...this.middlewares];
+  }
+};
+
+// src/http-dispatcher.ts
+var import_core2 = require("@objectstack/core");
+var import_system = require("@objectstack/spec/system");
+var HttpDispatcher = class {
+  // Casting to any to access dynamic props like broker, services, graphql
+  constructor(kernel) {
+    this.kernel = kernel;
+  }
+  success(data, meta) {
+    return {
+      status: 200,
+      body: { success: true, data, meta }
+    };
+  }
+  error(message, code = 500, details) {
+    return {
+      status: code,
+      body: { success: false, error: { message, code, details } }
+    };
+  }
+  ensureBroker() {
+    if (!this.kernel.broker) {
+      throw { statusCode: 500, message: "Kernel Broker not available" };
+    }
+    return this.kernel.broker;
+  }
+  /**
+   * Generates the discovery JSON response for the API root
+   */
+  getDiscoveryInfo(prefix) {
+    const services = this.getServicesMap();
+    const hasGraphQL = !!(services[import_system.CoreServiceName.enum.graphql] || this.kernel.graphql);
+    const hasSearch = !!services[import_system.CoreServiceName.enum.search];
+    const hasWebSockets = !!services[import_system.CoreServiceName.enum.realtime];
+    const hasFiles = !!(services[import_system.CoreServiceName.enum["file-storage"]] || services["storage"]?.supportsFiles);
+    const hasAnalytics = !!services[import_system.CoreServiceName.enum.analytics];
+    const hasHub = !!services[import_system.CoreServiceName.enum.hub];
+    return {
+      name: "ObjectOS",
+      version: "1.0.0",
+      environment: (0, import_core2.getEnv)("NODE_ENV", "development"),
+      routes: {
+        data: `${prefix}/data`,
+        metadata: `${prefix}/metadata`,
+        auth: `${prefix}/auth`,
+        graphql: hasGraphQL ? `${prefix}/graphql` : void 0,
+        storage: hasFiles ? `${prefix}/storage` : void 0,
+        analytics: hasAnalytics ? `${prefix}/analytics` : void 0,
+        hub: hasHub ? `${prefix}/hub` : void 0
+      },
+      features: {
+        graphql: hasGraphQL,
+        search: hasSearch,
+        websockets: hasWebSockets,
+        files: hasFiles,
+        analytics: hasAnalytics,
+        hub: hasHub
+      },
+      locale: {
+        default: "en",
+        supported: ["en", "zh-CN"],
+        timezone: "UTC"
+      }
+    };
+  }
+  /**
+   * Handles GraphQL requests
+   */
+  async handleGraphQL(body, context) {
+    if (!body || !body.query) {
+      throw { statusCode: 400, message: "Missing query in request body" };
+    }
+    if (typeof this.kernel.graphql !== "function") {
+      throw { statusCode: 501, message: "GraphQL service not available" };
+    }
+    return this.kernel.graphql(body.query, body.variables, {
+      request: context.request
+    });
+  }
+  /**
+   * Handles Auth requests
+   * path: sub-path after /auth/
+   */
+  async handleAuth(path, method, body, context) {
+    const authService = this.getService(import_system.CoreServiceName.enum.auth);
+    if (authService && typeof authService.handler === "function") {
+      const response = await authService.handler(context.request, context.response);
+      return { handled: true, result: response };
+    }
+    const normalizedPath = path.replace(/^\/+/, "");
+    if (normalizedPath === "login" && method.toUpperCase() === "POST") {
+      const broker = this.ensureBroker();
+      const data = await broker.call("auth.login", body, { request: context.request });
+      return { handled: true, response: { status: 200, body: data } };
+    }
+    return { handled: false };
+  }
+  /**
+   * Handles Metadata requests
+   * Standard: /metadata/:type/:name
+   * Fallback for backward compat: /metadata (all objects), /metadata/:objectName (get object)
+   */
+  async handleMetadata(path, context, method, body) {
+    const broker = this.ensureBroker();
+    const parts = path.replace(/^\/+/, "").split("/").filter(Boolean);
+    if (parts[0] === "types") {
+      return { handled: true, response: this.success({ types: ["objects", "apps", "plugins"] }) };
+    }
+    if (parts.length === 2) {
+      const [type, name] = parts;
+      if (method === "PUT" && body) {
+        const protocol = this.kernel?.context?.getService ? this.kernel.context.getService("protocol") : null;
+        if (protocol && typeof protocol.saveMetaItem === "function") {
+          try {
+            const result = await protocol.saveMetaItem({ type, name, item: body });
+            return { handled: true, response: this.success(result) };
+          } catch (e) {
+            return { handled: true, response: this.error(e.message, 400) };
+          }
+        }
+        try {
+          const data = await broker.call("metadata.saveItem", { type, name, item: body }, { request: context.request });
+          return { handled: true, response: this.success(data) };
+        } catch (e) {
+          return { handled: true, response: this.error(e.message || "Save not supported", 501) };
+        }
+      }
+      try {
+        if (type === "objects") {
+          const data2 = await broker.call("metadata.getObject", { objectName: name }, { request: context.request });
+          return { handled: true, response: this.success(data2) };
+        }
+        const data = await broker.call(`metadata.get${this.capitalize(type.slice(0, -1))}`, { name }, { request: context.request });
+        return { handled: true, response: this.success(data) };
+      } catch (e) {
+        return { handled: true, response: this.error(e.message, 404) };
+      }
+    }
+    if (parts.length === 1) {
+      const typeOrName = parts[0];
+      if (["objects", "apps", "plugins"].includes(typeOrName)) {
+        if (typeOrName === "objects") {
+          const data3 = await broker.call("metadata.objects", {}, { request: context.request });
+          return { handled: true, response: this.success(data3) };
+        }
+        const data2 = await broker.call(`metadata.${typeOrName}`, {}, { request: context.request });
+        return { handled: true, response: this.success(data2) };
+      }
+      const data = await broker.call("metadata.getObject", { objectName: typeOrName }, { request: context.request });
+      return { handled: true, response: this.success(data) };
+    }
+    if (parts.length === 0) {
+      const data = await broker.call("metadata.objects", {}, { request: context.request });
+      return { handled: true, response: this.success(data) };
+    }
+    return { handled: false };
+  }
+  /**
+   * Handles Data requests
+   * path: sub-path after /data/ (e.g. "contacts", "contacts/123", "contacts/query")
+   */
+  async handleData(path, method, body, query, context) {
+    const broker = this.ensureBroker();
+    const parts = path.replace(/^\/+/, "").split("/");
+    const objectName = parts[0];
+    if (!objectName) {
+      return { handled: true, response: this.error("Object name required", 400) };
+    }
+    const m = method.toUpperCase();
+    if (parts.length > 1) {
+      const action = parts[1];
+      if (action === "query" && m === "POST") {
+        const result = await broker.call("data.query", { object: objectName, ...body }, { request: context.request });
+        return { handled: true, response: this.success(result.data, { count: result.count, limit: body.limit, skip: body.skip }) };
+      }
+      if (action === "batch" && m === "POST") {
+        const result = await broker.call("data.batch", { object: objectName, ...body }, { request: context.request });
+        return { handled: true, response: this.success(result) };
+      }
+      if (parts.length === 2 && m === "GET") {
+        const id = parts[1];
+        const data = await broker.call("data.get", { object: objectName, id, ...query }, { request: context.request });
+        return { handled: true, response: this.success(data) };
+      }
+      if (parts.length === 2 && m === "PATCH") {
+        const id = parts[1];
+        const data = await broker.call("data.update", { object: objectName, id, data: body }, { request: context.request });
+        return { handled: true, response: this.success(data) };
+      }
+      if (parts.length === 2 && m === "DELETE") {
+        const id = parts[1];
+        await broker.call("data.delete", { object: objectName, id }, { request: context.request });
+        return { handled: true, response: this.success({ id, deleted: true }) };
+      }
+    } else {
+      if (m === "GET") {
+        const result = await broker.call("data.query", { object: objectName, filters: query }, { request: context.request });
+        return { handled: true, response: this.success(result.data, { count: result.count }) };
+      }
+      if (m === "POST") {
+        const data = await broker.call("data.create", { object: objectName, data: body }, { request: context.request });
+        const res = this.success(data);
+        res.status = 201;
+        return { handled: true, response: res };
+      }
+    }
+    return { handled: false };
+  }
+  /**
+   * Handles Analytics requests
+   * path: sub-path after /analytics/
+   */
+  async handleAnalytics(path, method, body, context) {
+    const analyticsService = this.getService(import_system.CoreServiceName.enum.analytics);
+    if (!analyticsService) return { handled: false };
+    const m = method.toUpperCase();
+    const subPath = path.replace(/^\/+/, "");
+    if (subPath === "query" && m === "POST") {
+      const result = await analyticsService.query(body, { request: context.request });
+      return { handled: true, response: this.success(result) };
+    }
+    if (subPath === "meta" && m === "GET") {
+      const result = await analyticsService.getMetadata({ request: context.request });
+      return { handled: true, response: this.success(result) };
+    }
+    if (subPath === "sql" && m === "POST") {
+      const result = await analyticsService.generateSql(body, { request: context.request });
+      return { handled: true, response: this.success(result) };
+    }
+    return { handled: false };
+  }
+  /**
+   * Handles Hub requests
+   * path: sub-path after /hub/
+   */
+  async handleHub(path, method, body, query, context) {
+    const hubService = this.getService(import_system.CoreServiceName.enum.hub);
+    if (!hubService) return { handled: false };
+    const m = method.toUpperCase();
+    const parts = path.replace(/^\/+/, "").split("/");
+    if (parts.length > 0) {
+      const resource = parts[0];
+      const actionBase = resource.endsWith("s") ? resource.slice(0, -1) : resource;
+      const id = parts[1];
+      try {
+        if (parts.length === 1) {
+          if (m === "GET") {
+            const capitalizedAction = "list" + this.capitalize(resource);
+            if (typeof hubService[capitalizedAction] === "function") {
+              const result = await hubService[capitalizedAction](query, { request: context.request });
+              return { handled: true, response: this.success(result) };
+            }
+          }
+          if (m === "POST") {
+            const capitalizedAction = "create" + this.capitalize(actionBase);
+            if (typeof hubService[capitalizedAction] === "function") {
+              const result = await hubService[capitalizedAction](body, { request: context.request });
+              return { handled: true, response: this.success(result) };
+            }
+          }
+        } else if (parts.length === 2) {
+          if (m === "GET") {
+            const capitalizedAction = "get" + this.capitalize(actionBase);
+            if (typeof hubService[capitalizedAction] === "function") {
+              const result = await hubService[capitalizedAction](id, { request: context.request });
+              return { handled: true, response: this.success(result) };
+            }
+          }
+          if (m === "PATCH" || m === "PUT") {
+            const capitalizedAction = "update" + this.capitalize(actionBase);
+            if (typeof hubService[capitalizedAction] === "function") {
+              const result = await hubService[capitalizedAction](id, body, { request: context.request });
+              return { handled: true, response: this.success(result) };
+            }
+          }
+          if (m === "DELETE") {
+            const capitalizedAction = "delete" + this.capitalize(actionBase);
+            if (typeof hubService[capitalizedAction] === "function") {
+              const result = await hubService[capitalizedAction](id, { request: context.request });
+              return { handled: true, response: this.success(result) };
+            }
+          }
+        }
+      } catch (e) {
+        return { handled: true, response: this.error(e.message, 500) };
+      }
+    }
+    return { handled: false };
+  }
+  /**
+   * Handles Storage requests
+   * path: sub-path after /storage/
+   */
+  async handleStorage(path, method, file, context) {
+    const storageService = this.getService(import_system.CoreServiceName.enum["file-storage"]) || this.kernel.services?.["file-storage"];
+    if (!storageService) {
+      return { handled: true, response: this.error("File storage not configured", 501) };
+    }
+    const m = method.toUpperCase();
+    const parts = path.replace(/^\/+/, "").split("/");
+    if (parts[0] === "upload" && m === "POST") {
+      if (!file) {
+        return { handled: true, response: this.error("No file provided", 400) };
+      }
+      const result = await storageService.upload(file, { request: context.request });
+      return { handled: true, response: this.success(result) };
+    }
+    if (parts[0] === "file" && parts[1] && m === "GET") {
+      const id = parts[1];
+      const result = await storageService.download(id, { request: context.request });
+      if (result.url && result.redirect) {
+        return { handled: true, result: { type: "redirect", url: result.url } };
+      }
+      if (result.stream) {
+        return {
+          handled: true,
+          result: {
+            type: "stream",
+            stream: result.stream,
+            headers: {
+              "Content-Type": result.mimeType || "application/octet-stream",
+              "Content-Length": result.size
+            }
+          }
+        };
+      }
+      return { handled: true, response: this.success(result) };
+    }
+    return { handled: false };
+  }
+  /**
+   * Handles Automation requests
+   * path: sub-path after /automation/
+   */
+  async handleAutomation(path, method, body, context) {
+    const automationService = this.getService(import_system.CoreServiceName.enum.automation);
+    if (!automationService) return { handled: false };
+    const m = method.toUpperCase();
+    const parts = path.replace(/^\/+/, "").split("/");
+    if (parts[0] === "trigger" && parts[1] && m === "POST") {
+      const triggerName = parts[1];
+      if (typeof automationService.trigger === "function") {
+        const result = await automationService.trigger(triggerName, body, { request: context.request });
+        return { handled: true, response: this.success(result) };
+      }
+    }
+    return { handled: false };
+  }
+  getServicesMap() {
+    if (this.kernel.services instanceof Map) {
+      return Object.fromEntries(this.kernel.services);
+    }
+    return this.kernel.services || {};
+  }
+  getService(name) {
+    if (typeof this.kernel.getService === "function") {
+      return this.kernel.getService(name);
+    }
+    const services = this.getServicesMap();
+    return services[name];
+  }
+  capitalize(s) {
+    return s.charAt(0).toUpperCase() + s.slice(1);
+  }
+  /**
+   * Main Dispatcher Entry Point
+   * Routes the request to the appropriate handler based on path and precedence
+   */
+  async dispatch(method, path, body, query, context) {
+    const cleanPath = path.replace(/\/$/, "");
+    if (cleanPath.startsWith("/auth")) {
+      return this.handleAuth(cleanPath.substring(5), method, body, context);
+    }
+    if (cleanPath.startsWith("/metadata")) {
+      return this.handleMetadata(cleanPath.substring(9), context);
+    }
+    if (cleanPath.startsWith("/data")) {
+      return this.handleData(cleanPath.substring(5), method, body, query, context);
+    }
+    if (cleanPath.startsWith("/graphql")) {
+      if (method === "POST") return this.handleGraphQL(body, context);
+    }
+    if (cleanPath.startsWith("/storage")) {
+      return this.handleStorage(cleanPath.substring(8), method, body, context);
+    }
+    if (cleanPath.startsWith("/automation")) {
+      return this.handleAutomation(cleanPath.substring(11), method, body, context);
+    }
+    if (cleanPath.startsWith("/analytics")) {
+      return this.handleAnalytics(cleanPath.substring(10), method, body, context);
+    }
+    if (cleanPath.startsWith("/hub")) {
+      return this.handleHub(cleanPath.substring(4), method, body, query, context);
+    }
+    if (cleanPath === "/openapi.json" && method === "GET") {
+      const broker = this.ensureBroker();
+      try {
+        const result2 = await broker.call("metadata.generateOpenApi", {}, { request: context.request });
+        return { handled: true, response: this.success(result2) };
+      } catch (e) {
+      }
+    }
+    const result = await this.handleApiEndpoint(cleanPath, method, body, query, context);
+    if (result.handled) return result;
+    return { handled: false };
+  }
+  /**
+   * Handles Custom API Endpoints defined in metadata
+   */
+  async handleApiEndpoint(path, method, body, query, context) {
+    const broker = this.ensureBroker();
+    try {
+      const endpoint = await broker.call("metadata.matchEndpoint", { path, method });
+      if (endpoint) {
+        if (endpoint.type === "flow") {
+          const result = await broker.call("automation.runFlow", {
+            flowId: endpoint.target,
+            inputs: { ...query, ...body, _request: context.request }
+          });
+          return { handled: true, response: this.success(result) };
+        }
+        if (endpoint.type === "script") {
+          const result = await broker.call("automation.runScript", {
+            scriptName: endpoint.target,
+            context: { ...query, ...body, request: context.request }
+          }, { request: context.request });
+          return { handled: true, response: this.success(result) };
+        }
+        if (endpoint.type === "object_operation") {
+          if (endpoint.objectParams) {
+            const { object, operation } = endpoint.objectParams;
+            if (operation === "find") {
+              const result = await broker.call("data.query", { object, filters: query }, { request: context.request });
+              return { handled: true, response: this.success(result.data, { count: result.count }) };
+            }
+            if (operation === "get" && query.id) {
+              const result = await broker.call("data.get", { object, id: query.id }, { request: context.request });
+              return { handled: true, response: this.success(result) };
+            }
+            if (operation === "create") {
+              const result = await broker.call("data.create", { object, data: body }, { request: context.request });
+              return { handled: true, response: this.success(result) };
+            }
+          }
+        }
+        if (endpoint.type === "proxy") {
+          return {
+            handled: true,
+            response: {
+              status: 200,
+              body: { proxy: true, target: endpoint.target, note: "Proxy execution requires http-client service" }
+            }
+          };
+        }
+      }
+    } catch (e) {
+    }
+    return { handled: false };
+  }
+};
+
+// src/middleware.ts
+var MiddlewareManager = class {
+  constructor() {
+    this.middlewares = /* @__PURE__ */ new Map();
+  }
+  /**
+   * Register middleware with configuration
+   * @param config - Middleware configuration
+   * @param middleware - Middleware function
+   */
+  register(config, middleware) {
+    const entry = {
+      name: config.name,
+      type: config.type,
+      middleware,
+      order: config.order ?? 100,
+      enabled: config.enabled ?? true,
+      paths: config.paths
+    };
+    this.middlewares.set(config.name, entry);
+  }
+  /**
+   * Unregister middleware by name
+   * @param name - Middleware name
+   */
+  unregister(name) {
+    this.middlewares.delete(name);
+  }
+  /**
+   * Enable middleware by name
+   * @param name - Middleware name
+   */
+  enable(name) {
+    const entry = this.middlewares.get(name);
+    if (entry) {
+      entry.enabled = true;
+    }
+  }
+  /**
+   * Disable middleware by name
+   * @param name - Middleware name
+   */
+  disable(name) {
+    const entry = this.middlewares.get(name);
+    if (entry) {
+      entry.enabled = false;
+    }
+  }
+  /**
+   * Get middleware entry by name
+   * @param name - Middleware name
+   */
+  get(name) {
+    return this.middlewares.get(name);
+  }
+  /**
+   * Get all middleware entries
+   */
+  getAll() {
+    return Array.from(this.middlewares.values());
+  }
+  /**
+   * Get middleware by type
+   * @param type - Middleware type
+   */
+  getByType(type) {
+    return this.getAll().filter((entry) => entry.type === type);
+  }
+  /**
+   * Get middleware chain sorted by order
+   * Returns only enabled middleware
+   */
+  getMiddlewareChain() {
+    return this.getAll().filter((entry) => entry.enabled).sort((a, b) => a.order - b.order).map((entry) => entry.middleware);
+  }
+  /**
+   * Get middleware chain with path filtering
+   * @param path - Request path to match against
+   */
+  getMiddlewareChainForPath(path) {
+    return this.getAll().filter((entry) => {
+      if (!entry.enabled) return false;
+      if (entry.paths) {
+        if (entry.paths.exclude) {
+          const excluded = entry.paths.exclude.some(
+            (pattern) => this.matchPath(path, pattern)
+          );
+          if (excluded) return false;
+        }
+        if (entry.paths.include) {
+          const included = entry.paths.include.some(
+            (pattern) => this.matchPath(path, pattern)
+          );
+          if (!included) return false;
+        }
+      }
+      return true;
+    }).sort((a, b) => a.order - b.order).map((entry) => entry.middleware);
+  }
+  /**
+   * Match path against pattern (simple glob matching)
+   * @param path - Request path
+   * @param pattern - Pattern to match (supports * wildcard)
+   */
+  matchPath(path, pattern) {
+    const regexPattern = pattern.replace(/\*/g, ".*").replace(/\?/g, ".");
+    const regex = new RegExp(`^${regexPattern}$`);
+    return regex.test(path);
+  }
+  /**
+   * Clear all middleware
+   */
+  clear() {
+    this.middlewares.clear();
+  }
+  /**
+   * Get middleware count
+   */
+  count() {
+    return this.middlewares.size;
+  }
+  /**
+   * Create a composite middleware from the chain
+   * This can be used to apply all middleware at once
+   */
+  createCompositeMiddleware() {
+    const chain = this.getMiddlewareChain();
+    return async (req, res, next) => {
+      let index = 0;
+      const executeNext = async () => {
+        if (index >= chain.length) {
+          await next();
+          return;
+        }
+        const middleware = chain[index++];
+        await middleware(req, res, executeNext);
+      };
+      await executeNext();
+    };
+  }
+};
+
+// src/index.ts
+__reExport(index_exports, require("@objectstack/core"), module.exports);
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  AppPlugin,
+  DriverPlugin,
+  HttpDispatcher,
+  HttpServer,
+  MiddlewareManager,
+  ObjectKernel,
+  RestServer,
+  RouteGroupBuilder,
+  RouteManager,
+  Runtime,
+  createApiRegistryPlugin,
+  ...require("@objectstack/core")
+});
+//# sourceMappingURL=index.cjs.map