@osolmaz/pi-workflows 0.7.0 → 0.8.0

package/src/job-progress/reporter.ts

@@ -0,0 +1,304 @@
+import {
+  estimateProgress,
+  type ProgressSample,
+  type ProgressTrackState,
+} from "../workflows/index.js";
+import {
+  JOB_PROGRESS_SCHEMA,
+  type JobProgressEstimate,
+  type JobProgressPublishResult,
+  type JobProgressReporterOptions,
+  type JobProgressSnapshot,
+  type JobProgressTrack,
+  type JobProgressUpdate,
+} from "./types.js";
+import { isTerminalJobProgressState, validateJobProgressSnapshot } from "./validation.js";
+
+const DEFAULT_MINIMUM_INTERVAL_MS = 30_000;
+const DEFAULT_PUBLISH_TIMEOUT_MS = 15_000;
+
+export type JobProgressReporter = {
+  report(update: JobProgressUpdate): Promise<JobProgressPublishResult>;
+  flush(): Promise<JobProgressPublishResult>;
+  snapshot(): JobProgressSnapshot;
+};
+
+export function createJobProgressReporter(
+  options: JobProgressReporterOptions,
+): JobProgressReporter {
+  const now = options.now ?? (() => new Date());
+  const minimumIntervalMs = nonNegativeInteger(
+    options.minimumIntervalMs ?? DEFAULT_MINIMUM_INTERVAL_MS,
+    "minimumIntervalMs",
+  );
+  const publishTimeoutMs = positiveInteger(
+    options.publishTimeoutMs ?? DEFAULT_PUBLISH_TIMEOUT_MS,
+    "publishTimeoutMs",
+  );
+  let current =
+    options.previousSnapshot === undefined
+      ? validateJobProgressSnapshot({
+          schema: JOB_PROGRESS_SCHEMA,
+          application: options.application,
+          component: options.component,
+          jobId: options.jobId,
+          sourceRevision: options.sourceRevision,
+          contractHash: options.contractHash,
+          sequence: 0,
+          state: options.initialState ?? "running",
+          phase: options.initialPhase ?? "starting",
+          startedAt: options.startedAt,
+          updatedAt: options.startedAt,
+          ...(options.deadlineAt === undefined ? {} : { deadlineAt: options.deadlineAt }),
+          tracks: options.initialTracks,
+        })
+      : validatePreviousSnapshot(options, options.previousSnapshot);
+  const resumed = options.previousSnapshot !== undefined;
+  let lastQueuedAtMs = resumed ? Date.parse(current.updatedAt) : Number.NEGATIVE_INFINITY;
+  let lastQueuedSequence = -1;
+  let lastPublishedSequence = resumed ? current.sequence : -1;
+  let queuedOperation: Promise<void> | undefined;
+  let tail: Promise<void> = Promise.resolve();
+
+  const enqueue = (snapshot: JobProgressSnapshot): Promise<void> => {
+    if (lastQueuedSequence === snapshot.sequence && queuedOperation !== undefined) {
+      return queuedOperation;
+    }
+    lastQueuedAtMs = Date.parse(snapshot.updatedAt);
+    lastQueuedSequence = snapshot.sequence;
+    const started = tail.then(() =>
+      startPublication(options.publish, cloneSnapshot(snapshot), publishTimeoutMs),
+    );
+    const operation = started.then(async (publication) => {
+      await publication.result;
+      lastPublishedSequence = Math.max(lastPublishedSequence, snapshot.sequence);
+    });
+    queuedOperation = operation;
+    tail = started.then((publication) => publication.settled).catch(() => undefined);
+    void operation
+      .finally(() => {
+        if (lastQueuedSequence === snapshot.sequence) {
+          lastQueuedSequence = -1;
+          queuedOperation = undefined;
+        }
+      })
+      .catch(() => undefined);
+    return operation;
+  };
+
+  return {
+    async report(update) {
+      if (isTerminalJobProgressState(current.state)) {
+        throw new Error("job progress cannot change after a terminal state");
+      }
+      if (current.sequence >= Number.MAX_SAFE_INTEGER) {
+        throw new Error("job progress sequence is exhausted");
+      }
+      const timestamp = now().toISOString();
+      const state = update.state ?? current.state;
+      const phase = update.phase ?? current.phase;
+      const finishedAt = isTerminalJobProgressState(state)
+        ? (update.finishedAt ?? timestamp)
+        : update.finishedAt;
+      const tracks = isTerminalJobProgressState(state)
+        ? terminalizeTracks(update.tracks ?? current.tracks, state)
+        : (update.tracks ?? current.tracks);
+      const next = validateJobProgressSnapshot({
+        ...current,
+        sequence: current.sequence + 1,
+        state,
+        phase,
+        updatedAt: timestamp,
+        tracks,
+        ...(update.cost === undefined ? {} : { cost: update.cost }),
+        ...(finishedAt === undefined ? {} : { finishedAt }),
+      });
+      assertMonotonicTracks(current, next);
+      const publishNow =
+        update.force === true ||
+        phase !== current.phase ||
+        isTerminalJobProgressState(state) ||
+        Date.parse(timestamp) - lastQueuedAtMs >= minimumIntervalMs;
+      current = next;
+      if (!publishNow) return { snapshot: cloneSnapshot(next), published: false };
+      await enqueue(next);
+      return { snapshot: cloneSnapshot(next), published: true };
+    },
+
+    async flush() {
+      const snapshot = current;
+      if (lastPublishedSequence >= snapshot.sequence) {
+        await tail;
+        return { snapshot: cloneSnapshot(snapshot), published: false };
+      }
+      await enqueue(snapshot);
+      return { snapshot: cloneSnapshot(snapshot), published: true };
+    },
+
+    snapshot() {
+      return cloneSnapshot(current);
+    },
+  };
+}
+
+export function estimateJobProgress(
+  snapshots: JobProgressSnapshot[],
+  now = new Date(),
+): JobProgressEstimate {
+  if (snapshots.length === 0)
+    throw new Error("job progress estimation requires at least one snapshot");
+  const validated = snapshots
+    .map(validateJobProgressSnapshot)
+    .sort((left, right) => left.sequence - right.sequence);
+  const latest = validated.at(-1) as JobProgressSnapshot;
+  for (const snapshot of validated) assertSameIdentity(latest, snapshot);
+  for (let index = 1; index < validated.length; index += 1) {
+    const previous = validated[index - 1] as JobProgressSnapshot;
+    const current = validated[index] as JobProgressSnapshot;
+    if (previous.sequence === current.sequence) {
+      throw new Error(`job progress sequence ${current.sequence} is duplicated`);
+    }
+    if (Date.parse(previous.updatedAt) > Date.parse(current.updatedAt)) {
+      throw new Error("job progress updatedAt must not decrease as sequence increases");
+    }
+  }
+  const keys = latest.tracks.map((track) => track.key);
+  const tracks: ProgressTrackState[] = keys.map((key) => {
+    const samples: ProgressSample[] = validated.flatMap((snapshot) => {
+      const track = snapshot.tracks.find((candidate) => candidate.key === key);
+      return track === undefined ? [] : [{ at: snapshot.updatedAt, data: track.data }];
+    });
+    return { key, samples, estimate: estimateProgress(key, samples, now) };
+  });
+  return {
+    snapshot: cloneSnapshot(latest),
+    tracks,
+    estimates: tracks.map((track) => track.estimate),
+  };
+}
+
+function terminalizeTracks(
+  tracks: JobProgressTrack[],
+  state: "completed" | "failed" | "cancelled",
+): JobProgressTrack[] {
+  return tracks.map((track) => ({
+    key: track.key,
+    data: {
+      ...track.data,
+      status:
+        track.data.status === "completed" ||
+        track.data.status === "failed" ||
+        track.data.status === "cancelled"
+          ? track.data.status
+          : state,
+    },
+  }));
+}
+
+function assertMonotonicTracks(previous: JobProgressSnapshot, next: JobProgressSnapshot): void {
+  if (previous.phase !== next.phase) return;
+  for (const track of next.tracks) {
+    const prior = previous.tracks.find((candidate) => candidate.key === track.key);
+    if (prior === undefined || resetsTrack(prior, track)) continue;
+    if (
+      prior.data.completed !== undefined &&
+      track.data.completed !== undefined &&
+      track.data.completed < prior.data.completed
+    ) {
+      throw new Error(`job progress track ${track.key} completed value must not decrease`);
+    }
+  }
+}
+
+function resetsTrack(previous: JobProgressTrack, next: JobProgressTrack): boolean {
+  return (
+    previous.data.phase !== next.data.phase ||
+    previous.data.unit !== next.data.unit ||
+    previous.data.total !== next.data.total
+  );
+}
+
+function assertSameIdentity(expected: JobProgressSnapshot, actual: JobProgressSnapshot): void {
+  for (const field of [
+    "application",
+    "component",
+    "jobId",
+    "sourceRevision",
+    "contractHash",
+    "startedAt",
+  ] as const) {
+    if (expected[field] !== actual[field]) {
+      throw new Error(`job progress sample ${field} does not match`);
+    }
+  }
+}
+
+function startPublication(
+  publish: JobProgressReporterOptions["publish"],
+  snapshot: JobProgressSnapshot,
+  timeoutMs: number,
+): { result: Promise<void>; settled: Promise<void> } {
+  const controller = new AbortController();
+  let timeout: NodeJS.Timeout | undefined;
+  const write = publish(snapshot, controller.signal);
+  const deadline = new Promise<never>((_resolve, reject) => {
+    timeout = setTimeout(() => {
+      controller.abort();
+      reject(new Error(`job progress publication timed out after ${timeoutMs} ms`));
+    }, timeoutMs);
+  });
+  const result = Promise.race([write, deadline]).finally(() => {
+    if (timeout !== undefined) clearTimeout(timeout);
+  });
+  return {
+    result,
+    settled: write.then(
+      () => undefined,
+      () => undefined,
+    ),
+  };
+}
+
+function validatePreviousSnapshot(
+  identity: JobProgressReporterOptions,
+  previous: JobProgressSnapshot,
+): JobProgressSnapshot {
+  const validated = validateJobProgressSnapshot(previous);
+  for (const field of [
+    "application",
+    "component",
+    "jobId",
+    "sourceRevision",
+    "contractHash",
+    "startedAt",
+  ] as const) {
+    if (identity[field] !== validated[field]) {
+      throw new Error(`job progress previous snapshot ${field} does not match`);
+    }
+  }
+  if (isTerminalJobProgressState(validated.state)) {
+    throw new Error("job progress cannot resume from a terminal snapshot");
+  }
+  if (identity.deadlineAt !== validated.deadlineAt) {
+    throw new Error("job progress previous snapshot deadlineAt does not match");
+  }
+  return validated;
+}
+
+function cloneSnapshot(snapshot: JobProgressSnapshot): JobProgressSnapshot {
+  return structuredClone(snapshot);
+}
+
+function nonNegativeInteger(value: number, field: string): number {
+  if (!Number.isSafeInteger(value) || value < 0) {
+    throw new Error(`${field} must be a non-negative safe integer`);
+  }
+  return value;
+}
+
+function positiveInteger(value: number, field: string): number {
+  if (!Number.isSafeInteger(value) || value <= 0) {
+    throw new Error(`${field} must be a positive safe integer`);
+  }
+  return value;
+}

