@workflow/web-shared 4.1.0-beta.62 → 4.1.0-beta.64

package/src/lib/event-materialization.ts

@@ -0,0 +1,243 @@
+/**
+ * Event materialization helpers.
+ *
+ * These functions convert a flat list of workflow events into entity-like
+ * objects (steps, hooks, waits) by grouping events by correlationId and
+ * stitching together lifecycle events.
+ *
+ * This enables a "top-down" data fetching pattern where the client fetches
+ * all events for a run once, then materializes entities client-side instead
+ * of making separate API calls for each entity type.
+ */
+
+import type { Event, StepStatus } from '@workflow/world';
+
+// ---------------------------------------------------------------------------
+// Materialized entity types
+// ---------------------------------------------------------------------------
+
+export interface MaterializedStep {
+  stepId: string;
+  runId: string;
+  stepName: string;
+  status: StepStatus;
+  attempt: number;
+  createdAt: Date;
+  startedAt?: Date;
+  completedAt?: Date;
+  updatedAt: Date;
+  /** All events for this step, in insertion order */
+  events: Event[];
+}
+
+export interface MaterializedHook {
+  hookId: string;
+  runId: string;
+  token?: string;
+  createdAt: Date;
+  receivedCount: number;
+  lastReceivedAt?: Date;
+  disposedAt?: Date;
+  /** All events for this hook, in insertion order */
+  events: Event[];
+}
+
+export interface MaterializedWait {
+  waitId: string;
+  runId: string;
+  status: 'waiting' | 'completed';
+  createdAt: Date;
+  resumeAt?: Date;
+  completedAt?: Date;
+  /** All events for this wait, in insertion order */
+  events: Event[];
+}
+
+export interface MaterializedEntities {
+  steps: MaterializedStep[];
+  hooks: MaterializedHook[];
+  waits: MaterializedWait[];
+}
+
+// ---------------------------------------------------------------------------
+// Helper: group events by correlationId prefix
+// ---------------------------------------------------------------------------
+
+function groupByCorrelationId(
+  events: Event[],
+  prefixes: string[]
+): Map<string, Event[]> {
+  const groups = new Map<string, Event[]>();
+  for (const event of events) {
+    const cid = event.correlationId;
+    if (!cid) continue;
+    if (!prefixes.some((p) => cid.startsWith(p))) continue;
+    const existing = groups.get(cid);
+    if (existing) {
+      existing.push(event);
+    } else {
+      groups.set(cid, [event]);
+    }
+  }
+  return groups;
+}
+
+// ---------------------------------------------------------------------------
+// materializeSteps
+// ---------------------------------------------------------------------------
+
+/**
+ * Group step_* events by correlationId and build Step-like entities.
+ *
+ * Handles partial event lists gracefully: a step may only have a
+ * step_created event with no completion yet.
+ */
+export function materializeSteps(events: Event[]): MaterializedStep[] {
+  const groups = groupByCorrelationId(events, ['step_']);
+  const steps: MaterializedStep[] = [];
+
+  for (const [correlationId, stepEvents] of groups) {
+    const created = stepEvents.find((e) => e.eventType === 'step_created');
+    if (!created) continue;
+
+    let status: StepStatus = 'pending';
+    let attempt = 0;
+    let startedAt: Date | undefined;
+    let completedAt: Date | undefined;
+    let updatedAt = created.createdAt;
+
+    for (const e of stepEvents) {
+      switch (e.eventType) {
+        case 'step_started':
+          status = 'running';
+          attempt += 1;
+          if (!startedAt) startedAt = e.createdAt;
+          completedAt = undefined;
+          updatedAt = e.createdAt;
+          break;
+        case 'step_completed':
+          status = 'completed';
+          completedAt = e.createdAt;
+          updatedAt = e.createdAt;
+          break;
+        case 'step_failed':
+          status = 'failed';
+          completedAt = e.createdAt;
+          updatedAt = e.createdAt;
+          break;
+        case 'step_retrying':
+          status = 'pending';
+          completedAt = undefined;
+          updatedAt = e.createdAt;
+          break;
+      }
+    }
+
+    steps.push({
+      stepId: correlationId,
+      runId: created.runId,
+      stepName:
+        created.eventType === 'step_created'
+          ? (created.eventData?.stepName ?? correlationId)
+          : correlationId,
+      status,
+      attempt,
+      createdAt: created.createdAt,
+      startedAt,
+      completedAt,
+      updatedAt,
+      events: stepEvents,
+    });
+  }
+
+  return steps;
+}
+
+// ---------------------------------------------------------------------------
+// materializeHooks
+// ---------------------------------------------------------------------------
+
+/**
+ * Group hook_* events by correlationId and build Hook-like entities.
+ */
+export function materializeHooks(events: Event[]): MaterializedHook[] {
+  const groups = groupByCorrelationId(events, ['hook_']);
+  const hooks: MaterializedHook[] = [];
+
+  for (const [correlationId, hookEvents] of groups) {
+    const created = hookEvents.find((e) => e.eventType === 'hook_created');
+    if (!created) continue;
+
+    const receivedEvents = hookEvents.filter(
+      (e) => e.eventType === 'hook_received'
+    );
+    const disposed = hookEvents.find((e) => e.eventType === 'hook_disposed');
+    const lastReceived = receivedEvents.at(-1);
+
+    hooks.push({
+      hookId: correlationId,
+      runId: created.runId,
+      token:
+        created.eventType === 'hook_created'
+          ? created.eventData?.token
+          : undefined,
+      createdAt: created.createdAt,
+      receivedCount: receivedEvents.length,
+      lastReceivedAt: lastReceived?.createdAt,
+      disposedAt: disposed?.createdAt,
+      events: hookEvents,
+    });
+  }
+
+  return hooks;
+}
+
+// ---------------------------------------------------------------------------
+// materializeWaits
+// ---------------------------------------------------------------------------
+
+/**
+ * Group wait_* events by correlationId and build Wait-like entities.
+ */
+export function materializeWaits(events: Event[]): MaterializedWait[] {
+  const groups = groupByCorrelationId(events, ['wait_']);
+  const waits: MaterializedWait[] = [];
+
+  for (const [correlationId, waitEvents] of groups) {
+    const created = waitEvents.find((e) => e.eventType === 'wait_created');
+    if (!created) continue;
+
+    const completed = waitEvents.find((e) => e.eventType === 'wait_completed');
+
+    waits.push({
+      waitId: correlationId,
+      runId: created.runId,
+      status: completed ? 'completed' : 'waiting',
+      createdAt: created.createdAt,
+      resumeAt:
+        created.eventType === 'wait_created'
+          ? created.eventData?.resumeAt
+          : undefined,
+      completedAt: completed?.createdAt,
+      events: waitEvents,
+    });
+  }
+
+  return waits;
+}
+
+// ---------------------------------------------------------------------------
+// materializeAll
+// ---------------------------------------------------------------------------
+
+/**
+ * Convenience function that materializes all entity types from a flat
+ * event list.
+ */
+export function materializeAll(events: Event[]): MaterializedEntities {
+  return {
+    steps: materializeSteps(events),
+    hooks: materializeHooks(events),
+    waits: materializeWaits(events),
+  };
+}

