@lostgradient/weft 0.2.0

package/dist/server/handler/route-dispatch.d.ts

@@ -0,0 +1,144 @@
+import type { Engine } from '../../core/engine.ts';
+import { type PrometheusExporter } from '../../observability/metrics.ts';
+import type { AuthContext } from '../authentication.ts';
+import type { DiscoveryInfo } from '../discovery-info.ts';
+import { type OpenApiSecuritySchemeName } from '../openapi.ts';
+import { type OperationRegistry, type PipelineTrace } from '../operation-catalog.ts';
+import type { OperationFault } from '../operation-fault.ts';
+import { type Principal } from '../principal.ts';
+import { type UnknownRestBinding } from '../rest-bindings.ts';
+import type { DirectRouteHandlerName } from './route-matching.ts';
+/** Alias for `AuthContext` — kept local so handler-internal code reads naturally. */
+type AuthenticatedRequestContext = AuthContext;
+/**
+ * Options bag passed to `handleRequest` by the HTTP server wrapper.
+ *
+ * Injects the resolved authentication context, custom metrics exporters, and
+ * an optional override for the operation registry and REST bindings.  Omit
+ * `operationRegistry` and `restBindings` together to use the live defaults.
+ *
+ * @example
+ * ```ts
+ * import { type HandlerOptions } from '@lostgradient/weft/server/handler';
+ *
+ * const options: HandlerOptions = {
+ *   authContext: { method: 'public' },
+ * };
+ * void options;
+ * ```
+ */
+export interface HandlerOptions {
+    /**
+     * Optional authenticated caller context injected by the HTTP server
+     * wrapper. See `AuthContext` in `authentication.ts` for field documentation.
+     */
+    authContext?: AuthContext;
+    /**
+     * Optional {@link PrometheusExporter} used to produce the body of
+     * `/v1/metrics`. This is the plug point for projects that source metrics
+     * from the OpenTelemetry SDK (e.g. via `@opentelemetry/exporter-prometheus`).
+     */
+    prometheusExporter?: PrometheusExporter;
+    /**
+     * Operation registry for pipeline dispatch. Must be supplied together
+     * with `restBindings` — a caller that overrides one but not the other
+     * gets a mismatched configuration (custom bindings referencing a live
+     * registry they weren't built against), which `handleRequest` rejects
+     * at request time. Omit both to use the live defaults.
+     */
+    operationRegistry?: OperationRegistry;
+    /**
+     * REST bindings. A request whose method+path matches a binding routes
+     * through the `executeOperation` pipeline. Must be supplied together
+     * with `operationRegistry`. Omit both to use the live defaults.
+     */
+    restBindings?: ReadonlyArray<UnknownRestBinding>;
+    /** OpenAPI security schemes supported by the live server configuration. */
+    supportedAuthenticationSchemes?: ReadonlySet<OpenApiSecuritySchemeName>;
+    /**
+     * Operator-supplied metadata applied uniformly to all three discovery
+     * documents (`/openapi.json`, `/openrpc.json`, `/asyncapi.json`).
+     */
+    discoveryInfo?: DiscoveryInfo;
+    /**
+     * Optional explicit public origin used when emitting absolute URLs in
+     * discovery routes such as `/.well-known/api-catalog` and
+     * `/.well-known/mcp.json`. Recommended in production to avoid trusting
+     * attacker-controlled `Host` / `X-Forwarded-Proto` headers. Takes precedence
+     * over `trustedHosts`.
+     */
+    publicOrigin?: string;
+    /**
+     * Optional allowlist of `Host` values that are trusted as the source of
+     * absolute service-desc URLs in discovery routes such as
+     * `/.well-known/api-catalog` and `/.well-known/mcp.json`. The route derives
+     * the origin from the incoming request and rejects (421
+     * Misdirected Request) if the resolved Host is not in this list.
+     *
+     * Either `publicOrigin` OR `trustedHosts` must be configured in
+     * production deployments — without one, the route returns 503 because
+     * `Bun.serve()` trusts the Host header in `request.url` and an attacker
+     * can otherwise poison the discovery URLs.
+     */
+    trustedHosts?: ReadonlyArray<string>;
+    /**
+     * Optional pipeline-trace observer. **Internal test seam** used by the
+     * dispatch-audit suite to prove every transport drives the full
+     * `executeOperation` pipeline. Production callers should not set this
+     * — the parameter has no other effect on dispatch behavior.
+     *
+     * @internal
+     */
+    pipelineTrace?: PipelineTrace;
+}
+export type RouteExecutionContext = {
+    request: Request;
+    engine: Engine;
+    options: HandlerOptions | undefined;
+};
+export type RouteExecutor = (context: RouteExecutionContext) => Promise<Response>;
+export declare const DIRECT_ROUTE_EXECUTORS: Record<DirectRouteHandlerName, RouteExecutor>;
+export declare function dispatchViaExecuteOperation(request: Request, engine: Engine, binding: UnknownRestBinding, pathParams: Record<string, string>, registry: OperationRegistry, principal: Principal, pipelineTrace?: PipelineTrace): Promise<Response>;
+/**
+ * Type guard that returns true if the value structurally resembles an
+ * {@link OperationFault} (carries `code`, `message`, and `data` properties).
+ *
+ * Used by error handlers to decide whether a thrown value can be mapped to a
+ * structured operation fault response, vs. needing to be wrapped in a generic
+ * 500.
+ *
+ * @example Catch an unknown error and surface as a fault when it qualifies
+ * ```ts
+ * import { isOperationFaultLike } from '@lostgradient/weft/server/handler';
+ *
+ * try {
+ *   // operation handler runs here
+ * } catch (error) {
+ *   if (isOperationFaultLike(error)) {
+ *     // structured fault — pass through
+ *   } else {
+ *     // unknown — wrap as 500
+ *   }
+ * }
+ * ```
+ */
+export declare function isOperationFaultLike(value: unknown): value is OperationFault;
+/**
+ * Convert the REST transport's `authContext` into a `Principal`. The
+ * authenticator (`serve()`) only reports method + optional claims; this
+ * shim bridges that into the richer `Principal` the pipeline expects.
+ * Returns `anonymousPrincipal()` when no context is provided (public
+ * request).
+ *
+ * @example
+ * ```ts
+ * import { authContextToPrincipal } from '@lostgradient/weft/server/handler';
+ *
+ * const principal = authContextToPrincipal({ method: 'api-key' });
+ * console.log(principal.method); // 'api-key'
+ * ```
+ */
+export declare function authContextToPrincipal(authContext: AuthenticatedRequestContext | undefined): Principal;
+export declare function defaultOperationRegistry(): OperationRegistry;
+export declare function defaultRestBindings(): ReadonlyArray<UnknownRestBinding>;
+export {};

