convex-effect-workflows 0.1.0

package/src/component/spans.ts

@@ -0,0 +1,241 @@
+import { v } from "convex/values";
+import { mutation, query, type MutationCtx, type QueryCtx } from "./_generated/server.js";
+import { vSpanKind, vSpanStatus } from "../shared/validators.js";
+import { generateSpanId, nowTs } from "./utils.js";
+import { persistBoundedPayload } from "./payloads.js";
+import { MAX_SPAN_ATTR_BYTES } from "../shared/constants.js";
+
+type DbReaderCtx = Pick<QueryCtx, "db">;
+
+async function getSpan(
+  ctx: DbReaderCtx,
+  executionId: string,
+  spanId: string,
+) {
+  return await ctx.db
+    .query("spans")
+    .withIndex("by_execution_span", (q) =>
+      q.eq("executionId", executionId).eq("spanId", spanId),
+    )
+    .unique();
+}
+
+export const createSpan = mutation({
+  args: {
+    executionId: v.string(),
+    traceId: v.string(),
+    spanId: v.optional(v.string()),
+    parentSpanId: v.optional(v.string()),
+    stepNumber: v.optional(v.number()),
+    name: v.string(),
+    kind: vSpanKind,
+    attempt: v.optional(v.number()),
+    input: v.optional(v.any()),
+    attributes: v.optional(v.any()),
+  },
+  returns: v.object({ spanId: v.string(), created: v.boolean() }),
+  handler: async (ctx, args) => {
+    const spanId = args.spanId ?? generateSpanId();
+    const existing = await getSpan(ctx, args.executionId, spanId);
+    if (existing) {
+      return { spanId, created: false };
+    }
+
+    const inputPayload =
+      args.input === undefined
+        ? { size: 0, ref: undefined, preview: undefined }
+        : await persistBoundedPayload(ctx, "spanInput", args.input);
+
+    const attrPayload =
+      args.attributes === undefined
+        ? undefined
+        : await persistBoundedPayload(
+            ctx,
+            "logData",
+            args.attributes,
+            MAX_SPAN_ATTR_BYTES,
+          );
+
+    await ctx.db.insert("spans", {
+      executionId: args.executionId,
+      traceId: args.traceId,
+      spanId,
+      parentSpanId: args.parentSpanId,
+      stepNumber: args.stepNumber,
+      name: args.name,
+      kind: args.kind,
+      status: "started",
+      startTime: nowTs(),
+      attempt: args.attempt,
+      attributes: attrPayload?.preview,
+      inputRef: inputPayload.ref,
+      inputPreview: inputPayload.preview,
+      inputSize: inputPayload.size,
+    });
+
+    return { spanId, created: true };
+  },
+});
+
+export const endSpan = mutation({
+  args: {
+    executionId: v.string(),
+    spanId: v.string(),
+    output: v.optional(v.any()),
+    error: v.optional(v.string()),
+    attributes: v.optional(v.any()),
+  },
+  returns: v.object({ changed: v.boolean() }),
+  handler: async (ctx, args) => {
+    const span = await getSpan(ctx, args.executionId, args.spanId);
+    if (!span) {
+      throw new Error(`Span not found: ${args.executionId}/${args.spanId}`);
+    }
+    if (span.status === "ended") {
+      return { changed: false };
+    }
+
+    const outputPayload =
+      args.output === undefined
+        ? { size: undefined, ref: undefined, preview: undefined }
+        : await persistBoundedPayload(ctx, "spanOutput", args.output);
+
+    const attrPayload =
+      args.attributes === undefined
+        ? undefined
+        : await persistBoundedPayload(
+            ctx,
+            "logData",
+            args.attributes,
+            MAX_SPAN_ATTR_BYTES,
+          );
+
+    await ctx.db.patch(span._id, {
+      status: "ended",
+      endTime: nowTs(),
+      outputRef: outputPayload.ref,
+      outputPreview: outputPayload.preview,
+      outputSize: outputPayload.size,
+      attributes: attrPayload?.preview ?? span.attributes,
+      error: args.error,
+    });
+    return { changed: true };
+  },
+});
+
+export const getExecutionSpan = query({
+  args: {
+    executionId: v.string(),
+    spanId: v.string(),
+  },
+  returns: v.any(),
+  handler: async (ctx, args) => {
+    return await getSpan(ctx, args.executionId, args.spanId);
+  },
+});
+
+export const listExecutionSpans = query({
+  args: {
+    executionId: v.string(),
+    limit: v.number(),
+    afterStartTime: v.optional(v.number()),
+    kind: v.optional(vSpanKind),
+    status: v.optional(vSpanStatus),
+  },
+  returns: v.any(),
+  handler: async (ctx, args) => {
+    const limit = Math.max(1, Math.min(args.limit, 500));
+    let rows = await ctx.db
+      .query("spans")
+      .withIndex("by_execution_start", (q) => q.eq("executionId", args.executionId))
+      .take(limit + 200);
+
+    if (args.afterStartTime !== undefined) {
+      rows = rows.filter((row) => row.startTime > args.afterStartTime!);
+    }
+    if (args.kind) {
+      rows = rows.filter((row) => row.kind === args.kind);
+    }
+    if (args.status) {
+      rows = rows.filter((row) => row.status === args.status);
+    }
+
+    rows.sort((a, b) => a.startTime - b.startTime);
+    const page = rows.slice(0, limit);
+    const nextAfterStartTime =
+      rows.length > limit ? page[page.length - 1]?.startTime : undefined;
+
+    return { page, nextAfterStartTime };
+  },
+});
+
+/**
+ * Test helper for creating a span with full control over fields including status, startTime, and endTime.
+ */
+export const internalCreateSpan = mutation({
+  args: {
+    executionId: v.string(),
+    traceId: v.string(),
+    spanId: v.optional(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()),
+    input: v.optional(v.any()),
+    output: v.optional(v.any()),
+    error: v.optional(v.string()),
+    attributes: v.optional(v.any()),
+  },
+  returns: v.object({ spanId: v.string() }),
+  handler: async (ctx, args) => {
+    const spanId = args.spanId ?? generateSpanId();
+
+    const inputPayload =
+      args.input === undefined
+        ? { size: 0, ref: undefined, preview: undefined }
+        : await persistBoundedPayload(ctx, "spanInput", args.input);
+
+    const outputPayload =
+      args.output === undefined
+        ? { size: undefined, ref: undefined, preview: undefined }
+        : await persistBoundedPayload(ctx, "spanOutput", args.output);
+
+    const attrPayload =
+      args.attributes === undefined
+        ? undefined
+        : await persistBoundedPayload(
+            ctx,
+            "logData",
+            args.attributes,
+            MAX_SPAN_ATTR_BYTES,
+          );
+
+    await ctx.db.insert("spans", {
+      executionId: args.executionId,
+      traceId: args.traceId,
+      spanId,
+      parentSpanId: args.parentSpanId,
+      stepNumber: args.stepNumber,
+      name: args.name,
+      kind: args.kind,
+      status: args.status,
+      startTime: args.startTime,
+      endTime: args.endTime,
+      attempt: args.attempt,
+      attributes: attrPayload?.preview,
+      inputRef: inputPayload.ref,
+      inputPreview: inputPayload.preview,
+      inputSize: inputPayload.size,
+      outputRef: outputPayload.ref,
+      outputPreview: outputPayload.preview,
+      outputSize: outputPayload.size,
+      error: args.error,
+    });
+
+    return { spanId };
+  },
+});

