@lostgradient/weft 0.5.0 → 0.7.0

package/dist/server/operations/workflow-events-sse.js

@@ -0,0 +1,200 @@
+import { z } from "zod";
+import { defineOperation } from "../operation-registry.js";
+import { isAuthenticated } from "../principal.js";
+import {
+  decodeCursor
+} from "../workflow-event-feed.js";
+import { invalidParamsFault, jsonErrorResponse } from "./operation-helpers.js";
+import {
+  createEventEnvelopeSSEStream,
+  readServerSentEventsCursor,
+  requireServerSentEventsAccept,
+  shapeServerSentEventsFault,
+  SSE_RESPONSE_HEADERS
+} from "./sse-stream.js";
+const INITIAL_CURSOR = "-1", MAX_WORKFLOW_SSE_REPLAY_EVENTS = 1000, MAXIMUM_WORKFLOW_STREAMS_MESSAGE = "maximum stream connections per workflow exceeded", cursorSchema = z.string().refine((cursor) => decodeCursor(cursor) !== null, {
+  message: "Invalid cursor"
+}), workflowEventsSseInputSchema = z.object({
+  workflowId: z.string().min(1),
+  selector: z.enum(["events", "tokens"]).default("events"),
+  fromCursor: cursorSchema.optional(),
+  lastEventId: cursorSchema.optional()
+}), workflowEventsSseOutputSchema = z.custom(isAsyncIterable, "Expected async iterable workflow event stream"), workflowEventEnvelopeSchema = z.object({
+  kind: z.string(),
+  workflowId: z.string(),
+  selector: z.enum(["events", "tokens"]),
+  sequence: z.number(),
+  cursor: z.string(),
+  emittedAtMs: z.number(),
+  payload: z.unknown()
+});
+export const workflowEventsSseOperation = defineOperation({
+  name: "weft.workflows.events.sse",
+  mcpExposable: !1,
+  kind: "stream",
+  summary: "Stream workflow events as Server-Sent Events",
+  description: '`selector: "events"` requires `events:read`; `selector: "tokens"` requires `streams:read`. The stream replays from `fromCursor` or `Last-Event-ID`, then remains open for live events and `ping` keepalives.',
+  destructive: !1,
+  tags: ["Events"],
+  inputSchema: workflowEventsSseInputSchema,
+  outputSchema: workflowEventsSseOutputSchema,
+  eventSchema: workflowEventEnvelopeSchema,
+  parameterizedAccess: {
+    discriminator: "selector",
+    defaultValue: "events",
+    variants: [
+      {
+        value: "events",
+        access: { kind: "scoped", scopes: { kind: "anyOf", scopes: ["events:read"] } }
+      },
+      {
+        value: "tokens",
+        access: { kind: "scoped", scopes: { kind: "anyOf", scopes: ["streams:read"] } }
+      }
+    ]
+  },
+  producibleFaults: ["InvalidParams", "UnsupportedTransport"],
+  access: { kind: "authenticated" },
+  authorize: async ({ input, principal }) => {
+    const requiredScope = workflowSseScope(input.selector);
+    if (!isAuthenticated(principal))
+      return { allowed: !1, classification: "unauthorized", reason: "authentication required" };
+    if (principal.hasScope(requiredScope))
+      return { allowed: !0 };
+    return {
+      allowed: !1,
+      classification: "forbidden",
+      reason: `requires scope: ${requiredScope}`
+    };
+  },
+  discoverable: !0,
+  transports: { http: !0, jsonRpcHttp: !1, jsonRpcWebSocket: !1, jsonRpcStdio: !1 },
+  unknownKeyPolicy: { http: "strip", jsonRpc: "reject" },
+  invoke: async ({ input, engine }) => {
+    return createWorkflowEventsIterable(input, eventStreamOperationContext(engine));
+  }
+});
+function workflowSseScope(selector) {
+  return selector === "tokens" ? "streams:read" : "events:read";
+}
+function eventStreamOperationContext(engine) {
+  if (typeof engine !== "object" || engine === null)
+    return {};
+  return engine;
+}
+function unsupportedEventStreamContextFault(message) {
+  return {
+    code: "UnsupportedTransport",
+    message,
+    data: { transport: "http-rest", supported: ["http-rest"] }
+  };
+}
+function maximumWorkflowStreamsFault() {
+  return invalidParamsFault(MAXIMUM_WORKFLOW_STREAMS_MESSAGE);
+}
+function isAsyncIterable(value) {
+  if (typeof value !== "object" || value === null)
+    return !1;
+  return typeof value[Symbol.asyncIterator] === "function";
+}
+function isClosableWorkflowEventsIterable(value) {
+  return "close" in value && typeof value.close === "function";
+}
+function isReplayAwareWorkflowEventsIterable(value) {
+  return isClosableWorkflowEventsIterable(value) && "replayComplete" in value && value.replayComplete instanceof Promise;
+}
+function createWorkflowEventsIterable(input, context) {
+  const feed = context.workflowEventFeed;
+  if (feed === void 0)
+    throw unsupportedEventStreamContextFault("workflow event SSE requires a workflow event feed");
+  const lease = context.acquireWorkflowStreamConnection?.(input.workflowId);
+  if (lease === null)
+    throw maximumWorkflowStreamsFault();
+  const controller = new AbortController, replayComplete = Promise.withResolvers();
+  let closed = !1;
+  const close = async () => {
+    if (closed)
+      return;
+    closed = !0;
+    controller.abort();
+    lease?.release();
+  }, fromCursor = input.lastEventId ?? input.fromCursor ?? INITIAL_CURSOR, subscribeOptions = {
+    workflowId: input.workflowId,
+    selector: input.selector,
+    fromCursor,
+    signal: controller.signal,
+    replayLimit: MAX_WORKFLOW_SSE_REPLAY_EVENTS,
+    onReplayComplete: () => replayComplete.resolve(),
+    createReplayLimitError: (count, limit) => invalidParamsFault(`Workflow event replay window is ${count} events; maximum is ${limit}. Supply a more recent fromCursor.`)
+  };
+  let source;
+  try {
+    source = feed.subscribe(subscribeOptions);
+  } catch (error) {
+    close();
+    throw error;
+  }
+  return {
+    async* [Symbol.asyncIterator]() {
+      try {
+        for await (const envelope of source)
+          yield envelope;
+      } finally {
+        await close();
+      }
+    },
+    replayComplete: replayComplete.promise,
+    close
+  };
+}
+function shapeWorkflowEventsSseSuccess(output, request) {
+  const close = isClosableWorkflowEventsIterable(output) ? () => output.close() : async () => {
+    return;
+  };
+  return new Response(createEventEnvelopeSSEStream({
+    iterable: output,
+    close,
+    ...isReplayAwareWorkflowEventsIterable(output) ? { ready: output.replayComplete } : {},
+    signal: request.signal
+  }), {
+    status: 200,
+    headers: SSE_RESPONSE_HEADERS
+  });
+}
+function shapeWorkflowEventsSseFault(fault) {
+  if (fault.code === "InvalidParams" && fault.message === MAXIMUM_WORKFLOW_STREAMS_MESSAGE)
+    return jsonErrorResponse(fault.message, 429);
+  return shapeServerSentEventsFault(fault);
+}
+function readSelector(request) {
+  const value = new URL(request.url).searchParams.get("selector");
+  if (value === null)
+    return;
+  return value;
+}
+export const workflowEventsSseRestBinding = {
+  method: "GET",
+  path: "/v1/workflows/:id/events/sse",
+  pathParamNames: ["id"],
+  operationName: "weft.workflows.events.sse",
+  transportKind: "sse",
+  inputSources: {
+    workflowId: { kind: "path", pathParam: "id" },
+    selector: { kind: "query", queryParam: "selector" },
+    fromCursor: { kind: "query", queryParam: "fromCursor" },
+    lastEventId: { kind: "header", headerName: "Last-Event-ID" }
+  },
+  extractInput: async (request, pathParams) => {
+    requireServerSentEventsAccept(request);
+    const url = new URL(request.url), lastEventId = readServerSentEventsCursor(request.headers.get("Last-Event-ID")), fromCursor = lastEventId === void 0 ? readServerSentEventsCursor(url.searchParams.get("fromCursor")) : void 0, selector = readSelector(request);
+    return {
+      workflowId: pathParams.id ?? "",
+      ...selector === void 0 ? {} : { selector },
+      ...fromCursor === void 0 ? {} : { fromCursor },
+      ...lastEventId === void 0 ? {} : { lastEventId }
+    };
+  },
+  success: { kind: "streaming", mediaType: "text/event-stream" },
+  shapeSuccess: shapeWorkflowEventsSseSuccess,
+  shapeFault: shapeWorkflowEventsSseFault
+};

