@supacloud/elysia 0.1.0 → 0.2.0

package/README.md

@@ -1,55 +1,34 @@
 # @supacloud/elysia
 
-Elysia runtime adapter for SupaCloud applications: it adapts the plain-data
-`CompiledModule` produced by `@supacloud/compiler` into Elysia plugins and
-manages the `application` / `request` scopes at runtime.
-
-This package does **not** depend on the compiler. The contract below is
-declared and re-exported locally; any object matching it works.
-
-## Compiled module contract
-
-```ts
-interface CompiledRoute {
-  method: "GET" | "POST" | "PUT" | "PATCH" | "DELETE";
-  path: string;
-  handler: string;   // method name on the controller instance
-  body?: unknown;    // TypeBox schema; validation enabled only when present
-  params?: unknown;
-  query?: unknown;
-  response?: unknown;
-}
-
-interface CompiledController {
-  path: string;                       // controller prefix, e.g. "/cases"
-  serviceKey: string;                 // key on services or the request scope
-  scope: "application" | "request" | "job";
-  routes: CompiledRoute[];
-}
-
-interface CompiledModule {
-  name: string;
-  createServices(
-    deps: Record<string, unknown>,
-    imported: Record<string, Record<string, unknown>>,
-  ): Record<string, unknown>;
-  createRequestScope?(
-    services: Record<string, unknown>,
-    ctx: unknown,
-  ): Record<string, unknown>;
-  controllers: CompiledController[];
-}
+Runtime adapter that turns `@supacloud/compiler` output into a production-ready
+[Elysia](https://elysiajs.com/) application.
+
+## Features
+
+- **Decoupled compilation**: takes the output of `@supacloud/compiler` directly.
+- **Topological initialization**: modules are registered in dependency order,
+  passing exported services downstream via Elysia plugins.
+- **Request-scoped providers**: creates a fresh scope per HTTP request via
+  `createRequestScope`, mapping request-scoped controllers and services.
+- **TypeBox schema binding**: attaches compiled parameter, query, body, and
+  response TypeBox schemas directly to Elysia route definitions.
+- **Unified Command Pipeline**: runs `@Command`-decorated handlers through a
+  structured `commandGovernance` adapter chain or a custom `composeCommandExecutors`
+  pipeline (fail-closed if command routes lack an executor).
+- **Public error mapping**: transforms framework / application errors via
+  `errorMapper` with standard `ApplicationError` envelope support, preserving
+  Elysia's default behavior (422) for schema validation errors.
+
+## Installation
+
+```bash
+bun add @supacloud/elysia elysia
 ```
 
-Controller methods are invoked as
-`controller[handler]({ body, params, query, request, scope })`; non-`Response`
-return values are serialized to JSON by Elysia. Validation failures use
-Elysia's default behavior (422).
-
 ## Usage
 
 ```ts
-import { createApplication } from "@supacloud/elysia";
+import { composeCommandExecutors, createApplication, requireIdempotencyKey } from "@supacloud/elysia";
 import AuditModule from "./.generated/audit.module";
 import CaseModule from "./.generated/case.module";
 