package/dist/server/handler/route-dispatch.js

@@ -0,0 +1,192 @@
+import { listMcpTools } from "../../mcp/tools.js";
+import {
+  createMetricsCollectorExporter
+} from "../../observability/metrics.js";
+import { generateApiCatalog, originFromRequest, warnIfPublicOriginUnset } from "../api-catalog.js";
+import { generateAsyncApiDocument } from "../asyncapi.js";
+import { faultToHttpResponse } from "../fault-to-http.js";
+import { generateMcpDiscovery } from "../mcp-discovery.js";
+import { generateOpenApiDocument } from "../openapi.js";
+import { generateOpenRpcDocument } from "../openrpc.js";
+import {
+  executeOperation
+} from "../operation-catalog.js";
+import { FAULT_CODE_TO_HTTP_STATUS } from "../operation-fault.js";
+import {
+  anonymousPrincipal,
+  principalFromApiKey,
+  principalFromJwtClaims,
+  principalFromMutualTls
+} from "../principal.js";
+import {
+  createLiveOperationRegistry,
+  createLiveRestBindings
+} from "../rest-bindings.js";
+import {
+  defaultShapeSuccess,
+  errorResponse,
+  jsonResponse,
+  negotiatedResponse
+} from "./response-helpers.js";
+const defaultPrometheusExporter = createMetricsCollectorExporter(void 0);
+function resolveDiscoveryOrigin(options) {
+  const { absoluteUrlDescription, path, request, serverOptions } = options;
+  if (serverOptions?.publicOrigin !== void 0)
+    return { origin: serverOptions.publicOrigin };
+  const requestOrigin = originFromRequest(request);
+  if (serverOptions?.trustedHosts !== void 0) {
+    const requestHost = new URL(requestOrigin).host;
+    if (!serverOptions.trustedHosts.includes(requestHost))
+      return {
+        response: errorResponse("request Host is not in the configured trustedHosts allowlist", 421)
+      };
+    return { origin: requestOrigin };
+  }
+  const isDevelopment = Bun.env.NODE_ENV === "development", operatorOverride = Bun.env.WEFT_ALLOW_UNTRUSTED_API_CATALOG_ORIGIN === "1";
+  if (!isDevelopment && !operatorOverride)
+    return {
+      response: errorResponse(`${path} refuses to emit ${absoluteUrlDescription} without one of \`publicOrigin\` or \`trustedHosts\` configured. Set \`serve({ publicOrigin: 'https://api.example.com' })\` or \`serve({ trustedHosts: ['api.example.com'] })\`. For local development, set NODE_ENV=development; for CI/test overrides set WEFT_ALLOW_UNTRUSTED_API_CATALOG_ORIGIN=1.`, 503)
+    };
+  warnIfPublicOriginUnset();
+  return { origin: requestOrigin };
+}
+async function handleGetMetrics(prometheusExporter = defaultPrometheusExporter) {
+  let body;
+  try {
+    body = await prometheusExporter.serialize();
+  } catch (error) {
+    console.error("PrometheusExporter.serialize() threw", { error });
+    return new Response(JSON.stringify({ error: "metrics exporter failed" }), {
+      status: 503,
+      headers: { "Content-Type": "application/json; charset=utf-8" }
+    });
+  }
+  return new Response(body, {
+    status: 200,
+    headers: { "Content-Type": "text/plain; charset=utf-8" }
+  });
+}
+export const DIRECT_ROUTE_EXECUTORS = {
+  healthCheck: async ({ request }) => negotiatedResponse(request, { status: "ok" }),
+  getMetrics: async ({ options }) => handleGetMetrics(options?.prometheusExporter),
+  apiCatalog: async ({ request, options }) => {
+    const originResolution = resolveDiscoveryOrigin({
+      absoluteUrlDescription: "absolute service-desc URLs",
+      path: "/.well-known/api-catalog",
+      request,
+      serverOptions: options
+    });
+    if (originResolution.response !== void 0)
+      return originResolution.response;
+    const body = generateApiCatalog({ origin: originResolution.origin });
+    return new Response(JSON.stringify(body), {
+      status: 200,
+      headers: { "Content-Type": "application/linkset+json" }
+    });
+  },
+  mcpDiscovery: async ({ request, options }) => {
+    const originResolution = resolveDiscoveryOrigin({
+      absoluteUrlDescription: "absolute MCP endpoint URLs",
+      path: "/.well-known/mcp.json",
+      request,
+      serverOptions: options
+    });
+    if (originResolution.response !== void 0)
+      return originResolution.response;
+    return jsonResponse(generateMcpDiscovery({ origin: originResolution.origin }));
+  },
+  openApiDocument: async ({ options }) => jsonResponse(generateOpenApiDocument({
+    registry: options?.operationRegistry ?? defaultOperationRegistry(),
+    ...options?.restBindings !== void 0 ? { restBindings: options.restBindings } : {},
+    ...options?.supportedAuthenticationSchemes !== void 0 ? { supportedSchemes: options.supportedAuthenticationSchemes } : {},
+    ...options?.discoveryInfo !== void 0 ? { discoveryInfo: options.discoveryInfo } : {}
+  })),
+  openRpcDocument: async ({ engine, options }) => jsonResponse(generateOpenRpcDocument({
+    registry: options?.operationRegistry ?? defaultOperationRegistry(),
+    transports: ["http", "websocket"],
+    mcpTools: listMcpTools(engine),
+    ...options?.discoveryInfo !== void 0 ? { discoveryInfo: options.discoveryInfo } : {}
+  })),
+  asyncApiDocument: async ({ options }) => jsonResponse(generateAsyncApiDocument({
+    registry: options?.operationRegistry ?? defaultOperationRegistry(),
+    ...options?.restBindings !== void 0 ? { restBindings: options.restBindings } : {},
+    ...options?.discoveryInfo !== void 0 ? { discoveryInfo: options.discoveryInfo } : {}
+  }))
+};
+export async function dispatchViaExecuteOperation(request, engine, binding, pathParams, registry, principal, pipelineTrace) {
+  let input;
+  try {
+    input = await binding.extractInput(request, pathParams);
+  } catch (error) {
+    if (isOperationFaultLike(error))
+      return binding.shapeFault ? binding.shapeFault(error) : faultToHttpResponse(error);
+    const message = error instanceof Error ? error.message : String(error);
+    return errorResponse(message, 400);
+  }
+  const result = await executeOperation(binding.operationName, input, {
+    principal,
+    engine,
+    transport: "http-rest",
+    registry,
+    ...pipelineTrace !== void 0 ? { pipelineTrace } : {}
+  });
+  if (result.ok)
+    return binding.shapeSuccess ? binding.shapeSuccess(result.value, request) : defaultShapeSuccess(result.value, binding.success);
+  return binding.shapeFault ? binding.shapeFault(result.fault) : faultToHttpResponse(result.fault);
+}
+function hasRequiredFaultProperties(candidate) {
+  return Object.hasOwn(candidate, "code") && Object.hasOwn(candidate, "message") && Object.hasOwn(candidate, "data");
+}
+function readFaultProperties(candidate) {
+  try {
+    return {
+      code: candidate.code,
+      message: candidate.message,
+      data: candidate.data
+    };
+  } catch {
+    return null;
+  }
+}
+export function isOperationFaultLike(value) {
+  if (typeof value !== "object" || value === null)
+    return !1;
+  const candidate = value;
+  if (!hasRequiredFaultProperties(candidate))
+    return !1;
+  const fields = readFaultProperties(candidate);
+  if (fields === null)
+    return !1;
+  return typeof fields.code === "string" && Object.hasOwn(FAULT_CODE_TO_HTTP_STATUS, fields.code) && typeof fields.message === "string" && typeof fields.data === "object" && fields.data !== null && !Array.isArray(fields.data);
+}
+export function authContextToPrincipal(authContext) {
+  if (authContext === void 0)
+    return anonymousPrincipal();
+  if (authContext.principal !== void 0)
+    return authContext.principal;
+  switch (authContext.method) {
+    case "jwt": {
+      if (authContext.claims === void 0)
+        throw Error("authContextToPrincipal: jwt authContext reached the pipeline without claims \u2014 " + "authenticator contract violation");
+      return principalFromJwtClaims(authContext.claims);
+    }
+    case "api-key":
+      return principalFromApiKey({ subject: "api-key-caller", scopes: [] });
+    case "mtls":
+      return principalFromMutualTls({ subject: "mtls-caller", scopes: [] });
+    case "public":
+      return anonymousPrincipal();
+  }
+}
+let defaultOperationRegistryCache;
+export function defaultOperationRegistry() {
+  if (defaultOperationRegistryCache === void 0)
+    defaultOperationRegistryCache = createLiveOperationRegistry();
+  return defaultOperationRegistryCache;
+}
+let defaultRestBindingsCache;
+export function defaultRestBindings() {
+  if (defaultRestBindingsCache === void 0)
+    defaultRestBindingsCache = createLiveRestBindings();
+  return defaultRestBindingsCache;
+}