package/src/component/utils.test.ts

@@ -0,0 +1,32 @@
+import { describe, expect, it } from "vitest";
+import {
+  generateSpanId,
+  generateTraceId,
+  toPreview,
+  valueSize,
+  shouldOffload,
+} from "./utils.js";
+
+describe("component utils", () => {
+  it("generates stable-length ids", () => {
+    expect(generateSpanId()).toHaveLength(16);
+    expect(generateTraceId()).toHaveLength(32);
+  });
+
+  it("calculates value size", () => {
+    expect(valueSize({ a: 1 })).toBeGreaterThan(0);
+    expect(valueSize(undefined)).toBeGreaterThanOrEqual(0);
+  });
+
+  it("truncates large previews deterministically", () => {
+    const value = { data: "x".repeat(10_000) };
+    const preview = toPreview(value, 64) as any;
+    expect(preview._truncated).toBe(true);
+    expect(typeof preview.preview).toBe("string");
+  });
+
+  it("identifies offload threshold", () => {
+    expect(shouldOffload("x".repeat(10), 1_000)).toBe(false);
+    expect(shouldOffload("x".repeat(5_000), 100)).toBe(true);
+  });
+});

package/src/component/utils.ts

@@ -0,0 +1,73 @@
+import { getConvexSize, type Value } from "convex/values";
+import {
+  MAX_INLINE_PAYLOAD_BYTES,
+  MAX_PREVIEW_STRING_BYTES,
+} from "../shared/constants.js";
+
+export function nowTs() {
+  return Date.now();
+}
+
+export function randomHex(size = 16): string {
+  const bytes = new Uint8Array(size);
+  crypto.getRandomValues(bytes);
+  return Array.from(bytes, (b) => b.toString(16).padStart(2, "0")).join("");
+}
+
+export function generateTraceId(): string {
+  return randomHex(16);
+}
+
+export function generateSpanId(): string {
+  return randomHex(8);
+}
+
+type TruncatedPreview = {
+  _truncated: true;
+  preview: string;
+  originalSize?: number;
+};
+
+export function valueSize(value: unknown): number {
+  try {
+    // Boundary note: getConvexSize validates Convex Value shape at runtime and
+    // throws for unsupported values, which we convert to size=0.
+    return getConvexSize((value ?? null) as Value);
+  } catch {
+    return 0;
+  }
+}
+
+export function toPreview(
+  value: unknown,
+  maxBytes = MAX_PREVIEW_STRING_BYTES,
+): Value | TruncatedPreview | undefined {
+  if (value === undefined) {
+    return undefined;
+  }
+
+  let json: string | undefined;
+  try {
+    json = JSON.stringify(value);
+  } catch {
+    return { _truncated: true, preview: "<non-serializable>" };
+  }
+
+  if (json === undefined) {
+    return { _truncated: true, preview: "<non-serializable>" };
+  }
+
+  if (json.length <= maxBytes) {
+    return value as Value;
+  }
+
+  return {
+    _truncated: true,
+    preview: json.slice(0, maxBytes),
+    originalSize: json.length,
+  };
+}
+
+export function shouldOffload(value: unknown, inlineLimit = MAX_INLINE_PAYLOAD_BYTES) {
+  return valueSize(value) > inlineLimit;
+}

