@celerity-sdk/core 0.2.0 → 0.3.0

package/README.md

@@ -1,6 +1,6 @@
 # @celerity-sdk/core
 
-Core SDK for building Celerity applications — decorators, dependency injection, layers, guards, handler adapters, and the application factory.
+Core SDK for building Celerity applications - decorators, dependency injection, layers, guards, handler adapters, and the application factory.
 
 ## Installation
 
@@ -101,12 +101,27 @@ class OrdersHandler {
 import { CelerityFactory } from "@celerity-sdk/core";
 
 const app = await CelerityFactory.create(AppModule);
-// Auto-detects platform from CELERITY_RUNTIME_PLATFORM env var
+// Auto-detects platform from CELERITY_PLATFORM env var
 ```
 
+## Handler Resolution
+
+When a handler is invoked by ID (e.g. from a blueprint's `spec.handler` field), the SDK resolves it using a multi-step strategy:
+
+1. **Direct registry ID match** - looks up the handler by its explicit `id` (set via decorator or `createHttpHandler`).
+2. **Module resolution fallback** - if the direct lookup fails, the ID is treated as a module reference and dynamically imported:
+   - `"handlers.hello"` - named export `hello` from module `handlers`
+   - `"handlers"` - default export from module `handlers`
+   - `"app.module"` - tries named export split first (`module: "app"`, `export: "module"`), then falls back to default export from module `app.module`
+3. **Path/method routing** - if both ID-based lookups fail, falls back to matching the incoming request's HTTP method and path against the registry.
+
+Module resolution matches the imported function against the registry by reference (`===`). Once matched, the handler ID is assigned and subsequent invocations use the direct lookup without repeated imports.
+
+This is primarily relevant for blueprint-first function handlers where `spec.handler` references like `"handlers.hello"` map to exported functions that have no routing information in code.
+
 ## Guards
 
-Guards are declarative — they annotate handlers with protection requirements but do not execute in the Node.js process. Guard enforcement happens at the Rust runtime layer (containers) or API Gateway (serverless).
+Guards are declarative. They annotate handlers with protection requirements but do not execute in the Node.js process. Guard enforcement happens at the Rust runtime layer (containers) or API Gateway (serverless).
 
 ## Testing
 
@@ -117,6 +132,18 @@ const app = new TestingApplication(AppModule);
 const response = await app.handle(mockRequest({ method: "GET", path: "/orders/1" }));
 ```
 
+## Advanced Exports
+
+The following exports are available for adapter authors building custom serverless or runtime adapters:
+
+| Export | Purpose |
+|---|---|
+| `resolveHandlerByModuleRef(id, registry, baseDir)` | Resolve a handler ID as a module reference via dynamic import |
+| `executeHandlerPipeline(handler, request, options)` | Execute the full layer + handler pipeline |
+| `HandlerRegistry` | Handler registry class with route and ID-based lookups |
+| `bootstrapForRuntime(modulePath?, systemLayers?)` | Bootstrap for the Celerity runtime host |
+| `mapRuntimeRequest` / `mapToRuntimeResponse` | Runtime request/response mappers |
+
 ## Part of the Celerity Framework
 
 See [celerityframework.io](https://celerityframework.io) for full documentation.

package/dist/index.cjs

@@ -112,6 +112,7 @@ __export(index_exports, {
   mapToRuntimeResponse: () => mapToRuntimeResponse,
   mockRequest: () => mockRequest,
   registerModuleGraph: () => registerModuleGraph,
+  resolveHandlerByModuleRef: () => resolveHandlerByModuleRef,
   runLayerPipeline: () => runLayerPipeline,
   startRuntime: () => startRuntime,
   tokenToString: () => tokenToString,
@@ -1171,6 +1172,11 @@ var HandlerRegistry = class {
     debug4("getHandler %s %s \u2192 %s", method, path, found ? "matched" : "not found");
     return found;
   }
+  getHandlerById(id) {
+    const found = this.handlers.find((h) => h.id !== void 0 && h.id === id);
+    debug4("getHandlerById %s \u2192 %s", id, found ? "matched" : "not found");
+    return found;
+  }
   getAllHandlers() {
     return [
       ...this.handlers
@@ -1256,8 +1262,9 @@ var HandlerRegistry = class {
         layers.unshift(validate(schemas));
       }
     }
-    debug4("registerFunctionHandler: %s", meta.method && meta.path ? `${meta.method} ${meta.path}` : "(no route)");
+    debug4("registerFunctionHandler: %s", definition.id ?? (meta.method && meta.path ? `${meta.method} ${meta.path}` : "(no route)"));
     this.handlers.push({
+      id: definition.id,
       path: meta.path,
       method: meta.method,
       protectedBy: [],
@@ -1799,23 +1806,96 @@ function httpDelete(path, handlerOrOptions, maybeHandler) {
 }
 __name(httpDelete, "httpDelete");
 
-// src/bootstrap/discovery.ts
+// src/handlers/module-resolver.ts
 var import_node_path = require("path");
 var import_debug9 = __toESM(require("debug"), 1);
-var debug9 = (0, import_debug9.default)("celerity:core:bootstrap");
+var debug9 = (0, import_debug9.default)("celerity:core:module-resolver");
+async function resolveHandlerByModuleRef(handlerId, registry, baseDir) {
+  const lastDot = handlerId.lastIndexOf(".");
+  if (lastDot > 0) {
+    const moduleName = handlerId.slice(0, lastDot);
+    const exportName = handlerId.slice(lastDot + 1);
+    const result = await tryResolveExport(baseDir, moduleName, exportName, handlerId, registry);
+    if (result) return result;
+  }
+  return tryResolveExport(baseDir, handlerId, "default", handlerId, registry);
+}
+__name(resolveHandlerByModuleRef, "resolveHandlerByModuleRef");
+async function tryResolveExport(baseDir, moduleName, exportName, handlerId, registry) {
+  const handlerModulePath = (0, import_node_path.resolve)(baseDir, moduleName);
+  let mod;
+  try {
+    mod = await import(handlerModulePath);
+  } catch {
+    try {
+      mod = await import(`${handlerModulePath}.js`);
+    } catch {
+      return null;
+    }
+  }
+  const exported = mod[exportName];
+  if (!exported) return null;
+  const isFnDef = typeof exported === "object" && exported !== null && exported.__celerity_handler;
+  const handlerFn = isFnDef ? exported.handler : exported;
+  if (typeof handlerFn !== "function") return null;
+  const match = registry.getAllHandlers().find((h) => h.handlerFn === handlerFn);
+  if (match) {
+    match.id = handlerId;
+    debug9("matched '%s' to registry handler", handlerId);
+    return match;
+  }
+  debug9("'%s' not in registry, wrapping directly", handlerId);
+  return buildResolvedFromExport(handlerId, handlerFn, isFnDef ? exported : null);
+}
+__name(tryResolveExport, "tryResolveExport");
+function buildResolvedFromExport(handlerId, handlerFn, fnDef) {
+  if (fnDef) {
+    const meta = fnDef.metadata;
+    return {
+      id: handlerId,
+      protectedBy: [],
+      layers: [
+        ...meta.layers ?? []
+      ],
+      isPublic: false,
+      paramMetadata: [],
+      customMetadata: meta.customMetadata ?? {},
+      handlerFn,
+      isFunctionHandler: true,
+      injectTokens: meta.inject ?? []
+    };
+  }
+  return {
+    id: handlerId,
+    protectedBy: [],
+    layers: [],
+    isPublic: false,
+    paramMetadata: [],
+    customMetadata: {},
+    handlerFn,
+    isFunctionHandler: true,
+    injectTokens: []
+  };
+}
+__name(buildResolvedFromExport, "buildResolvedFromExport");
+
+// src/bootstrap/discovery.ts
+var import_node_path2 = require("path");
+var import_debug10 = __toESM(require("debug"), 1);
+var debug10 = (0, import_debug10.default)("celerity:core:bootstrap");
 async function discoverModule(modulePath) {
   const resolved = modulePath ?? process.env.CELERITY_MODULE_PATH;
   if (!resolved) {
     throw new Error("Cannot discover module: set CELERITY_MODULE_PATH environment variable or pass modulePath");
   }
-  const absolutePath = (0, import_node_path.resolve)(resolved);
-  debug9("discoverModule: importing %s", absolutePath);
+  const absolutePath = (0, import_node_path2.resolve)(resolved);
+  debug10("discoverModule: importing %s", absolutePath);
   const imported = await import(absolutePath);
   const rootModule = imported.default ?? findModuleExport(imported);
   if (!rootModule || typeof rootModule !== "function") {
     throw new Error(`No module class found in "${resolved}"`);
   }
-  debug9("discoverModule: found %s", rootModule.name);
+  debug10("discoverModule: found %s", rootModule.name);
   return rootModule;
 }
 __name(discoverModule, "discoverModule");
@@ -1871,24 +1951,37 @@ function mapToRuntimeResponse(response) {
 __name(mapToRuntimeResponse, "mapToRuntimeResponse");
 
 // src/bootstrap/runtime-entry.ts
+var import_node_path3 = require("path");
 async function bootstrapForRuntime(modulePath, systemLayers) {
   const layers = systemLayers ?? await createDefaultSystemLayers();
+  const resolvedModulePath = modulePath ?? process.env.CELERITY_MODULE_PATH;
+  const moduleDir = resolvedModulePath ? (0, import_node_path3.dirname)((0, import_node_path3.resolve)(resolvedModulePath)) : process.cwd();
   const rootModule = await discoverModule(modulePath);
   const { container, registry } = await bootstrap(rootModule);
+  function buildCallback(handler) {
+    if (!handler) return null;
+    return async (_err, request) => {
+      const httpRequest = mapRuntimeRequest(request);
+      const httpResponse = await executeHandlerPipeline(handler, httpRequest, {
+        container,
+        systemLayers: layers
+      });
+      return mapToRuntimeResponse(httpResponse);
+    };
+  }
+  __name(buildCallback, "buildCallback");
   return {
     registry,
     container,
     createRouteCallback(path, method) {
-      const handler = registry.getHandler(path, method);
-      if (!handler) return null;
-      return async (_err, request) => {
-        const httpRequest = mapRuntimeRequest(request);
-        const httpResponse = await executeHandlerPipeline(handler, httpRequest, {
-          container,
-          systemLayers: layers
-        });
-        return mapToRuntimeResponse(httpResponse);
-      };
+      return buildCallback(registry.getHandler(path, method));
+    },
+    async createRouteCallbackById(handlerId, codeLocation) {
+      const fromRegistry = registry.getHandlerById(handlerId);
+      if (fromRegistry) return buildCallback(fromRegistry);
+      const baseDir = codeLocation ? (0, import_node_path3.resolve)(codeLocation) : moduleDir;
+      const resolved = await resolveHandlerByModuleRef(handlerId, registry, baseDir);
+      return resolved ? buildCallback(resolved) : null;
     }
   };
 }
@@ -1903,7 +1996,7 @@ async function startRuntime(options) {
   const appConfig = app.setup();
   const result = await bootstrapForRuntime();
   for (const def of appConfig.api?.http?.handlers ?? []) {
-    const callback = result.createRouteCallback(def.path, def.method);
+    const callback = result.createRouteCallback(def.path, def.method) ?? await result.createRouteCallbackById(def.handler, def.location);
     if (callback) {
       app.registerHttpHandler(def.path, def.method, def.timeout, callback);
     }
@@ -1994,6 +2087,7 @@ __name(startRuntime, "startRuntime");
   mapToRuntimeResponse,
   mockRequest,
   registerModuleGraph,
+  resolveHandlerByModuleRef,
   runLayerPipeline,
   startRuntime,
   tokenToString,