package/dist/server/handler/route-matching.d.ts

@@ -0,0 +1,55 @@
+import { DIRECT_HTTP_ROUTES } from '../route-model.ts';
+/** Union of all handler names derived from the shared direct-route model. */
+export type DirectRouteHandlerName = (typeof DIRECT_HTTP_ROUTES)[number]['handler'];
+export type RouteMatch = {
+    handler: DirectRouteHandlerName;
+    params: Record<string, string>;
+    path: string;
+};
+export declare function matchDirectRoute(method: string, pathname: string): RouteMatch | null;
+/**
+ * Extract path parameter values from a regex match against a route pattern.
+ *
+ * Pairs the ordered `parameterNames` (from the route's compiled pattern)
+ * with the corresponding capture groups in `match`, decoding each value with
+ * `decodeURIComponent`. Used by route dispatchers to turn a regex hit into a
+ * `{ paramName: value }` map for the operation handler.
+ *
+ * The in-tree direct routes are parameter-free meta endpoints. The function
+ * remains public for tests and user-supplied route extensions.
+ *
+ * @example Extract route params from a synthetic custom route
+ * ```ts
+ * import { extractRouteParameters } from '@lostgradient/weft/server/handler';
+ *
+ * const pattern = /^\/projects\/([^/]+)\/workflows\/([^/]+)$/;
+ * const match = pattern.exec('/projects/acme/workflows/wf-42');
+ * if (match) {
+ *   const params = extractRouteParameters(['projectId', 'workflowId'], match);
+ *   console.log(params); // { projectId: 'acme', workflowId: 'wf-42' }
+ * }
+ * ```
+ */
+export declare function extractRouteParameters(parameterNames: readonly string[], match: Pick<RegExpExecArray, number | 'length'>): Record<string, string>;
+/**
+ * Extracts a named parameter from a route parameter map, throwing a descriptive
+ * `Error` if the parameter is absent.
+ *
+ * Used by direct-route helpers and any user-supplied route handlers that
+ * extend the catalog. In-tree `RestBinding` routes do not call this function;
+ * they receive a pre-populated `pathParams` map from `bindingPathMatches` via
+ * `RestBinding.extractInput`.
+ *
+ * @example
+ * ```ts
+ * import { getRequiredRouteParameter } from '@lostgradient/weft/server/handler';
+ *
+ * const params = { workflowId: 'wf-123' };
+ * const id = getRequiredRouteParameter(params, 'workflowId', 'GET /v1/workflows/:workflowId');
+ * console.log(id); // 'wf-123'
+ *
+ * // Throws: Missing route parameter "workflowId" for GET /v1/workflows/:workflowId
+ * getRequiredRouteParameter({}, 'workflowId', 'GET /v1/workflows/:workflowId');
+ * ```
+ */
+export declare function getRequiredRouteParameter(params: Record<string, string>, name: string, routeDescription: string): string;