package/src/shared/constants.test.ts

@@ -0,0 +1,14 @@
+import { describe, expect, it } from "vitest";
+import {
+  DEFAULT_EXECUTIONS_PAGE_SIZE,
+  MAX_INLINE_PAYLOAD_BYTES,
+  MAX_LOG_DATA_BYTES,
+  MAX_PAGE_SIZE,
+} from "./constants.js";
+
+describe("shared constants", () => {
+  it("enforces sane bounds", () => {
+    expect(MAX_INLINE_PAYLOAD_BYTES).toBeGreaterThan(MAX_LOG_DATA_BYTES);
+    expect(MAX_PAGE_SIZE).toBeGreaterThan(DEFAULT_EXECUTIONS_PAGE_SIZE);
+  });
+});

package/src/shared/constants.ts

@@ -0,0 +1,15 @@
+export const COMPONENT_NAME = "effectWorkflows";
+
+export const MAX_INLINE_PAYLOAD_BYTES = 256_000;
+export const MAX_PREVIEW_STRING_BYTES = 4_096;
+export const MAX_LOG_DATA_BYTES = 64_000;
+export const MAX_SPAN_ATTR_BYTES = 64_000;
+
+export const DEFAULT_EXECUTIONS_PAGE_SIZE = 50;
+export const DEFAULT_STEPS_PAGE_SIZE = 100;
+export const DEFAULT_SPANS_PAGE_SIZE = 200;
+export const DEFAULT_LOGS_PAGE_SIZE = 200;
+
+export const MAX_PAGE_SIZE = 500;
+
+export const DEFAULT_RETENTION_DAYS = 30;

package/src/shared/validators.ts