package/src/job-progress/types.ts

@@ -0,0 +1,92 @@
+import type {
+  ProgressEstimate,
+  ProgressTrackState,
+  WorkflowProgressData,
+} from "../workflows/index.js";
+
+export const JOB_PROGRESS_SCHEMA = "pi-workflows.job-progress.v1" as const;
+
+export type JobProgressState =
+  | "queued"
+  | "running"
+  | "waiting"
+  | "blocked"
+  | "completed"
+  | "failed"
+  | "cancelled"
+  | "unknown";
+
+export type JobProgressTrack = {
+  key: string;
+  data: WorkflowProgressData;
+};
+
+export type JobProgressCost = {
+  settledUsd: number;
+  reservedUsd: number;
+};
+
+export type JobProgressSnapshot = {
+  schema: typeof JOB_PROGRESS_SCHEMA;
+  application: string;
+  component: string;
+  jobId: string;
+  sourceRevision: string;
+  contractHash: string;
+  sequence: number;
+  state: JobProgressState;
+  phase: string;
+  startedAt: string;
+  updatedAt: string;
+  deadlineAt?: string;
+  finishedAt?: string;
+  tracks: JobProgressTrack[];
+  cost?: JobProgressCost;
+};
+
+export type JobProgressIdentity = Pick<
+  JobProgressSnapshot,
+  "application" | "component" | "jobId" | "sourceRevision" | "contractHash" | "startedAt"
+> & {
+  deadlineAt?: string;
+};
+
+export type JobProgressUpdate = {
+  state?: JobProgressState;
+  phase?: string;
+  tracks?: JobProgressTrack[];
+  cost?: JobProgressCost;
+  finishedAt?: string;
+  force?: boolean;
+};
+
+export type JobProgressPublish = (
+  snapshot: JobProgressSnapshot,
+  signal: AbortSignal,
+) => Promise<void>;
+
+type JobProgressReporterBaseOptions = JobProgressIdentity & {
+  initialState?: Exclude<JobProgressState, "completed" | "failed" | "cancelled">;
+  initialPhase?: string;
+  publish: JobProgressPublish;
+  minimumIntervalMs?: number;
+  publishTimeoutMs?: number;
+  now?: () => Date;
+};
+
+export type JobProgressReporterOptions = JobProgressReporterBaseOptions &
+  (
+    | { initialTracks: JobProgressTrack[]; previousSnapshot?: never }
+    | { initialTracks?: JobProgressTrack[]; previousSnapshot: JobProgressSnapshot }
+  );
+
+export type JobProgressPublishResult = {
+  snapshot: JobProgressSnapshot;
+  published: boolean;
+};
+
+export type JobProgressEstimate = {
+  snapshot: JobProgressSnapshot;
+  tracks: ProgressTrackState[];
+  estimates: ProgressEstimate[];
+};