package/dist/server/handler/route-matching.js

@@ -0,0 +1,45 @@
+import { MalformedRouteParameterError } from "../rest-binding.js";
+import { DIRECT_HTTP_ROUTES, toRegex } from "../route-model.js";
+const DIRECT_ROUTE_PATTERNS = [];
+for (const route of DIRECT_HTTP_ROUTES)
+  DIRECT_ROUTE_PATTERNS.push({
+    method: route.method,
+    pattern: toRegex(route.path),
+    handler: route.handler,
+    path: route.path,
+    paramNames: route.paramNames
+  });
+export function matchDirectRoute(method, pathname) {
+  for (const route of DIRECT_ROUTE_PATTERNS) {
+    if (route.method !== method)
+      continue;
+    const match = route.pattern.exec(pathname);
+    if (!match)
+      continue;
+    return {
+      handler: route.handler,
+      params: extractRouteParameters(route.paramNames, match),
+      path: route.path
+    };
+  }
+  return null;
+}
+export function extractRouteParameters(parameterNames, match) {
+  const params = {};
+  for (let index = 0;index < parameterNames.length; index += 1) {
+    const name = parameterNames[index], value = match[index + 1];
+    if (name !== void 0 && value !== void 0)
+      try {
+        params[name] = decodeURIComponent(value);
+      } catch {
+        throw new MalformedRouteParameterError;
+      }
+  }
+  return params;
+}
+export function getRequiredRouteParameter(params, name, routeDescription) {
+  const value = params[name];
+  if (value === void 0)
+    throw Error(`Missing route parameter "${name}" for ${routeDescription}`);
+  return value;
+}

package/dist/server/handler.d.ts

@@ -0,0 +1 @@
+export * from './handler/index.ts';