@@ -0,0 +1,98 @@
+import { v, type Infer } from "convex/values";
+
+export const vExecutionStatus = v.union(
+  v.literal("pending"),
+  v.literal("running"),
+  v.literal("suspended"),
+  v.literal("completed"),
+  v.literal("failed"),
+  v.literal("interrupted"),
+);
+export type ExecutionStatus = Infer<typeof vExecutionStatus>;
+
+export const vStepKind = v.union(
+  v.literal("activity"),
+  v.literal("deferred"),
+  v.literal("clock"),
+  v.literal("nestedWorkflow"),
+  v.literal("system"),
+);
+export type StepKind = Infer<typeof vStepKind>;
+
+export const vStepState = v.union(
+  v.literal("started"),
+  v.literal("suspended"),
+  v.literal("completed"),
+  v.literal("failed"),
+  v.literal("canceled"),
+);
+export type StepState = Infer<typeof vStepState>;
+
+// valuePreview intentionally remains v.any(): previews can be raw inline values
+// or truncated preview envelopes for arbitrary user payloads.
+export const vResultEnvelope = v.union(
+  v.object({
+    kind: v.literal("success"),
+    valueRef: v.optional(v.id("payloads")),
+    valuePreview: v.optional(v.any()),
+  }),
+  v.object({
+    kind: v.literal("failed"),
+    error: v.string(),
+    valueRef: v.optional(v.id("payloads")),
+    valuePreview: v.optional(v.any()),
+  }),
+  v.object({ kind: v.literal("canceled") }),
+);
+export type ResultEnvelope = Infer<typeof vResultEnvelope>;
+
+export const vDeterminismSignature = v.object({
+  kind: vStepKind,
+  opName: v.string(),
+  attempt: v.optional(v.number()),
+  scheduleMeta: v.optional(v.any()),
+  schemaVersion: v.optional(v.number()),
+});
+export type DeterminismSignature = Infer<typeof vDeterminismSignature>;
+
+export const vSpanKind = v.union(
+  v.literal("workflow"),
+  v.literal("activity"),
+  v.literal("deferred"),
+  v.literal("clock"),
+  v.literal("system"),
+);
+export type SpanKind = Infer<typeof vSpanKind>;
+
+export const vSpanStatus = v.union(v.literal("started"), v.literal("ended"));
+export type SpanStatus = Infer<typeof vSpanStatus>;
+
+export const vLogLevel = v.union(
+  v.literal("debug"),
+  v.literal("info"),
+  v.literal("warn"),
+  v.literal("error"),
+);
+export type LogLevel = Infer<typeof vLogLevel>;
+
+export const vLogSource = v.union(
+  v.literal("workflow"),
+  v.literal("activity"),
+  v.literal("engine"),
+  v.literal("system"),
+);
+export type LogSource = Infer<typeof vLogSource>;
+
+export const vSortOrder = v.union(v.literal("asc"), v.literal("desc"));
+export type SortOrder = Infer<typeof vSortOrder>;
+
+export const vPayloadKind = v.union(
+  v.literal("executionPayload"),
+  v.literal("stepInput"),
+  v.literal("stepOutput"),
+  v.literal("deferredExit"),
+  v.literal("spanInput"),
+  v.literal("spanOutput"),
+  v.literal("logData"),
+);
+export type PayloadKind = Infer<typeof vPayloadKind>;

package/src/test.d.ts

@@ -0,0 +1,8 @@
+// Type augmentation for Bun import.meta.glob
+declare global {
+  interface ImportMeta {
+    glob(pattern: string): Record<string, () => any>;
+  }
+}
+
+export {};

package/src/test.ts

@@ -0,0 +1,17 @@
+/// <reference types="vite/client" />
+import type { TestConvex } from "convex-test";
+import type { GenericSchema, SchemaDefinition } from "convex/server";
+import workpool from "@convex-dev/workpool/test";
+import schema from "./component/schema.js";
+
+const modules = import.meta.glob("./component/**/*.ts");
+
+export function register(
+  t: TestConvex<SchemaDefinition<GenericSchema, boolean>>,
+  name: string = "effectWorkflows",
+) {
+  t.registerComponent(name, schema, modules);
+  workpool.register(t);
+}
+
+export default { register, schema, modules };