package/src/job-progress/validation.ts

@@ -0,0 +1,255 @@
+import { validateProgressData } from "../workflows/index.js";
+import {
+  JOB_PROGRESS_SCHEMA,
+  type JobProgressCost,
+  type JobProgressSnapshot,
+  type JobProgressState,
+  type JobProgressTrack,
+} from "./types.js";
+
+export const MAX_JOB_PROGRESS_BYTES = 64 * 1024;
+export const MAX_JOB_PROGRESS_TRACKS = 128;
+
+const SNAPSHOT_FIELDS = new Set([
+  "schema",
+  "application",
+  "component",
+  "jobId",
+  "sourceRevision",
+  "contractHash",
+  "sequence",
+  "state",
+  "phase",
+  "startedAt",
+  "updatedAt",
+  "deadlineAt",
+  "finishedAt",
+  "tracks",
+  "cost",
+]);
+const TRACK_FIELDS = new Set(["key", "data"]);
+const COST_FIELDS = new Set(["settledUsd", "reservedUsd"]);
+const STATES = new Set<JobProgressState>([
+  "queued",
+  "running",
+  "waiting",
+  "blocked",
+  "completed",
+  "failed",
+  "cancelled",
+  "unknown",
+]);
+const KEY_PATTERN = /^[A-Za-z0-9][A-Za-z0-9._:/-]{0,127}$/;
+const RFC_3339_PATTERN =
+  /^(\d{4})-(\d{2})-(\d{2})T(?:[01]\d|2[0-3]):[0-5]\d:[0-5]\d(?:\.\d+)?(?:Z|[+-](?:[01]\d|2[0-3]):[0-5]\d)$/;
+
+export function validateJobProgressSnapshot(value: unknown): JobProgressSnapshot {
+  const bytes = jsonBytes(value);
+  if (bytes > MAX_JOB_PROGRESS_BYTES) {
+    throw new Error(`job progress snapshot must be at most ${MAX_JOB_PROGRESS_BYTES} bytes`);
+  }
+  if (!isRecord(value)) throw new Error("job progress snapshot must be an object");
+  rejectUnknown(value, SNAPSHOT_FIELDS, "job progress");
+  if (value.schema !== JOB_PROGRESS_SCHEMA) {
+    throw new Error(`job progress.schema must equal ${JOB_PROGRESS_SCHEMA}`);
+  }
+
+  const application = requiredText(value.application, "job progress.application", 100);
+  const component = requiredText(value.component, "job progress.component", 100);
+  const jobId = requiredText(value.jobId, "job progress.jobId", 200);
+  const sourceRevision = requiredText(value.sourceRevision, "job progress.sourceRevision", 200);
+  const contractHash = requiredText(value.contractHash, "job progress.contractHash", 200);
+  const sequence = requiredInteger(value.sequence, "job progress.sequence");
+  const state = requiredState(value.state);
+  const phase = requiredText(value.phase, "job progress.phase", 100);
+  const startedAt = requiredTimestamp(value.startedAt, "job progress.startedAt");
+  const updatedAt = requiredTimestamp(value.updatedAt, "job progress.updatedAt");
+  const deadlineAt = optionalTimestamp(value.deadlineAt, "job progress.deadlineAt");
+  const finishedAt = optionalTimestamp(value.finishedAt, "job progress.finishedAt");
+  const tracks = requiredTracks(value.tracks);
+  const cost = optionalCost(value.cost);
+
+  if (Date.parse(updatedAt) < Date.parse(startedAt)) {
+    throw new Error("job progress.updatedAt must not be before startedAt");
+  }
+  if (deadlineAt !== undefined && Date.parse(deadlineAt) <= Date.parse(startedAt)) {
+    throw new Error("job progress.deadlineAt must be after startedAt");
+  }
+  if (finishedAt !== undefined && Date.parse(finishedAt) < Date.parse(startedAt)) {
+    throw new Error("job progress.finishedAt must not be before startedAt");
+  }
+  if (finishedAt !== undefined && Date.parse(finishedAt) > Date.parse(updatedAt)) {
+    throw new Error("job progress.finishedAt must not be after updatedAt");
+  }
+  if (isTerminal(state) && finishedAt === undefined) {
+    throw new Error("job progress.finishedAt is required for a terminal state");
+  }
+  if (!isTerminal(state) && finishedAt !== undefined) {
+    throw new Error("job progress.finishedAt is allowed only for a terminal state");
+  }
+  if (isTerminal(state) && tracks.some((track) => !isTerminalTrack(track))) {
+    throw new Error("job progress tracks must be terminal when the job state is terminal");
+  }
+
+  return {
+    schema: JOB_PROGRESS_SCHEMA,
+    application,
+    component,
+    jobId,
+    sourceRevision,
+    contractHash,
+    sequence,
+    state,
+    phase,
+    startedAt,
+    updatedAt,
+    ...(deadlineAt === undefined ? {} : { deadlineAt }),
+    ...(finishedAt === undefined ? {} : { finishedAt }),
+    tracks,
+    ...(cost === undefined ? {} : { cost }),
+  };
+}
+
+export function isTerminalJobProgressState(
+  state: JobProgressState,
+): state is "completed" | "failed" | "cancelled" {
+  return isTerminal(state);
+}
+
+function requiredTracks(value: unknown): JobProgressTrack[] {
+  if (!Array.isArray(value)) throw new Error("job progress.tracks must be an array");
+  if (value.length < 1) throw new Error("job progress.tracks must contain at least one entry");
+  if (value.length > MAX_JOB_PROGRESS_TRACKS) {
+    throw new Error(`job progress.tracks must contain at most ${MAX_JOB_PROGRESS_TRACKS} entries`);
+  }
+  const keys = new Set<string>();
+  return value.map((item, index) => {
+    if (!isRecord(item)) throw new Error(`job progress.tracks[${index}] must be an object`);
+    rejectUnknown(item, TRACK_FIELDS, `job progress.tracks[${index}]`);
+    if (typeof item.key !== "string" || !KEY_PATTERN.test(item.key)) {
+      throw new Error(
+        `job progress.tracks[${index}].key must match [A-Za-z0-9][A-Za-z0-9._:/-]{0,127}`,
+      );
+    }
+    if (keys.has(item.key)) throw new Error(`job progress track key ${item.key} is duplicated`);
+    keys.add(item.key);
+    if (!isRecord(item.data)) {
+      throw new Error(`job progress.tracks[${index}].data must be an object`);
+    }
+    return { key: item.key, data: structuredClone(validateProgressData(item.data)) };
+  });
+}
+
+function optionalCost(value: unknown): JobProgressCost | undefined {
+  if (value === undefined) return undefined;
+  if (!isRecord(value)) throw new Error("job progress.cost must be an object");
+  rejectUnknown(value, COST_FIELDS, "job progress.cost");
+  return {
+    settledUsd: requiredNonNegative(value.settledUsd, "job progress.cost.settledUsd"),
+    reservedUsd: requiredNonNegative(value.reservedUsd, "job progress.cost.reservedUsd"),
+  };
+}
+
+function requiredState(value: unknown): JobProgressState {
+  if (typeof value !== "string" || !STATES.has(value as JobProgressState)) {
+    throw new Error("job progress.state is invalid");
+  }
+  return value as JobProgressState;
+}
+
+function requiredText(value: unknown, field: string, max: number): string {
+  if (typeof value !== "string" || value.trim().length < 1 || value.trim().length > max) {
+    throw new Error(`${field} must be 1 to ${max} characters`);
+  }
+  if ([...value].some(isControlCharacter))
+    throw new Error(`${field} must not contain control characters`);
+  return value;
+}
+
+function requiredInteger(value: unknown, field: string): number {
+  if (!Number.isSafeInteger(value) || (value as number) < 0) {
+    throw new Error(`${field} must be a non-negative safe integer`);
+  }
+  return value as number;
+}
+
+function requiredNonNegative(value: unknown, field: string): number {
+  if (typeof value !== "number" || !Number.isFinite(value) || value < 0) {
+    throw new Error(`${field} must be a finite non-negative number`);
+  }
+  return value;
+}
+
+function requiredTimestamp(value: unknown, field: string): string {
+  const parsed = optionalTimestamp(value, field);
+  if (parsed === undefined) throw new Error(`${field} is required`);
+  return parsed;
+}
+
+function optionalTimestamp(value: unknown, field: string): string | undefined {
+  if (value === undefined) return undefined;
+  if (typeof value !== "string") {
+    throw new Error(`${field} must be an RFC 3339 timestamp with an offset`);
+  }
+  const match = RFC_3339_PATTERN.exec(value);
+  if (match === null || !validCalendarDate(match[1], match[2], match[3])) {
+    throw new Error(`${field} must be an RFC 3339 timestamp with an offset`);
+  }
+  return value;
+}
+
+function validCalendarDate(
+  yearText: string | undefined,
+  monthText: string | undefined,
+  dayText: string | undefined,
+): boolean {
+  const year = Number(yearText);
+  const month = Number(monthText);
+  const day = Number(dayText);
+  if (!Number.isInteger(year) || year < 1 || month < 1 || month > 12 || day < 1) return false;
+  return day <= new Date(Date.UTC(year, month, 0)).getUTCDate();
+}
+
+function rejectUnknown(
+  value: Record<string, unknown>,
+  allowed: ReadonlySet<string>,
+  field: string,
+): void {
+  for (const key of Object.keys(value)) {
+    if (!allowed.has(key)) throw new Error(`${field}.${key} is not supported`);
+  }
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  if (value === null || typeof value !== "object" || Array.isArray(value)) return false;
+  const prototype = Object.getPrototypeOf(value) as unknown;
+  return prototype === Object.prototype || prototype === null;
+}
+
+function jsonBytes(value: unknown): number {
+  let encoded: string | undefined;
+  try {
+    encoded = JSON.stringify(value);
+  } catch {
+    throw new Error("job progress snapshot must be JSON serializable");
+  }
+  if (encoded === undefined) throw new Error("job progress snapshot must be JSON serializable");
+  return Buffer.byteLength(encoded, "utf8");
+}
+
+function isControlCharacter(character: string): boolean {
+  const code = character.codePointAt(0) ?? 0;
+  return code < 32 || (code >= 127 && code <= 159);
+}
+
+function isTerminal(state: JobProgressState): boolean {
+  return state === "completed" || state === "failed" || state === "cancelled";
+}
+
+function isTerminalTrack(track: JobProgressTrack): boolean {
+  return (
+    track.data.status === "completed" ||
+    track.data.status === "failed" ||
+    track.data.status === "cancelled"
+  );
+}