@@ -57,45 +36,38 @@ const app = createApplication({
   name: "case-service",
   modules: [AuditModule, CaseModule], // topological import order
   deps: { db: createDbClient() },     // platform deps, passed to createServices
-  requestContext: (request) => ({
-    requestId: request.headers.get("x-request-id") ?? crypto.randomUUID(),
-    request,
-  }),
+  commandGovernance: {
+    authorize: (invocation) => authorize(invocation.requestContext, invocation.command.permission),
+    idempotency: (invocation, next) => idempotencyStore.run(requireIdempotencyKey(invocation), next),
+    transaction: (invocation, next) => transactionManager.run(invocation, next),
+    audit: {
+      succeeded: (invocation, result) => auditLog.record(invocation, result),
+      failed: (invocation, error) => auditLog.recordFailure(invocation, error),
+    },
+  },
+  // Or custom onion-style command pipeline:
+  // commandExecutor: composeCommandExecutors(outerMiddleware, innerMiddleware),
 });
 
 export default app;
 ```
 
-- Each module is instantiated in order: `createServices(deps, imported)`
-  receives platform `deps` plus the services of all previously created
-  modules, keyed by module name.
-- Each module becomes a named Elysia plugin (`supacloud:<module.name>`) that
-  decorates the context with `services`.
-- When a module defines `createRequestScope`, a **fresh** request scope is
-  resolved per request and exposed on the `scope` context key — never reused
-  across requests. Request-scoped controller instances are looked up on
-  `scope`; application-scoped instances on `services`.
-- Full route paths are `controller.path + route.path` (slashes normalized);
-  schema options (`body` / `params` / `query` / `response`) are passed to
-  Elysia only when the corresponding field exists.
-
-Lower-level building blocks:
-
-- `createModulePlugin(compiled, services, ctxFactory?)` — adapt a single
-  module into an Elysia plugin (useful for tests and embedding).
-- `createTestApp(options)` — semantic alias of `createApplication`.
-- `testRequest(app, path, init?)` (from `@supacloud/elysia` source
-  `src/testing.ts`) — in-process `app.handle(new Request(...))` helper.
-
-## Edge runtime integration
-
-SupaCloud's edge runtime (`@supacloud/edge-runtime`) supports Elysia as a
-first-class function framework. Default-export the Elysia instance from your
-function entrypoint and set the activation manifest to:
-
-```json
-{ "framework": "elysia" }
-```
+## API
+
+### `createApplication(options: ApplicationOptions): Elysia`
+
+Creates the root Elysia application from compiled modules.
+
+### `createModulePlugin(compiled, services, ctxFactory?, options?, imported?): Elysia`
+
+Creates an Elysia plugin from a single compiled module. Can be mounted
+directly onto an existing Elysia app.
+
+### `composeCommandExecutors(...executors): CommandExecutor`
+
+Composes multiple `CommandExecutor` middleware functions into an onion-style pipeline.
+
+### `ApplicationError`
 
-The runtime then routes requests through `app.handle(request)` instead of a
-plain `fetch` handler.
+Lightweight error class carrying HTTP `status`, machine-readable `code`, and
+optional structured `details`.

package/dist/index.d.ts

@@ -9,6 +9,16 @@ export interface CompiledRoute {
     params?: unknown;
     query?: unknown;
     response?: unknown;
+    /** Class name of the @Command explicitly bound to this route. */
+    command?: string;
+}
+export interface CompiledCommand {
+    className: string;
+    name: string;
+    permission?: string;
+    transaction?: "required" | "none" | string;
+    audit?: string;
+    idempotency?: "required" | "none" | string;
 }
 export interface CompiledController {
     /** Controller path prefix, e.g. "/cases". */
@@ -21,10 +31,81 @@ export interface CompiledController {
 export interface CompiledModule {
     name: string;
     createServices(deps: Record<string, unknown>, imported: Record<string, Record<string, unknown>>): Record<string, unknown>;
-    createRequestScope?(services: Record<string, unknown>, ctx: unknown): Record<string, unknown>;
+    createRequestScope?(services: Record<string, unknown>, ctx: unknown, imported?: Record<string, Record<string, unknown>>): Record<string, unknown>;
     controllers: CompiledController[];
+    commands?: CompiledCommand[];
 }
 export type RequestContextFactory = (request: Request) => unknown | Promise<unknown>;
+export declare const VERIFIED_JWT_SUBJECT_HEADER = "x-supacloud-jwt-sub";
+export declare const EXECUTION_ID_HEADER = "x-sb-execution-id";
+export declare const IDEMPOTENCY_KEY_HEADER = "idempotency-key";
+export interface TrustedRequestIdentity {
+    authenticated: boolean;
+    /** Subject verified and forwarded by the SupaCloud Edge Runtime. */
+    subject?: string;
+    /** Bearer token associated with the verified subject. Never log this value. */
+    accessToken?: string;
+}
+export interface SupaCloudRequestContext {
+    requestId: string;
+    request: Request;
+    identity: TrustedRequestIdentity;
+    idempotencyKey?: string;
+}
+export interface CommandInvocation {
+    command: CompiledCommand;
+    input: {
+        body: unknown;
+        params: Record<string, string>;
+        query: Record<string, unknown>;
+    };
+    request: Request;
+    requestContext: unknown;
+    scope?: Record<string, unknown>;
+    services: Record<string, unknown>;
+}
+export type CommandExecutor = (invocation: CommandInvocation, next: () => unknown | Promise<unknown>) => unknown | Promise<unknown>;
+export type CommandAuthorizer = (invocation: CommandInvocation) => void | Promise<void>;
+export type CommandMiddleware = (invocation: CommandInvocation, next: () => unknown | Promise<unknown>) => unknown | Promise<unknown>;
+export interface CommandAudit {
+    succeeded(invocation: CommandInvocation, result: unknown): void | Promise<void>;
+    failed(invocation: CommandInvocation, error: unknown): void | Promise<void>;
+}
+export interface CommandGovernance {
+    authorize: CommandAuthorizer;
+    idempotency?: CommandMiddleware;
+    transaction?: CommandMiddleware;
+    audit?: CommandAudit;
+}
+/**
+ * Compose multiple CommandExecutors into a single onion-style pipeline.
+ * Outer executors run first before calling `next()`, and complete last.
+ */
+export declare function composeCommandExecutors(...executors: (CommandExecutor | undefined | null)[]): CommandExecutor;
+export interface ApplicationErrorOptions {
+    status?: number;
+    code?: string;
+    details?: unknown;
+}
+export interface PublicApplicationError extends Error {
+    readonly expose: true;
+    readonly status: number;
+    readonly code: string;
+    readonly details?: unknown;
+}
+export declare class ApplicationError extends Error implements PublicApplicationError {
+    readonly expose: true;
+    readonly status: number;
+    readonly code: string;
+    readonly details?: unknown;
+    constructor(message: string, options?: ApplicationErrorOptions);
+}
+export interface ErrorContext {
+    request: Request;
+    requestContext: unknown;
+    frameworkCode: string | number | undefined;
+}
+export type ErrorMapper = (error: unknown, context: ErrorContext) => Response | undefined | Promise<Response | undefined>;
 export interface ApplicationOptions {
     name?: string;
     /** Modules in topological import order. */
@@ -33,7 +114,27 @@ export interface ApplicationOptions {
     deps?: Record<string, unknown>;
     /** Builds the per-request context object. Defaults to { requestId, request }. */
     requestContext?: RequestContextFactory;
+    /** Enforces permission/audit/idempotency policy for command-bound routes. */
+    commandGovernance?: CommandGovernance;
+    /** Optional custom or composed executor. When provided alongside commandGovernance, it wraps or composes with governance. */
+    commandExecutor?: CommandExecutor;
+    /** Maps framework or application failures to the public HTTP contract. */
+    errorMapper?: ErrorMapper;
 }
+/**
+ * Build the standard request context for applications behind SupaCloud Edge
+ * Runtime. The runtime strips incoming x-supacloud-jwt-sub values and writes
+ * the header only after JWT verification.
+ */
+export declare const createSupaCloudRequestContext: RequestContextFactory;
+/**
+ * Compose the standard command governance order:
+ * authorization -> idempotency -> transaction -> audit -> handler.
+ * Declared governance metadata fails closed when its adapter is absent.
+ */
+export declare function createCommandExecutor(governance: CommandGovernance): CommandExecutor;
+export declare function requireTrustedIdentity(requestContext: unknown): Required<Pick<TrustedRequestIdentity, "subject" | "accessToken">> & TrustedRequestIdentity;
+export declare function requireIdempotencyKey(invocation: CommandInvocation): string;
 /**
  * Adapt a single compiled module into an Elysia plugin.
  *
@@ -42,7 +143,8 @@ export interface ApplicationOptions {
  * exposed on the `scope` context key. Request-scoped controller instances are
  * looked up on `scope`, everything else on `services`.
  */
-export declare function createModulePlugin(compiled: CompiledModule, services: Record<string, unknown>, ctxFactory?: RequestContextFactory): Elysia;
+export declare function createModulePlugin(compiled: CompiledModule, services: Record<string, unknown>, ctxFactory?: RequestContextFactory, options?: Pick<ApplicationOptions, "commandGovernance" | "commandExecutor" | "errorMapper">, imported?: Record<string, Record<string, unknown>>): Elysia;
+export declare function defaultErrorResponse(error: unknown, frameworkCode?: string | number): Response;
 /**
  * Create the root Elysia application from compiled modules.
  *

package/dist/index.js

@@ -1,21 +1,178 @@
 // src/index.ts
 import { Elysia } from "elysia";
-var defaultRequestContext = (request) => ({
-  requestId: crypto.randomUUID(),
-  request
-});
+var VERIFIED_JWT_SUBJECT_HEADER = "x-supacloud-jwt-sub";
+var EXECUTION_ID_HEADER = "x-sb-execution-id";
+var IDEMPOTENCY_KEY_HEADER = "idempotency-key";
+function composeCommandExecutors(...executors) {
+  const active = executors.filter((e) => typeof e === "function");
+  if (active.length === 0)
+    return (_inv, next) => next();
+  return (invocation, next) => {
+    let index = -1;
+    const dispatch = (i) => {
+      if (i <= index) {
+        return Promise.reject(new Error("next() called multiple times"));
+      }
+      index = i;
+      if (i === active.length) {
+        return Promise.resolve(next());
+      }
+      const fn = active[i];
+      if (!fn) {
+        return Promise.resolve(next());
+      }
+      return Promise.resolve(fn(invocation, () => dispatch(i + 1)));
+    };
+    return dispatch(0);
+  };
+}
+
+class ApplicationError extends Error {
+  expose = true;
+  status;
+  code;
+  details;
+  constructor(message, options = {}) {
+    super(message);
+    this.name = "ApplicationError";
+    this.status = options.status ?? 500;
+    this.code = options.code ?? "INTERNAL_ERROR";
+    this.details = options.details;
+  }
+}
+function safeHeaderValue(value, maxLength) {
+  if (!value || value.length > maxLength || /[\u0000-\u001f\u007f]/.test(value)) {
+    return;
+  }
+  return value;
+}
+function bearerToken(request) {
+  const authorization = request.headers.get("authorization");
+  const match = authorization?.match(/^Bearer\s+(.+)$/i);
+  return match ? safeHeaderValue(match[1], 16384) : undefined;
+}
+var createSupaCloudRequestContext = (request) => {
+  const subject = safeHeaderValue(request.headers.get(VERIFIED_JWT_SUBJECT_HEADER), 1024);
+  const accessToken = subject ? bearerToken(request) : undefined;
+  const requestId = safeHeaderValue(request.headers.get(EXECUTION_ID_HEADER), 256) ?? safeHeaderValue(request.headers.get("x-request-id"), 256) ?? crypto.randomUUID();
+  const idempotencyKey = safeHeaderValue(request.headers.get(IDEMPOTENCY_KEY_HEADER), 512);
+  const identity = {
+    authenticated: subject !== undefined,
+    ...subject === undefined ? {} : { subject }
+  };
+  if (accessToken !== undefined) {
+    Object.defineProperty(identity, "accessToken", {
+      value: accessToken,
+      enumerable: false,
+      configurable: false
+    });
+  }
+  return {
+    requestId,
+    request,
+    identity,
+    ...idempotencyKey === undefined ? {} : { idempotencyKey }
+  };
+};
+var defaultRequestContext = createSupaCloudRequestContext;
+function missingGovernanceAdapter(command, adapter) {
+  const codes = {
+    idempotency: "COMMAND_IDEMPOTENCY_UNAVAILABLE",
+    transaction: "COMMAND_TRANSACTION_UNAVAILABLE",
+    audit: "COMMAND_AUDIT_UNAVAILABLE"
+  };
+  return new ApplicationError(`Command "${command.name}" requires a ${adapter} adapter`, {
+    status: 501,
+    code: codes[adapter]
+  });
+}
+function createCommandExecutor(governance) {
+  return async (invocation, next) => {
+    const { command } = invocation;
+    if (command.audit && !governance.audit) {
+      throw missingGovernanceAdapter(command, "audit");
+    }
+    if (command.transaction === "required" && !governance.transaction) {
+      throw missingGovernanceAdapter(command, "transaction");
+    }
+    if (command.idempotency === "required" && !governance.idempotency) {
+      throw missingGovernanceAdapter(command, "idempotency");
+    }
+    try {
+      await governance.authorize(invocation);
+      let execute = async () => {
+        const result = await next();
+        if (command.audit)
+          await governance.audit.succeeded(invocation, result);
+        return result;
+      };
+      if (command.transaction === "required") {
+        const inner = execute;
+        execute = () => Promise.resolve(governance.transaction(invocation, inner));
+      }
+      if (command.idempotency === "required") {
+        const inner = execute;
+        execute = () => Promise.resolve(governance.idempotency(invocation, inner));
+      }
+      return await execute();
+    } catch (error) {
+      if (command.audit)
+        await governance.audit.failed(invocation, error);
+      throw error;
+    }
+  };
+}
+function requireTrustedIdentity(requestContext) {
+  const context = requestContext;
+  const identity = context?.identity;
+  if (!identity?.authenticated || !identity.subject || !identity.accessToken) {
+    throw new ApplicationError("Authenticated user context is required", {
+      status: 401,
+      code: "AUTHENTICATION_REQUIRED"
+    });
+  }
+  return identity;
+}
+function requireIdempotencyKey(invocation) {
+  const context = invocation.requestContext;
+  const key = context?.idempotencyKey ?? safeHeaderValue(invocation.request.headers.get(IDEMPOTENCY_KEY_HEADER), 512);
+  if (!key) {
+    throw new ApplicationError("Idempotency-Key header is required", {
+      status: 400,
+      code: "IDEMPOTENCY_KEY_REQUIRED"
+    });
+  }
+  return key;
+}
 function joinPaths(prefix, path) {
   const joined = `${prefix}/${path}`.replace(/\/{2,}/g, "/");
   return joined.length > 1 ? joined.replace(/\/+$/, "") : joined;
 }
-function createModulePlugin(compiled, services, ctxFactory = defaultRequestContext) {
-  const plugin = new Elysia({ name: `supacloud:${compiled.name}` }).decorate("services", services);
-  if (compiled.createRequestScope) {
-    const createRequestScope = compiled.createRequestScope;
-    plugin.resolve(async ({ request }) => ({
-      scope: createRequestScope(services, await ctxFactory(request))
-    }));
+function createModulePlugin(compiled, services, ctxFactory = defaultRequestContext, options = {}, imported = {}) {
+  const hasCommandRoutes = compiled.controllers.some((controller) => controller.routes.some((route) => route.command !== undefined));
+  if (hasCommandRoutes && !options.commandGovernance && !options.commandExecutor) {
+    throw new ApplicationError(`Module "${compiled.name}" has command routes but no commandGovernance`, { code: "COMMAND_GOVERNANCE_UNCONFIGURED" });
   }
+  const commandsByClassName = new Map((compiled.commands ?? []).map((command) => [command.className, command]));
+  for (const controller of compiled.controllers) {
+    for (const route of controller.routes) {
+      if (route.command && !commandsByClassName.has(route.command)) {
+        throw new ApplicationError(`Command "${route.command}" is not registered`, {
+          code: "COMMAND_NOT_REGISTERED"
+        });
+      }
+    }
+  }
+  const requestContexts = new WeakMap;
+  const governanceExecutor = options.commandGovernance ? createCommandExecutor(options.commandGovernance) : undefined;
+  const commandExecutor = options.commandExecutor && governanceExecutor ? composeCommandExecutors(options.commandExecutor, governanceExecutor) : options.commandExecutor ?? governanceExecutor;
+  const plugin = new Elysia({ name: `supacloud:${compiled.name}` }).decorate("services", services);
+  const createRequestScope = compiled.createRequestScope;
+  plugin.resolve(async ({ request }) => {
+    const requestContext = await ctxFactory(request);
+    requestContexts.set(request, requestContext);
+    return { requestContext };
+  });
   for (const controller of compiled.controllers) {
     for (const route of controller.routes) {
       const path = joinPaths(controller.path, route.path);
@@ -29,19 +186,40 @@ function createModulePlugin(compiled, services, ctxFactory = defaultRequestConte
       if (route.response !== undefined)
         schema.response = route.response;
       const handler = async (ctx) => {
-        const source = controller.scope === "request" ? ctx.scope : services;
+        const requestContext = ctx.requestContext ?? await ctxFactory(ctx.request);
+        const requestScope = createRequestScope ? createRequestScope(services, requestContext, imported) : undefined;
+        const source = controller.scope === "request" ? requestScope : services;
         const instance = source?.[controller.serviceKey];
         const method = instance?.[route.handler];
         if (typeof method !== "function") {
           throw new Error(`supacloud: controller "${controller.serviceKey}" has no handler "${route.handler}" in scope "${controller.scope}"`);
         }
-        return method.call(instance, {
+        const input = {
           body: ctx.body,
           params: ctx.params,
           query: ctx.query,
           request: ctx.request,
-          scope: ctx.scope
-        });
+          scope: requestScope,
+          requestContext
+        };
+        const invoke = () => method.call(instance, input);
+        if (!route.command)
+          return invoke();
+        const command = commandsByClassName.get(route.command);
+        if (!commandExecutor) {
+          throw new ApplicationError(`Command "${command.name}" has no executor`, {
+            status: 501,
+            code: "COMMAND_EXECUTOR_UNAVAILABLE"
+          });
+        }
+        return commandExecutor({
+          command,
+          input,
+          request: ctx.request,
+          requestContext,
+          scope: requestScope,
+          services
+        }, invoke);
       };
       switch (route.method) {
         case "GET":
@@ -62,16 +240,66 @@ function createModulePlugin(compiled, services, ctxFactory = defaultRequestConte
       }
     }
   }
+  plugin.onError({ as: "global" }, async ({ code, error, request }) => {
+    const context = {
+      request,
+      requestContext: requestContexts.get(request),
+      frameworkCode: code
+    };
+    const mapped = await options.errorMapper?.(error, context);
+    return mapped ?? defaultErrorResponse(error, code);
+  });
   return plugin;
 }
+function defaultErrorResponse(error, frameworkCode) {
+  if (isPublicApplicationError(error)) {
+    return Response.json({
+      ok: false,
+      code: error.code,
+      message: error.message,
+      ...error.details === undefined ? {} : { details: error.details }
+    }, { status: error.status });
+  }
+  if (frameworkCode === "VALIDATION") {
+    return Response.json({
+      ok: false,
+      code: "VALIDATION_ERROR",
+      message: "Request validation failed"
+    }, { status: 422 });
+  }
+  return Response.json({
+    ok: false,
+    code: "INTERNAL_ERROR",
+    message: "Internal Server Error"
+  }, { status: 500 });
+}
+function isPublicApplicationError(error) {
+  if (!(error instanceof Error))
+    return false;
+  const candidate = error;
+  return candidate.expose === true && typeof candidate.status === "number" && Number.isInteger(candidate.status) && candidate.status >= 400 && candidate.status <= 599 && typeof candidate.code === "string" && candidate.code.length > 0;
+}
 function createApplication(options) {
   const app = new Elysia({ name: options.name ?? "supacloud:app" });
-  const ctxFactory = options.requestContext ?? defaultRequestContext;
+  const configuredContextFactory = options.requestContext ?? defaultRequestContext;
+  const contextCache = new WeakMap;
+  const ctxFactory = (request) => {
+    const cached = contextCache.get(request);
+    if (cached)
+      return cached;
+    const pending = Promise.resolve(configuredContextFactory(request));
+    contextCache.set(request, pending);
+    return pending;
+  };
   const imported = {};
   for (const module of options.modules) {
     const services = module.createServices(options.deps ?? {}, imported);
     imported[module.name] = services;
-    app.use(createModulePlugin(module, services, ctxFactory));
+    app.use(createModulePlugin(module, services, ctxFactory, {
+      commandGovernance: options.commandGovernance,
+      commandExecutor: options.commandExecutor,
+      errorMapper: options.errorMapper
+    }, imported));
   }
   return app;
 }
@@ -79,7 +307,17 @@ function createTestApp(options) {
   return createApplication(options);
 }
 export {
+  ApplicationError,
+  EXECUTION_ID_HEADER,
+  IDEMPOTENCY_KEY_HEADER,
+  VERIFIED_JWT_SUBJECT_HEADER,
+  composeCommandExecutors,
   createApplication,
+  createCommandExecutor,
   createModulePlugin,
-  createTestApp
+  createSupaCloudRequestContext,
+  createTestApp,
+  defaultErrorResponse,
+  requireIdempotencyKey,
+  requireTrustedIdentity
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@supacloud/elysia",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "Elysia runtime adapter for SupaCloud compiled modules: application/request scopes, route registration and validation",
   "type": "module",
   "main": "./dist/index.js",