@lostgradient/weft 0.6.0 → 0.7.0

package/dist/server/asyncapi-channels.js

@@ -82,10 +82,59 @@ export function buildWebSocketMessages(operation, definitionSchemaToJsonSchema)
   };
 }
 export function buildSseMessages(operation, definitionSchemaToJsonSchema) {
-  const names = sseMessageNames(operation), logicalEventSchema = eventJsonSchema(operation, definitionSchemaToJsonSchema);
+  const logicalEventSchema = eventJsonSchema(operation, definitionSchemaToJsonSchema);
+  if (!isTokenSseOperation(operation)) {
+    const eventNames = eventSseMessageNames(operation);
+    return {
+      [eventNames.eventEnvelopeEvent]: {
+        name: eventNames.eventEnvelopeEvent,
+        contentType: "text/event-stream",
+        payload: logicalEventSchema,
+        summary: `SSE event envelope for ${operation.name}.`,
+        bindings: {
+          http: {
+            event: "<envelope.kind>"
+          }
+        },
+        "x-weft-sse-frame": "id: <cursor>\\nevent: <envelope.kind>\\ndata: <JSON event envelope>\\n\\n"
+      },
+      [eventNames.pingEvent]: {
+        name: eventNames.pingEvent,
+        contentType: "text/event-stream",
+        payload: {
+          additionalProperties: !1,
+          properties: {
+            emittedAtMs: { type: "number" }
+          },
+          required: ["emittedAtMs"],
+          type: "object"
+        },
+        summary: `SSE ping keepalive for ${operation.name}.`,
+        bindings: {
+          http: {
+            event: "ping"
+          }
+        },
+        "x-weft-sse-frame": 'event: ping\\ndata: {"emittedAtMs":<timestamp>}\\n\\n'
+      },
+      [eventNames.errorEvent]: {
+        name: eventNames.errorEvent,
+        contentType: "text/event-stream",
+        payload: sseErrorPayloadSchema(),
+        summary: `SSE error event for ${operation.name}.`,
+        bindings: {
+          http: {
+            event: "error"
+          }
+        },
+        "x-weft-sse-frame": "event: error\\ndata: <JSON Error>\\n\\n"
+      }
+    };
+  }
+  const tokenNames = tokenSseMessageNames(operation);
   return {
-    [names.tokenEvent]: {
-      name: names.tokenEvent,
+    [tokenNames.tokenEvent]: {
+      name: tokenNames.tokenEvent,
       contentType: "text/event-stream",
       payload: { type: "string" },
       summary: `SSE token event for ${operation.name}. The data: line carries the token text.`,
@@ -97,8 +146,8 @@ export function buildSseMessages(operation, definitionSchemaToJsonSchema) {
       "x-weft-sse-frame": "event: token\\nid: <sequence>\\ndata: <token-text>\\n\\n",
       "x-weft-event-schema": logicalEventSchema
     },
-    [names.doneEvent]: {
-      name: names.doneEvent,
+    [tokenNames.doneEvent]: {
+      name: tokenNames.doneEvent,
       contentType: "text/event-stream",
       payload: {
         additionalProperties: !1,
@@ -113,18 +162,10 @@ export function buildSseMessages(operation, definitionSchemaToJsonSchema) {
       },
       "x-weft-sse-frame": "event: done\\n\\n"
     },
-    [names.errorEvent]: {
-      name: names.errorEvent,
+    [tokenNames.errorEvent]: {
+      name: tokenNames.errorEvent,
       contentType: "text/event-stream",
-      payload: {
-        properties: {
-          code: { type: "string" },
-          data: {},
-          message: { type: "string" }
-        },
-        required: ["message"],
-        type: "object"
-      },
+      payload: sseErrorPayloadSchema(),
       summary: `SSE error event for ${operation.name}.`,
       bindings: {
         http: {
@@ -164,6 +205,17 @@ function webSocketMessageNames(operation) {
   };
 }
 function sseMessageNames(operation) {
+  return isTokenSseOperation(operation) ? tokenSseMessageNames(operation) : eventSseMessageNames(operation);
+}
+function eventSseMessageNames(operation) {
+  const prefix = operationPrefix(operation);
+  return {
+    eventEnvelopeEvent: `${prefix}_eventEnvelopeEvent`,
+    pingEvent: `${prefix}_pingEvent`,
+    errorEvent: `${prefix}_errorEvent`
+  };
+}
+function tokenSseMessageNames(operation) {
   const prefix = operationPrefix(operation);
   return {
     tokenEvent: `${prefix}_tokenEvent`,
@@ -171,6 +223,20 @@ function sseMessageNames(operation) {
     errorEvent: `${prefix}_errorEvent`
   };
 }
+function isTokenSseOperation(operation) {
+  return operation.name === "weft.workflows.streams.sse";
+}
+function sseErrorPayloadSchema() {
+  return {
+    properties: {
+      code: { type: "string" },
+      data: {},
+      message: { type: "string" }
+    },
+    required: ["message"],
+    type: "object"
+  };
+}
 function messageReferenceMap(names) {
   const references = {};
   for (const [key, name] of Object.entries(names).toSorted(([left], [right]) => compareStrings(left, right)))

package/dist/server/handler/auth-context-principal.d.ts

@@ -0,0 +1,19 @@
+import type { AuthContext } from '../authentication.ts';
+import { type Principal } from '../principal.ts';
+/**
+ * Convert the REST transport's `authContext` into a `Principal`. The
+ * authenticator (`serve()`) reports method + optional claims; this maps
+ * that transport authentication result into the `Principal` used by the
+ * operation pipeline.
+ * 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: AuthContext | undefined): Principal;

package/dist/server/handler/auth-context-principal.js

@@ -0,0 +1,25 @@
+import {
+  anonymousPrincipal,
+  principalFromApiKey,
+  principalFromJwtClaims,
+  principalFromMutualTls
+} from "../principal.js";
+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();
+  }
+}

package/dist/server/handler/index.d.ts

@@ -11,7 +11,8 @@
  */
 import type { Engine } from '../../core/engine.ts';
 import { type HandlerOptions } from './route-dispatch.ts';
-export { authContextToPrincipal, isOperationFaultLike, type HandlerOptions, } from './route-dispatch.ts';
+export { authContextToPrincipal } from './auth-context-principal.ts';
+export { isOperationFaultLike, type HandlerOptions } from './route-dispatch.ts';
 export { extractRouteParameters, getRequiredRouteParameter } from './route-matching.ts';
 /**
  * Pure HTTP request handler. Maps Request to Response.

package/dist/server/handler/index.js

@@ -1,31 +1,23 @@
 import { MalformedRouteParameterError } from "../rest-binding.js";
+import { authContextToPrincipal } from "./auth-context-principal.js";
 import { matchRestBinding } from "./binding-dispatch.js";
 import { errorResponse } from "./response-helpers.js";
 import {
-  authContextToPrincipal,
   defaultOperationRegistry,
   defaultRestBindings,
   DIRECT_ROUTE_EXECUTORS,
   dispatchViaExecuteOperation
 } from "./route-dispatch.js";
 import { matchDirectRoute } from "./route-matching.js";
-export {
-  authContextToPrincipal,
-  isOperationFaultLike
-} from "./route-dispatch.js";
+export { authContextToPrincipal } from "./auth-context-principal.js";
+export { isOperationFaultLike } from "./route-dispatch.js";
 export { extractRouteParameters, getRequiredRouteParameter } from "./route-matching.js";
-function routeParameterErrorResponse(error) {
-  if (error instanceof MalformedRouteParameterError)
-    return errorResponse(error.message, 400);
-  return null;
-}
 function matchRouteBoundary(matcher) {
   try {
     return { kind: "matched", value: matcher() };
   } catch (error) {
-    const response = routeParameterErrorResponse(error);
-    if (response !== null)
-      return { kind: "malformed", response };
+    if (error instanceof MalformedRouteParameterError)
+      return { kind: "malformed", response: errorResponse(error.message, 400) };
     throw error;
   }
 }
@@ -34,10 +26,20 @@ function validateHandlerOptions(options) {
     return null;
   return errorResponse("`restBindings` and `operationRegistry` must be supplied together (or both omitted).", 500);
 }
+function liveEventStreamContextFromOptions(options) {
+  const context = {};
+  if (options?.workflowEventFeed !== void 0)
+    context.workflowEventFeed = options.workflowEventFeed;
+  if (options?.fleetEventFeed !== void 0)
+    context.fleetEventFeed = options.fleetEventFeed;
+  if (options?.acquireWorkflowStreamConnection !== void 0)
+    context.acquireWorkflowStreamConnection = options.acquireWorkflowStreamConnection;
+  return context;
+}
 async function dispatchRestBinding(request, engine, bindingMatch, operationRegistry, options, url) {
   try {
     const principal = authContextToPrincipal(options?.authContext);
-    return await dispatchViaExecuteOperation(request, engine, bindingMatch.binding, bindingMatch.pathParams, operationRegistry, principal, options?.pipelineTrace, options?.maxRequestBodyBytes);
+    return await dispatchViaExecuteOperation(request, engine, bindingMatch.binding, bindingMatch.pathParams, operationRegistry, principal, options?.pipelineTrace, options?.maxRequestBodyBytes, options?.supportedAuthenticationSchemes, liveEventStreamContextFromOptions(options));
   } catch (error) {
     console.error("Unhandled error in dispatchViaExecuteOperation", {
       method: request.method,
@@ -60,10 +62,7 @@ async function dispatchDirectRoute(request, engine, route, options, url) {
     return errorResponse("Internal server error", 500);
   }
 }
-export async function handleRequest(request, engine, options) {
-  const url = new URL(request.url), optionError = validateHandlerOptions(options);
-  if (optionError !== null)
-    return optionError;
+async function dispatchMatchedRoute(request, engine, options, url) {
   const directRouteLookup = matchRouteBoundary(() => matchDirectRoute(request.method, url.pathname));
   if (directRouteLookup.kind === "malformed")
     return directRouteLookup.response;
@@ -76,3 +75,21 @@ export async function handleRequest(request, engine, options) {
     return dispatchRestBinding(request, engine, bindingLookup.value, operationRegistry, options, url);
   return errorResponse(`Not found: ${request.method} ${url.pathname}`, 404);
 }
+async function dispatchMatchedRouteBoundary(request, engine, options, url) {
+  try {
+    return await dispatchMatchedRoute(request, engine, options, url);
+  } catch (error) {
+    console.error("Unhandled error in handleRequest route matching", {
+      method: request.method,
+      path: url.pathname,
+      error
+    });
+    return errorResponse("Internal server error", 500);
+  }
+}
+export async function handleRequest(request, engine, options) {
+  const url = new URL(request.url), optionError = validateHandlerOptions(options);
+  if (optionError !== null)
+    return optionError;
+  return dispatchMatchedRouteBoundary(request, engine, options, url);
+}

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

@@ -2,14 +2,16 @@ 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 { FleetEventFeed } from '../fleet-event-feed.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 { WorkflowStreamConnectionAcquirer } from '../operations/workflow-events-sse.ts';
+import type { Principal } from '../principal.ts';
 import { type UnknownRestBinding } from '../rest-bindings.ts';
+import type { WorkflowEventFeed } from '../workflow-event-feed.ts';
 import type { DirectRouteHandlerName } from './route-matching.ts';
-/** Alias for `AuthContext` — kept local so handler-internal code reads naturally. */
-type AuthenticatedRequestContext = AuthContext;
+import { type LiveEventStreamContext } from './sse-route-dispatch.ts';
 /**
  * Options bag passed to `handleRequest` by the HTTP server wrapper.
  *
@@ -83,6 +85,12 @@ export interface HandlerOptions {
     trustedHosts?: ReadonlyArray<string>;
     /** Maximum REST operation request body size in bytes. Defaults to 1 MB. */
     maxRequestBodyBytes?: number;
+    /** Event feed used by live workflow SSE routes. */
+    workflowEventFeed?: WorkflowEventFeed;
+    /** Fleet feed used by live fleet SSE routes. */
+    fleetEventFeed?: Pick<FleetEventFeed, 'subscribe'>;
+    /** Shared per-workflow long-lived stream connection limiter. */
+    acquireWorkflowStreamConnection?: WorkflowStreamConnectionAcquirer;
     /**
      * Optional pipeline-trace observer. **Internal test seam** used by the
      * dispatch-audit suite to prove every transport drives the full
@@ -100,7 +108,7 @@ export type RouteExecutionContext = {
 };
 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, maxRequestBodyBytes?: number): Promise<Response>;
+export declare function dispatchViaExecuteOperation(request: Request, engine: Engine, binding: UnknownRestBinding, pathParams: Record<string, string>, registry: OperationRegistry, principal: Principal, pipelineTrace?: PipelineTrace, maxRequestBodyBytes?: number, supportedAuthenticationSchemes?: ReadonlySet<OpenApiSecuritySchemeName>, liveEventStreamContext?: LiveEventStreamContext): Promise<Response>;
 /**
  * Type guard that returns true if the value structurally resembles an
  * {@link OperationFault} (carries `code`, `message`, and `data` properties).
@@ -125,23 +133,5 @@ export declare function dispatchViaExecuteOperation(request: Request, engine: En
  * ```
  */
 export declare function isOperationFaultLike(value: unknown): value is OperationFault;
-/**
- * Convert the REST transport's `authContext` into a `Principal`. The
- * authenticator (`serve()`) reports method + optional claims; this maps
- * that transport authentication result into the `Principal` used by the
- * operation pipeline.
- * 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

@@ -12,12 +12,6 @@ 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
@@ -28,6 +22,10 @@ import {
   jsonResponse,
   negotiatedResponse
 } from "./response-helpers.js";
+import {
+  dispatchServerSentEventsBinding,
+  isDirectServerSentEventsOperation
+} from "./sse-route-dispatch.js";
 const defaultPrometheusExporter = createMetricsCollectorExporter(void 0);
 function resolveDiscoveryOrigin(options) {
   const { absoluteUrlDescription, path, request, serverOptions } = options;
@@ -113,17 +111,22 @@ export const DIRECT_ROUTE_EXECUTORS = {
     ...options?.discoveryInfo !== void 0 ? { discoveryInfo: options.discoveryInfo } : {}
   }))
 };
-export async function dispatchViaExecuteOperation(request, engine, binding, pathParams, registry, principal, pipelineTrace, maxRequestBodyBytes) {
-  let input;
-  try {
-    input = await binding.extractInput(request, pathParams, maxRequestBodyBytes !== void 0 ? { maxBodyBytes: maxRequestBodyBytes } : {});
-  } 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, {
+export async function dispatchViaExecuteOperation(request, engine, binding, pathParams, registry, principal, pipelineTrace, maxRequestBodyBytes, supportedAuthenticationSchemes, liveEventStreamContext) {
+  const extracted = await extractRestBindingInput(request, binding, pathParams, maxRequestBodyBytes);
+  if (!extracted.ok)
+    return extracted.response;
+  if (isDirectServerSentEventsOperation(binding.operationName))
+    return dispatchServerSentEventsBinding({
+      request,
+      binding,
+      rawInput: extracted.input,
+      principal,
+      registry,
+      ...pipelineTrace === void 0 ? {} : { pipelineTrace },
+      ...supportedAuthenticationSchemes === void 0 ? {} : { supportedAuthenticationSchemes },
+      ...liveEventStreamContext === void 0 ? {} : { liveEventStreamContext }
+    });
+  const result = await executeOperation(binding.operationName, extracted.input, {
     principal,
     engine,
     transport: "http-rest",
@@ -134,6 +137,16 @@ export async function dispatchViaExecuteOperation(request, engine, binding, path
     return binding.shapeSuccess ? binding.shapeSuccess(result.value, request) : defaultShapeSuccess(result.value, binding.success);
   return binding.shapeFault ? binding.shapeFault(result.fault) : faultToHttpResponse(result.fault);
 }
+async function extractRestBindingInput(request, binding, pathParams, maxRequestBodyBytes) {
+  try {
+    return { ok: !0, input: await binding.extractInput(request, pathParams, maxRequestBodyBytes !== void 0 ? { maxBodyBytes: maxRequestBodyBytes } : {}) };
+  } catch (error) {
+    if (isOperationFaultLike(error))
+      return { ok: !1, response: binding.shapeFault ? binding.shapeFault(error) : faultToHttpResponse(error) };
+    const message = error instanceof Error ? error.message : String(error);
+    return { ok: !1, response: errorResponse(message, 400) };
+  }
+}
 function hasRequiredFaultProperties(candidate) {
   return Object.hasOwn(candidate, "code") && Object.hasOwn(candidate, "message") && Object.hasOwn(candidate, "data");
 }
@@ -159,25 +172,6 @@ export function isOperationFaultLike(value) {
     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)

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

@@ -0,0 +1,25 @@
+import type { FleetEventFeed } from '../fleet-event-feed.ts';
+import type { OpenApiSecuritySchemeName } from '../openapi.ts';
+import { type OperationRegistry, type PipelineTrace } from '../operation-catalog.ts';
+import { type WorkflowStreamConnectionAcquirer } from '../operations/workflow-events-sse.ts';
+import { type Principal } from '../principal.ts';
+import type { UnknownRestBinding } from '../rest-bindings.ts';
+import type { WorkflowEventFeed } from '../workflow-event-feed.ts';
+export type LiveEventStreamContext = {
+    workflowEventFeed?: WorkflowEventFeed;
+    fleetEventFeed?: Pick<FleetEventFeed, 'subscribe'>;
+    acquireWorkflowStreamConnection?: WorkflowStreamConnectionAcquirer;
+};
+type DispatchServerSentEventsBindingOptions = {
+    readonly request: Request;
+    readonly binding: UnknownRestBinding;
+    readonly rawInput: unknown;
+    readonly principal: Principal;
+    readonly registry: OperationRegistry;
+    readonly pipelineTrace?: PipelineTrace;
+    readonly supportedAuthenticationSchemes?: ReadonlySet<OpenApiSecuritySchemeName>;
+    readonly liveEventStreamContext?: LiveEventStreamContext;
+};
+export declare function isDirectServerSentEventsOperation(operationName: string): boolean;
+export declare function dispatchServerSentEventsBinding(options: DispatchServerSentEventsBindingOptions): Promise<Response>;
+export {};

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

@@ -0,0 +1,45 @@
+import { faultToHttpResponse } from "../fault-to-http.js";
+import {
+  executeOperation
+} from "../operation-catalog.js";
+import { fleetEventsSseOperation } from "../operations/fleet-events-sse.js";
+import {
+  workflowEventsSseOperation
+} from "../operations/workflow-events-sse.js";
+import { isAuthenticated, principalFromStdioLocal } from "../principal.js";
+export function isDirectServerSentEventsOperation(operationName) {
+  return operationName === workflowEventsSseOperation.name || operationName === fleetEventsSseOperation.name;
+}
+export async function dispatchServerSentEventsBinding(options) {
+  const { binding, registry } = options, missingOperationResponse = shapeMissingOperation(binding, registry);
+  if (missingOperationResponse !== null)
+    return missingOperationResponse;
+  const shapeSuccess = binding.shapeSuccess;
+  if (shapeSuccess === void 0)
+    throw Error("SSE binding missing success shaper");
+  const result = await executeOperation(binding.operationName, options.rawInput, {
+    principal: principalForServerSentEvents(options),
+    engine: options.liveEventStreamContext ?? {},
+    transport: "http-rest",
+    registry,
+    ...options.pipelineTrace === void 0 ? {} : { pipelineTrace: options.pipelineTrace }
+  });
+  if (result.ok)
+    return shapeSuccess(result.value, options.request);
+  return binding.shapeFault ? binding.shapeFault(result.fault) : faultToHttpResponse(result.fault);
+}
+function shapeMissingOperation(binding, registry) {
+  if (registry.get(binding.operationName) !== void 0)
+    return null;
+  const fault = {
+    code: "MethodNotFound",
+    message: `unknown operation: ${binding.operationName}`,
+    data: { method: binding.operationName }
+  };
+  return binding.shapeFault ? binding.shapeFault(fault) : faultToHttpResponse(fault);
+}
+function principalForServerSentEvents(options) {
+  if (options.supportedAuthenticationSchemes?.size === 0 && !isAuthenticated(options.principal))
+    return principalFromStdioLocal();
+  return options.principal;
+}