convex-effect-workflows 0.1.0

package/src/component/dashboard.ts

@@ -0,0 +1,743 @@
+import { v } from "convex/values";
+import { query, type QueryCtx } from "./_generated/server.js";
+import {
+  DEFAULT_EXECUTIONS_PAGE_SIZE,
+  DEFAULT_LOGS_PAGE_SIZE,
+  DEFAULT_SPANS_PAGE_SIZE,
+  DEFAULT_STEPS_PAGE_SIZE,
+  MAX_PAGE_SIZE,
+} from "../shared/constants.js";
+import {
+  vDeterminismSignature,
+  vExecutionStatus,
+  vLogLevel,
+  vLogSource,
+  vResultEnvelope,
+  vSortOrder,
+  vSpanKind,
+  vSpanStatus,
+  vStepKind,
+  vStepState,
+} from "../shared/validators.js";
+import type { ExecutionStatus, SortOrder } from "../shared/validators.js";
+
+const DEFAULT_SCAN_MULTIPLIER = 8;
+const MAX_SCAN_ROWS = 2000;
+
+const vExecutionDoc = v.object({
+  _id: v.id("executions"),
+  _creationTime: v.number(),
+  workflowName: v.string(),
+  executionId: v.string(),
+  status: vExecutionStatus,
+  generation: v.number(),
+  tenantId: v.optional(v.string()),
+  parentExecutionId: v.optional(v.string()),
+  payloadRef: v.optional(v.id("payloads")),
+  payloadPreview: v.optional(v.any()),
+  payloadSize: v.number(),
+  resultKind: v.optional(v.union(v.literal("success"), v.literal("failure"))),
+  resultRef: v.optional(v.id("payloads")),
+  resultPreview: v.optional(v.any()),
+  error: v.optional(v.string()),
+  traceId: v.string(),
+  runnerHandle: v.optional(v.string()),
+  startedAt: v.number(),
+  completedAt: v.optional(v.number()),
+  lastResumedAt: v.optional(v.number()),
+  lastSuspendedAt: v.optional(v.number()),
+});
+
+const vJournalStepDoc = v.object({
+  _id: v.id("journalSteps"),
+  _creationTime: v.number(),
+  executionId: v.string(),
+  stepNumber: v.number(),
+  kind: vStepKind,
+  name: v.string(),
+  signature: vDeterminismSignature,
+  state: vStepState,
+  attempt: v.optional(v.number()),
+  workId: v.optional(v.string()),
+  spanId: v.optional(v.string()),
+  inputRef: v.optional(v.id("payloads")),
+  inputPreview: v.optional(v.any()),
+  inputSize: v.number(),
+  runResult: v.optional(vResultEnvelope),
+  startedAt: v.number(),
+  completedAt: v.optional(v.number()),
+  resumeToken: v.optional(v.string()),
+});
+
+const vSpanDoc = v.object({
+  _id: v.id("spans"),
+  _creationTime: v.number(),
+  executionId: v.string(),
+  traceId: v.string(),
+  spanId: v.string(),
+  parentSpanId: v.optional(v.string()),
+  stepNumber: v.optional(v.number()),
+  name: v.string(),
+  kind: vSpanKind,
+  status: vSpanStatus,
+  startTime: v.number(),
+  endTime: v.optional(v.number()),
+  attempt: v.optional(v.number()),
+  attributes: v.optional(v.any()),
+  inputRef: v.optional(v.id("payloads")),
+  inputPreview: v.optional(v.any()),
+  inputSize: v.optional(v.number()),
+  outputRef: v.optional(v.id("payloads")),
+  outputPreview: v.optional(v.any()),
+  outputSize: v.optional(v.number()),
+  error: v.optional(v.string()),
+});
+
+const vLogDoc = v.object({
+  _id: v.id("logs"),
+  _creationTime: v.number(),
+  executionId: v.string(),
+  traceId: v.optional(v.string()),
+  spanId: v.optional(v.string()),
+  stepNumber: v.optional(v.number()),
+  level: vLogLevel,
+  message: v.string(),
+  data: v.optional(v.any()),
+  source: vLogSource,
+  timestamp: v.number(),
+});
+
+const vExecutionListResult = v.object({
+  page: v.array(vExecutionDoc),
+  cursor: v.union(
+    v.object({
+      startedAt: v.number(),
+      executionId: v.string(),
+    }),
+    v.null(),
+  ),
+  isDone: v.boolean(),
+});
+
+const vExecutionDetailsResult = v.union(
+  v.object({
+    execution: vExecutionDoc,
+    steps: v.array(vJournalStepDoc),
+    spans: v.array(vSpanDoc),
+    logs: v.array(vLogDoc),
+  }),
+  v.null(),
+);
+
+const vExecutionStepsResult = v.object({
+  page: v.array(vJournalStepDoc),
+  cursor: v.union(v.number(), v.null()),
+  isDone: v.boolean(),
+});
+
+const vExecutionSpansResult = v.object({
+  page: v.array(vSpanDoc),
+  cursor: v.union(
+    v.object({
+      startTime: v.number(),
+      spanId: v.id("spans"),
+    }),
+    v.null(),
+  ),
+  isDone: v.boolean(),
+});
+
+const vExecutionLogsResult = v.object({
+  page: v.array(vLogDoc),
+  cursor: v.union(
+    v.object({
+      timestamp: v.number(),
+      logId: v.id("logs"),
+    }),
+    v.null(),
+  ),
+  isDone: v.boolean(),
+});
+
+const vExecutionMetricsResult = v.object({
+  total: v.number(),
+  completed: v.number(),
+  failed: v.number(),
+  interrupted: v.number(),
+  active: v.number(),
+  successRate: v.number(),
+  avgDurationMs: v.number(),
+  p50DurationMs: v.number(),
+  p95DurationMs: v.number(),
+});
+
+function clampLimit(limit: number | undefined, fallback: number) {
+  return Math.max(1, Math.min(limit ?? fallback, MAX_PAGE_SIZE));
+}
+
+function scanLimitFor(limit: number, multiplier = DEFAULT_SCAN_MULTIPLIER) {
+  return Math.min(MAX_SCAN_ROWS, Math.max(limit + 1, limit * multiplier));
+}
+
+function idCmp(a: string, b: string) {
+  return a < b ? -1 : a > b ? 1 : 0;
+}
+
+function applyExecutionCursor(
+  row: { startedAt: number; executionId: string },
+  args: {
+    cursorStartedAt?: number;
+    cursorExecutionId?: string;
+    order: SortOrder;
+  },
+) {
+  if (args.cursorStartedAt === undefined) {
+    return true;
+  }
+
+  if (args.order === "asc") {
+    if (row.startedAt < args.cursorStartedAt) return false;
+    if (
+      row.startedAt === args.cursorStartedAt &&
+      args.cursorExecutionId &&
+      idCmp(row.executionId, args.cursorExecutionId) <= 0
+    ) {
+      return false;
+    }
+    return true;
+  }
+
+  if (row.startedAt > args.cursorStartedAt) return false;
+  if (
+    row.startedAt === args.cursorStartedAt &&
+    args.cursorExecutionId &&
+    idCmp(row.executionId, args.cursorExecutionId) >= 0
+  ) {
+    return false;
+  }
+  return true;
+}
+
+async function executionWindow(
+  ctx: QueryCtx,
+  args: {
+    workflowName?: string;
+    status?: ExecutionStatus;
+    tenantId?: string;
+    startedAfter?: number;
+    startedBefore?: number;
+    order: SortOrder;
+    scanLimit: number;
+  },
+) {
+  if (args.tenantId) {
+    if (args.startedAfter !== undefined && args.startedBefore !== undefined) {
+      return await ctx.db
+        .query("executions")
+        .withIndex("by_tenant_started", (q) =>
+          q
+            .eq("tenantId", args.tenantId!)
+            .gte("startedAt", args.startedAfter!)
+            .lte("startedAt", args.startedBefore!),
+        )
+        .order(args.order)
+        .take(args.scanLimit);
+    }
+    if (args.startedAfter !== undefined) {
+      return await ctx.db
+        .query("executions")
+        .withIndex("by_tenant_started", (q) =>
+          q.eq("tenantId", args.tenantId!).gte("startedAt", args.startedAfter!),
+        )
+        .order(args.order)
+        .take(args.scanLimit);
+    }
+    if (args.startedBefore !== undefined) {
+      return await ctx.db
+        .query("executions")
+        .withIndex("by_tenant_started", (q) =>
+          q.eq("tenantId", args.tenantId!).lte("startedAt", args.startedBefore!),
+        )
+        .order(args.order)
+        .take(args.scanLimit);
+    }
+    return await ctx.db
+      .query("executions")
+      .withIndex("by_tenant_started", (q) => q.eq("tenantId", args.tenantId!))
+      .order(args.order)
+      .take(args.scanLimit);
+  }
+
+  if (args.workflowName) {
+    if (args.startedAfter !== undefined && args.startedBefore !== undefined) {
+      return await ctx.db
+        .query("executions")
+        .withIndex("by_workflow_started", (q) =>
+          q
+            .eq("workflowName", args.workflowName!)
+            .gte("startedAt", args.startedAfter!)
+            .lte("startedAt", args.startedBefore!),
+        )
+        .order(args.order)
+        .take(args.scanLimit);
+    }
+    if (args.startedAfter !== undefined) {
+      return await ctx.db
+        .query("executions")
+        .withIndex("by_workflow_started", (q) =>
+          q.eq("workflowName", args.workflowName!).gte("startedAt", args.startedAfter!),
+        )
+        .order(args.order)
+        .take(args.scanLimit);
+    }
+    if (args.startedBefore !== undefined) {
+      return await ctx.db
+        .query("executions")
+        .withIndex("by_workflow_started", (q) =>
+          q.eq("workflowName", args.workflowName!).lte("startedAt", args.startedBefore!),
+        )
+        .order(args.order)
+        .take(args.scanLimit);
+    }
+    return await ctx.db
+      .query("executions")
+      .withIndex("by_workflow_started", (q) => q.eq("workflowName", args.workflowName!))
+      .order(args.order)
+      .take(args.scanLimit);
+  }
+
+  if (args.status) {
+    if (args.startedAfter !== undefined && args.startedBefore !== undefined) {
+      return await ctx.db
+        .query("executions")
+        .withIndex("by_status_started", (q) =>
+          q
+            .eq("status", args.status!)
+            .gte("startedAt", args.startedAfter!)
+            .lte("startedAt", args.startedBefore!),
+        )
+        .order(args.order)
+        .take(args.scanLimit);
+    }
+    if (args.startedAfter !== undefined) {
+      return await ctx.db
+        .query("executions")
+        .withIndex("by_status_started", (q) =>
+          q.eq("status", args.status!).gte("startedAt", args.startedAfter!),
+        )
+        .order(args.order)
+        .take(args.scanLimit);
+    }
+    if (args.startedBefore !== undefined) {
+      return await ctx.db
+        .query("executions")
+        .withIndex("by_status_started", (q) =>
+          q.eq("status", args.status!).lte("startedAt", args.startedBefore!),
+        )
+        .order(args.order)
+        .take(args.scanLimit);
+    }
+    return await ctx.db
+      .query("executions")
+      .withIndex("by_status_started", (q) => q.eq("status", args.status!))
+      .order(args.order)
+      .take(args.scanLimit);
+  }
+
+  if (args.startedAfter !== undefined && args.startedBefore !== undefined) {
+    return await ctx.db
+      .query("executions")
+      .withIndex("by_started", (q) =>
+        q.gte("startedAt", args.startedAfter!).lte("startedAt", args.startedBefore!),
+      )
+      .order(args.order)
+      .take(args.scanLimit);
+  }
+  if (args.startedAfter !== undefined) {
+    return await ctx.db
+      .query("executions")
+      .withIndex("by_started", (q) => q.gte("startedAt", args.startedAfter!))
+      .order(args.order)
+      .take(args.scanLimit);
+  }
+  if (args.startedBefore !== undefined) {
+    return await ctx.db
+      .query("executions")
+      .withIndex("by_started", (q) => q.lte("startedAt", args.startedBefore!))
+      .order(args.order)
+      .take(args.scanLimit);
+  }
+
+  return await ctx.db
+    .query("executions")
+    .withIndex("by_started")
+    .order(args.order)
+    .take(args.scanLimit);
+}
+
+export const listExecutions = query({
+  args: {
+    workflowName: v.optional(v.string()),
+    status: v.optional(vExecutionStatus),
+    tenantId: v.optional(v.string()),
+    startedAfter: v.optional(v.number()),
+    startedBefore: v.optional(v.number()),
+    limit: v.optional(v.number()),
+    cursorStartedAt: v.optional(v.number()),
+    cursorExecutionId: v.optional(v.string()),
+    order: v.optional(vSortOrder),
+  },
+  returns: vExecutionListResult,
+  handler: async (ctx, args) => {
+    const limit = clampLimit(args.limit, DEFAULT_EXECUTIONS_PAGE_SIZE);
+    const order = args.order ?? "desc";
+    const scanLimit = scanLimitFor(limit, 10);
+
+    const rows = await executionWindow(ctx, {
+      workflowName: args.workflowName,
+      status: args.status,
+      tenantId: args.tenantId,
+      startedAfter: args.startedAfter,
+      startedBefore: args.startedBefore,
+      order,
+      scanLimit,
+    });
+
+    const filtered = rows
+      .filter((row) => {
+        if (args.workflowName && row.workflowName !== args.workflowName) return false;
+        if (args.status && row.status !== args.status) return false;
+        if (args.tenantId && row.tenantId !== args.tenantId) return false;
+        return applyExecutionCursor(row, {
+          cursorStartedAt: args.cursorStartedAt,
+          cursorExecutionId: args.cursorExecutionId,
+          order,
+        });
+      })
+      .sort((a, b) => {
+        if (a.startedAt !== b.startedAt) {
+          return order === "asc" ? a.startedAt - b.startedAt : b.startedAt - a.startedAt;
+        }
+        return order === "asc"
+          ? idCmp(a.executionId, b.executionId)
+          : idCmp(b.executionId, a.executionId);
+      });
+
+    const page = filtered.slice(0, limit);
+    const scannedFullWindow = rows.length >= scanLimit;
+    const hasMore = filtered.length > limit || (page.length === limit && scannedFullWindow);
+    const next = hasMore ? page[page.length - 1] : undefined;
+
+    return {
+      page,
+      cursor: next
+        ? {
+            startedAt: next.startedAt,
+            executionId: next.executionId,
+          }
+        : null,
+      isDone: !hasMore,
+    };
+  },
+});
+
+export const getExecution = query({
+  args: {
+    executionId: v.string(),
+  },
+  returns: vExecutionDetailsResult,
+  handler: async (ctx, { executionId }) => {
+    const execution = await ctx.db
+      .query("executions")
+      .withIndex("by_execution_id", (q) => q.eq("executionId", executionId))
+      .unique();
+
+    if (!execution) {
+      return null;
+    }
+
+    const [steps, spans, logs] = await Promise.all([
+      ctx.db
+        .query("journalSteps")
+        .withIndex("by_execution_step", (q) => q.eq("executionId", executionId))
+        .collect(),
+      ctx.db
+        .query("spans")
+        .withIndex("by_execution_start", (q) => q.eq("executionId", executionId))
+        .collect(),
+      ctx.db
+        .query("logs")
+        .withIndex("by_execution_time", (q) => q.eq("executionId", executionId))
+        .order("desc")
+        .take(DEFAULT_LOGS_PAGE_SIZE),
+    ]);
+
+    steps.sort((a, b) => a.stepNumber - b.stepNumber);
+    spans.sort((a, b) => a.startTime - b.startTime);
+
+    return {
+      execution,
+      steps,
+      spans,
+      logs,
+    };
+  },
+});
+
+export const listExecutionSteps = query({
+  args: {
+    executionId: v.string(),
+    state: v.optional(vStepState),
+    limit: v.optional(v.number()),
+    afterStepNumber: v.optional(v.number()),
+  },
+  returns: vExecutionStepsResult,
+  handler: async (ctx, args) => {
+    const limit = clampLimit(args.limit, DEFAULT_STEPS_PAGE_SIZE);
+    const scanLimit = scanLimitFor(limit, 10);
+
+    const rows =
+      args.afterStepNumber !== undefined
+        ? await ctx.db
+            .query("journalSteps")
+            .withIndex("by_execution_step", (q) =>
+              q.eq("executionId", args.executionId).gt("stepNumber", args.afterStepNumber!),
+            )
+            .take(scanLimit)
+        : await ctx.db
+            .query("journalSteps")
+            .withIndex("by_execution_step", (q) => q.eq("executionId", args.executionId))
+            .take(scanLimit);
+
+    const filtered = rows.filter((row) => (args.state ? row.state === args.state : true));
+
+    const page = filtered.slice(0, limit);
+    const hasMore = filtered.length > limit || (page.length === limit && rows.length >= scanLimit);
+    const nextAfterStepNumber = hasMore ? page[page.length - 1]?.stepNumber : undefined;
+
+    return {
+      page,
+      cursor: nextAfterStepNumber ?? null,
+      isDone: !hasMore,
+    };
+  },
+});
+
+export const listExecutionSpans = query({
+  args: {
+    executionId: v.string(),
+    kind: v.optional(vSpanKind),
+    status: v.optional(vSpanStatus),
+    limit: v.optional(v.number()),
+    afterStartTime: v.optional(v.number()),
+    afterSpanId: v.optional(v.string()),
+  },
+  returns: vExecutionSpansResult,
+  handler: async (ctx, args) => {
+    const limit = clampLimit(args.limit, DEFAULT_SPANS_PAGE_SIZE);
+    const scanLimit = scanLimitFor(limit, 10);
+
+    const rows =
+      args.afterStartTime !== undefined
+        ? await ctx.db
+            .query("spans")
+            .withIndex("by_execution_start", (q) =>
+              q.eq("executionId", args.executionId).gte("startTime", args.afterStartTime!),
+            )
+            .take(scanLimit)
+        : await ctx.db
+            .query("spans")
+            .withIndex("by_execution_start", (q) => q.eq("executionId", args.executionId))
+            .take(scanLimit);
+
+    const filtered = rows
+      .filter((row) => {
+        if (args.kind && row.kind !== args.kind) return false;
+        if (args.status && row.status !== args.status) return false;
+        if (args.afterStartTime === undefined) return true;
+        if (row.startTime > args.afterStartTime) return true;
+        if (row.startTime < args.afterStartTime) return false;
+        if (!args.afterSpanId) return false;
+        return idCmp(row._id, args.afterSpanId) > 0;
+      })
+      .sort((a, b) => {
+        if (a.startTime !== b.startTime) return a.startTime - b.startTime;
+        return idCmp(a._id, b._id);
+      });
+
+    const page = filtered.slice(0, limit);
+    const hasMore = filtered.length > limit || (page.length === limit && rows.length >= scanLimit);
+    const next = hasMore ? page[page.length - 1] : undefined;
+
+    return {
+      page,
+      cursor: next
+        ? {
+            startTime: next.startTime,
+            spanId: next._id,
+          }
+        : null,
+      isDone: !hasMore,
+    };
+  },
+});
+
+export const listExecutionLogs = query({
+  args: {
+    executionId: v.string(),
+    level: v.optional(vLogLevel),
+    source: v.optional(vLogSource),
+    spanId: v.optional(v.string()),
+    limit: v.optional(v.number()),
+    afterTimestamp: v.optional(v.number()),
+    afterLogId: v.optional(v.string()),
+    order: v.optional(vSortOrder),
+  },
+  returns: vExecutionLogsResult,
+  handler: async (ctx, args) => {
+    const limit = clampLimit(args.limit, DEFAULT_LOGS_PAGE_SIZE);
+    const order = args.order ?? "desc";
+    const scanLimit = scanLimitFor(limit, 12);
+
+    const rows =
+      args.afterTimestamp === undefined
+        ? await ctx.db
+            .query("logs")
+            .withIndex("by_execution_time", (q) => q.eq("executionId", args.executionId))
+            .order(order)
+            .take(scanLimit)
+        : order === "asc"
+          ? await ctx.db
+              .query("logs")
+              .withIndex("by_execution_time", (q) =>
+                q.eq("executionId", args.executionId).gte("timestamp", args.afterTimestamp!),
+              )
+              .order(order)
+              .take(scanLimit)
+          : await ctx.db
+              .query("logs")
+              .withIndex("by_execution_time", (q) =>
+                q.eq("executionId", args.executionId).lte("timestamp", args.afterTimestamp!),
+              )
+              .order(order)
+              .take(scanLimit);
+
+    const filtered = rows
+      .filter((row) => {
+        if (args.level && row.level !== args.level) return false;
+        if (args.source && row.source !== args.source) return false;
+        if (args.spanId && row.spanId !== args.spanId) return false;
+
+        if (args.afterTimestamp === undefined) return true;
+        if (row.timestamp !== args.afterTimestamp) {
+          return order === "asc"
+            ? row.timestamp > args.afterTimestamp
+            : row.timestamp < args.afterTimestamp;
+        }
+        if (!args.afterLogId) {
+          return false;
+        }
+        return order === "asc"
+          ? idCmp(row._id, args.afterLogId) > 0
+          : idCmp(row._id, args.afterLogId) < 0;
+      })
+      .sort((a, b) => {
+        if (a.timestamp !== b.timestamp) {
+          return order === "asc" ? a.timestamp - b.timestamp : b.timestamp - a.timestamp;
+        }
+        return order === "asc" ? idCmp(a._id, b._id) : idCmp(b._id, a._id);
+      });
+
+    const page = filtered.slice(0, limit);
+    const hasMore = filtered.length > limit || (page.length === limit && rows.length >= scanLimit);
+    const next = hasMore ? page[page.length - 1] : undefined;
+
+    return {
+      page,
+      cursor: next
+        ? {
+            timestamp: next.timestamp,
+            logId: next._id,
+          }
+        : null,
+      isDone: !hasMore,
+    };
+  },
+});
+
+export const executionMetrics = query({
+  args: {
+    workflowName: v.optional(v.string()),
+    startedAfter: v.optional(v.number()),
+    startedBefore: v.optional(v.number()),
+  },
+  returns: vExecutionMetricsResult,
+  handler: async (ctx, args) => {
+    const rows =
+      args.startedAfter !== undefined && args.startedBefore !== undefined
+        ? await ctx.db
+            .query("executions")
+            .withIndex("by_started", (q) =>
+              q.gte("startedAt", args.startedAfter!).lte("startedAt", args.startedBefore!),
+            )
+            .collect()
+        : args.startedAfter !== undefined
+          ? await ctx.db
+              .query("executions")
+              .withIndex("by_started", (q) => q.gte("startedAt", args.startedAfter!))
+              .collect()
+          : args.startedBefore !== undefined
+            ? await ctx.db
+                .query("executions")
+                .withIndex("by_started", (q) => q.lte("startedAt", args.startedBefore!))
+                .collect()
+            : await ctx.db.query("executions").withIndex("by_started").collect();
+
+    const filtered = rows.filter((row) => {
+      if (args.workflowName && row.workflowName !== args.workflowName) return false;
+      return true;
+    });
+
+    let completed = 0;
+    let failed = 0;
+    let interrupted = 0;
+    let active = 0;
+    const durations: number[] = [];
+
+    for (const row of filtered) {
+      if (row.status === "completed") {
+        completed += 1;
+      } else if (row.status === "failed") {
+        failed += 1;
+      } else if (row.status === "interrupted") {
+        interrupted += 1;
+      } else if (row.status === "pending" || row.status === "running" || row.status === "suspended") {
+        active += 1;
+      }
+
+      if (row.completedAt !== undefined) {
+        durations.push(Math.max(0, row.completedAt - row.startedAt));
+      }
+    }
+
+    durations.sort((a, b) => a - b);
+    const avgDurationMs = durations.length
+      ? Math.round(durations.reduce((sum, v0) => sum + v0, 0) / durations.length)
+      : 0;
+
+    const p50DurationMs = durations.length ? durations[Math.floor(durations.length * 0.5)] : 0;
+    const p95DurationMs = durations.length ? durations[Math.floor(durations.length * 0.95)] : 0;
+
+    return {
+      total: filtered.length,
+      completed,
+      failed,
+      interrupted,
+      active,
+      successRate: filtered.length ? completed / filtered.length : 0,
+      avgDurationMs,
+      p50DurationMs,
+      p95DurationMs,
+    };
+  },
+});