package/dist/server/rest-bindings.js

@@ -45,6 +45,10 @@ import {
   createScheduleOperation,
   createScheduleRestBinding
 } from "./operations/create-schedule.js";
+import {
+  fleetEventsSseOperation,
+  fleetEventsSseRestBinding
+} from "./operations/fleet-events-sse.js";
 import { fleetEventsSubscriptionOperation } from "./operations/fleet-events-subscription.js";
 import { forkWorkflowOperation, forkWorkflowRestBinding } from "./operations/fork-workflow.js";
 import {
@@ -203,6 +207,10 @@ import {
   drainDeploymentOperation,
   drainWorkerOperation
 } from "./operations/worker-drain.js";
+import {
+  workflowEventsSseOperation,
+  workflowEventsSseRestBinding
+} from "./operations/workflow-events-sse.js";
 import { workflowEventsSubscriptionOperation } from "./operations/workflow-events-subscription.js";
 export const REST_BINDINGS = [
   startWorkflowRestBinding,
@@ -250,6 +258,8 @@ export const REST_BINDINGS = [
   resumeScheduleRestBinding,
   getStreamChunksRestBinding,
   streamWorkflowSseRestBinding,
+  workflowEventsSseRestBinding,
+  fleetEventsSseRestBinding,
   getTaskDiagnosticsRestBinding,
   clearTaskDeadLetterRestBinding,
   listSchedulesRestBinding,
@@ -376,6 +386,8 @@ export function createLiveOperationRegistry(options) {
     resumeScheduleOperation,
     getStreamChunksOperation,
     streamWorkflowSseOperation,
+    workflowEventsSseOperation,
+    fleetEventsSseOperation,
     workflowEventsSubscriptionOperation,
     fleetEventsSubscriptionOperation,
     buildTaskDiagnosticsOperationForRegistry(resolved),

package/dist/server/runtime/authentication-bridge.js

@@ -15,6 +15,7 @@ import { gateRequest } from "./request-gate.js";
 import { handleTaskPollRequest, handleTaskResultRequest } from "./task-polling.js";
 import { reassignOrExpireTask } from "./task-reconciliation.js";
 import {
+  acquireWorkflowStreamConnection,
   addStreamSocket,
   addWatchSocket,
   removeStreamSocket,
@@ -96,6 +97,9 @@ function buildHandlerOptions(context, options, authentication) {
     ...options.maxRequestBodyBytes !== void 0 ? { maxRequestBodyBytes: options.maxRequestBodyBytes } : {},
     operationRegistry: context.liveOperationRegistry,
     restBindings: context.liveRestBindings,
+    workflowEventFeed: context.workflowEventFeed,
+    fleetEventFeed: context.fleetEventFeed,
+    acquireWorkflowStreamConnection: (workflowId) => acquireWorkflowStreamConnection(context, workflowId),
     supportedAuthenticationSchemes: context.supportedAuthenticationSchemes
   };
 }

package/dist/server/runtime/cors.d.ts

@@ -63,7 +63,7 @@ export interface CorsOptions {
     readonly allowedOrigins?: ReadonlyArray<string> | ((origin: string) => boolean);
     /** Methods advertised in preflight responses. Defaults to the common verbs plus `OPTIONS`. */
     readonly allowedMethods?: ReadonlyArray<string>;
-    /** Request headers a client may send. Defaults to `Authorization, Content-Type`. */
+    /** Request headers a client may send. Defaults to `Authorization, Content-Type, Last-Event-ID, Cache-Control`. */
     readonly allowedHeaders?: ReadonlyArray<string>;
     /** Response headers exposed to client scripts via `Access-Control-Expose-Headers`. */
     readonly exposedHeaders?: ReadonlyArray<string>;

package/dist/server/runtime/cors.js

@@ -1,4 +1,9 @@
-const DEFAULT_ALLOWED_METHODS = ["GET", "POST", "PUT", "PATCH", "DELETE", "OPTIONS"], DEFAULT_ALLOWED_HEADERS = ["Authorization", "Content-Type"], DEFAULT_MAX_AGE_SECONDS = 600, WILDCARD_ORIGIN = "*";
+const DEFAULT_ALLOWED_METHODS = ["GET", "POST", "PUT", "PATCH", "DELETE", "OPTIONS"], DEFAULT_ALLOWED_HEADERS = [
+  "Authorization",
+  "Content-Type",
+  "Last-Event-ID",
+  "Cache-Control"
+], DEFAULT_MAX_AGE_SECONDS = 600, WILDCARD_ORIGIN = "*";
 export function canonicalizeOrigin(value) {
   const trimmed = value.trim();
   if (trimmed === "" || trimmed === "null")

package/dist/server/runtime/websocket-stream.d.ts

@@ -8,6 +8,9 @@ import type { ServerContext } from './context.ts';
  * workflow cannot consume unbounded server sockets.
  */
 export declare const DEFAULT_MAX_STREAM_CONNECTIONS_PER_WORKFLOW = 100;
+export type WorkflowStreamConnectionLease = {
+    release(): void;
+};
 export declare function sendStreamMessage(ws: ServerWebSocket<WebSocketData>, sequence: number, message: string): void;
 export declare function sendWatchMessage(ws: ServerWebSocket<WebSocketData>, sequence: number, message: string): void;
 export declare function getHighestStoredStreamSequence(engine: Engine, workflowId: string, key: string): Promise<number>;
@@ -17,6 +20,7 @@ export declare function addWatchSocket(context: ServerContext, workflowId: strin
 export declare function removeStreamSocket(context: ServerContext, ws: ServerWebSocket<WebSocketData>): void;
 export declare function removeWatchSocket(context: ServerContext, ws: ServerWebSocket<WebSocketData>): void;
 export declare function removeWorkflowStreamConnection(context: ServerContext, ws: ServerWebSocket<WebSocketData>): void;
+export declare function acquireWorkflowStreamConnection(context: ServerContext, workflowId: string): WorkflowStreamConnectionLease | null;
 export declare function flushPendingStreamMessages(_context: ServerContext, ws: ServerWebSocket<WebSocketData>): void;
 export declare function flushPendingWatchMessages(_context: ServerContext, ws: ServerWebSocket<WebSocketData>): void;
 export declare function publishTokenMessage(context: ServerContext, workflowId: string, sequence: number, message: string): void;

package/dist/server/runtime/websocket-stream.js

@@ -86,6 +86,24 @@ export function removeWorkflowStreamConnection(context, ws) {
   if (!workflowId || !ws.data.workflowStreamConnectionAccepted)
     return;
   ws.data.workflowStreamConnectionAccepted = !1;
+  releaseWorkflowStreamConnection(context, workflowId);
+}
+export function acquireWorkflowStreamConnection(context, workflowId) {
+  const currentCount = context.workflowStreamConnectionCounts.get(workflowId), maxConnections = context.maxStreamConnectionsPerWorkflow;
+  if ((currentCount ?? 0) >= maxConnections)
+    return null;
+  context.workflowStreamConnectionCounts.set(workflowId, (currentCount ?? 0) + 1);
+  let released = !1;
+  return {
+    release() {
+      if (released)
+        return;
+      released = !0;
+      releaseWorkflowStreamConnection(context, workflowId);
+    }
+  };
+}
+function releaseWorkflowStreamConnection(context, workflowId) {
   const currentCount = context.workflowStreamConnectionCounts.get(workflowId);
   if (currentCount === void 0 || currentCount <= 1) {
     context.workflowStreamConnectionCounts.delete(workflowId);
@@ -94,12 +112,11 @@ export function removeWorkflowStreamConnection(context, ws) {
   context.workflowStreamConnectionCounts.set(workflowId, currentCount - 1);
 }
 function addWorkflowStreamConnection(context, workflowId, ws) {
-  const currentCount = context.workflowStreamConnectionCounts.get(workflowId) ?? 0, maxConnections = context.maxStreamConnectionsPerWorkflow;
-  if (currentCount >= maxConnections) {
+  const maxConnections = context.maxStreamConnectionsPerWorkflow;
+  if (acquireWorkflowStreamConnection(context, workflowId) === null) {
     ws.close(STREAM_CONNECTION_POLICY_CLOSE_CODE, `maximum stream connections per workflow (${maxConnections}) exceeded`);
     return !1;
   }
-  context.workflowStreamConnectionCounts.set(workflowId, currentCount + 1);
   ws.data.workflowStreamConnectionAccepted = !0;
   return !0;
 }

package/dist/server/workflow-event-feed.d.ts

@@ -72,6 +72,7 @@ export type ReplayLiveSubscribeOptions<TEnvelope extends SequencedEventEnvelope>
     filterEnvelope?: (envelope: TEnvelope) => boolean;
     countReplayEnvelope?: (envelope: TEnvelope) => boolean;
     createReplayLimitError?: (count: number, limit: number) => unknown;
+    onReplayComplete?: () => void;
 };
 export declare class ReplayWindowExceededError extends Error {
     readonly count: number;

package/dist/server/workflow-event-feed.js

@@ -44,7 +44,7 @@ export function createReplayLiveFeed(backend, options) {
   }
   function subscribe(args) {
     const buffer = [];
-    let bufferOverflowed = !1, waker = null;
+    let bufferOverflowed = !1, waker = null, cleanedUp = !1;
     const signal = args?.signal, fromCursor = args?.fromCursor, requestedAfter = fromCursor !== void 0 ? decodeCursorOrThrow(fromCursor) : -1, unsubscribe = backend.subscribeLive((envelope) => {
       if (!shouldDeliverEnvelope(envelope, args))
         return;
@@ -57,14 +57,23 @@ export function createReplayLiveFeed(backend, options) {
         waker = null;
         fire();
       }
-    }), onAbort = () => {
+    }), wake = () => {
       if (waker) {
         const fire = waker;
         waker = null;
         fire();
       }
-    };
-    signal?.addEventListener("abort", onAbort);
+    }, cleanup = () => {
+      if (cleanedUp)
+        return;
+      cleanedUp = !0;
+      signal?.removeEventListener("abort", onAbort);
+      unsubscribe();
+      wake();
+    }, onAbort = () => cleanup();
+    signal?.addEventListener("abort", onAbort, { once: !0 });
+    if (signal?.aborted)
+      cleanup();
     async function* generator() {
       try {
         if (signal?.aborted)
@@ -73,12 +82,12 @@ export function createReplayLiveFeed(backend, options) {
         yield* replayUpTo(backend, requestedAfter, snapshot, signal, args);
         if (signal?.aborted)
           return;
+        args?.onReplayComplete?.();
         yield* drainLive(buffer, snapshot, signal, () => bufferOverflowed, (w) => {
           waker = w;
         });
       } finally {
-        signal?.removeEventListener("abort", onAbort);
-        unsubscribe();
+        cleanup();
       }
     }
     return generator();
@@ -119,6 +128,8 @@ export function createWorkflowEventFeed(backend, options) {
       subscribeOptions.countReplayEnvelope = args.countReplayEnvelope;
     if (args.createReplayLimitError !== void 0)
       subscribeOptions.createReplayLimitError = args.createReplayLimitError;
+    if (args.onReplayComplete !== void 0)
+      subscribeOptions.onReplayComplete = args.onReplayComplete;
     return createScopedFeed(args.workflowId, args.selector).subscribe(subscribeOptions);
   }
   return {