package/src/lib/trace-builder.ts

@@ -0,0 +1,201 @@
+/**
+ * Builds a complete trace from a WorkflowRun and its Events.
+ *
+ * This module groups raw events by correlation ID and entity type,
+ * converts each group into an OpenTelemetry-style Span, and returns
+ * a fully-formed Trace ready for the trace viewer.
+ */
+
+import type { Event, WorkflowRun } from '@workflow/world';
+import type { Span } from '../components/trace-viewer/types';
+import {
+  hookToSpan,
+  runToSpan,
+  stepToSpan,
+  waitToSpan,
+  WORKFLOW_LIBRARY,
+} from '../components/workflow-traces/trace-span-construction';
+import { otelTimeToMs } from '../components/workflow-traces/trace-time-utils';
+
+// ---------------------------------------------------------------------------
+// Event type classifiers
+// ---------------------------------------------------------------------------
+
+export const isStepEvent = (eventType: string) => eventType.startsWith('step_');
+
+export const isTimerEvent = (eventType: string) =>
+  eventType === 'wait_created' || eventType === 'wait_completed';
+
+export const isHookLifecycleEvent = (eventType: string) =>
+  eventType === 'hook_received' ||
+  eventType === 'hook_created' ||
+  eventType === 'hook_disposed';
+
+// ---------------------------------------------------------------------------
+// Event grouping
+// ---------------------------------------------------------------------------
+
+export type GroupedEvents = {
+  eventsByStepId: Map<string, Event[]>;
+  runLevelEvents: Event[];
+  timerEvents: Map<string, Event[]>;
+  hookEvents: Map<string, Event[]>;
+};
+
+function pushEvent(
+  map: Map<string, Event[]>,
+  correlationId: string,
+  event: Event
+) {
+  const existing = map.get(correlationId);
+  if (existing) {
+    existing.push(event);
+    return;
+  }
+  map.set(correlationId, [event]);
+}
+
+export function groupEventsByCorrelation(events: Event[]): GroupedEvents {
+  const eventsByStepId = new Map<string, Event[]>();
+  const runLevelEvents: Event[] = [];
+  const timerEvents = new Map<string, Event[]>();
+  const hookEvents = new Map<string, Event[]>();
+
+  for (const event of events) {
+    const correlationId = event.correlationId;
+    if (!correlationId) {
+      runLevelEvents.push(event);
+      continue;
+    }
+
+    if (isTimerEvent(event.eventType)) {
+      pushEvent(timerEvents, correlationId, event);
+      continue;
+    }
+
+    if (isHookLifecycleEvent(event.eventType)) {
+      pushEvent(hookEvents, correlationId, event);
+      continue;
+    }
+
+    if (isStepEvent(event.eventType)) {
+      pushEvent(eventsByStepId, correlationId, event);
+      continue;
+    }
+
+    runLevelEvents.push(event);
+  }
+
+  return { eventsByStepId, runLevelEvents, timerEvents, hookEvents };
+}
+
+// ---------------------------------------------------------------------------
+// Trace construction
+// ---------------------------------------------------------------------------
+
+/**
+ * Computes the latest known event time from the events list.
+ * Active (in-progress) child spans are capped at this time instead of `now`,
+ * so they only extend as far as our data goes.
+ */
+function computeLatestKnownTime(events: Event[], run: WorkflowRun): Date {
+  let latest = new Date(run.createdAt).getTime();
+  for (const event of events) {
+    const t = new Date(event.createdAt).getTime();
+    if (t > latest) latest = t;
+  }
+  return new Date(latest);
+}
+
+function buildSpans(
+  run: WorkflowRun,
+  groupedEvents: GroupedEvents,
+  now: Date,
+  latestKnownTime: Date
+) {
+  // Active child spans cap at latestKnownTime so they don't extend into
+  // unknown territory. Even when the run is completed, we may not have loaded
+  // all events yet, so always use the latest event we've actually seen.
+  const childMaxEnd = latestKnownTime;
+
+  const stepSpans = Array.from(groupedEvents.eventsByStepId.values())
+    .map((events) => stepToSpan(events, childMaxEnd))
+    .filter((span): span is Span => span !== null);
+
+  const hookSpans = Array.from(groupedEvents.hookEvents.values())
+    .map((events) => hookToSpan(events, childMaxEnd))
+    .filter((span): span is Span => span !== null);
+
+  const waitSpans = Array.from(groupedEvents.timerEvents.values())
+    .map((events) => waitToSpan(events, childMaxEnd))
+    .filter((span): span is Span => span !== null);
+
+  return {
+    runSpan: runToSpan(run, groupedEvents.runLevelEvents, now),
+    spans: [...stepSpans, ...hookSpans, ...waitSpans],
+  };
+}
+
+function cascadeSpans(runSpan: Span, spans: Span[]) {
+  const sortedSpans = [
+    runSpan,
+    ...spans.slice().sort((a, b) => {
+      const aStart = otelTimeToMs(a.startTime);
+      const bStart = otelTimeToMs(b.startTime);
+      return aStart - bStart;
+    }),
+  ];
+
+  return sortedSpans.map((span, index) => {
+    const parentSpanId =
+      index === 0 ? undefined : String(sortedSpans[index - 1].spanId);
+    return {
+      ...span,
+      parentSpanId,
+    };
+  });
+}
+
+export interface TraceWithMeta {
+  traceId: string;
+  rootSpanId: string;
+  spans: Span[];
+  resources: { name: string; attributes: Record<string, string> }[];
+  /** Duration in ms from trace start to the latest known event. */
+  knownDurationMs: number;
+}
+
+export function buildTrace(
+  run: WorkflowRun,
+  events: Event[],
+  now: Date
+): TraceWithMeta {
+  const groupedEvents = groupEventsByCorrelation(events);
+  const latestKnownTime = computeLatestKnownTime(events, run);
+  const { runSpan, spans } = buildSpans(
+    run,
+    groupedEvents,
+    now,
+    latestKnownTime
+  );
+  const sortedCascadingSpans = cascadeSpans(runSpan, spans);
+
+  // Compute known duration relative to trace start
+  const traceStartMs = otelTimeToMs(runSpan.startTime);
+  const knownDurationMs = latestKnownTime.getTime() - traceStartMs;
+
+  return {
+    traceId: run.runId,
+    rootSpanId: run.runId,
+    spans: sortedCascadingSpans,
+    resources: [
+      {
+        name: 'workflow',
+        attributes: {
+          'service.name': WORKFLOW_LIBRARY.name,
+        },
+      },
+    ],
+    knownDurationMs: Math.max(0, knownDurationMs),
+  };
+}