@osolmaz/pi-workflows 0.2.0 → 0.4.0

package/src/controllers/definition.ts

@@ -0,0 +1,65 @@
+import type { AnyControllerDefinition, ControllerDefinition, ControllerResource } from "./types.js";
+
+const CONTROLLER_DEFINITION_BRAND = Symbol.for("pi-workflows.controller-definition");
+const CONTROLLER_NAME_PATTERN = /^[a-z][a-z0-9-]*$/;
+
+export function defineController<TSpec, TStatus>(
+  definition: ControllerDefinition<TSpec, TStatus>,
+): ControllerDefinition<TSpec, TStatus> {
+  assertValidControllerDefinition(definition);
+  if (isControllerDefinition(definition)) {
+    return definition;
+  }
+  Object.defineProperty(definition, CONTROLLER_DEFINITION_BRAND, {
+    value: true,
+    enumerable: false,
+    configurable: false,
+    writable: false,
+  });
+  return definition;
+}
+
+export function isControllerDefinition(value: unknown): value is AnyControllerDefinition {
+  return (
+    value !== null &&
+    typeof value === "object" &&
+    (value as Record<PropertyKey, unknown>)[CONTROLLER_DEFINITION_BRAND] === true
+  );
+}
+
+export function assertValidControllerDefinition<TSpec, TStatus>(
+  definition: ControllerDefinition<TSpec, TStatus>,
+): void {
+  if (definition === null || typeof definition !== "object") {
+    throw new Error("Invalid controller definition: expected an object");
+  }
+  if (!CONTROLLER_NAME_PATTERN.test(definition.name)) {
+    throw new Error(
+      `Invalid controller definition: name ${JSON.stringify(definition.name)} must match ${CONTROLLER_NAME_PATTERN.source}`,
+    );
+  }
+  if (typeof definition.initialStatus !== "function") {
+    throw new Error("Invalid controller definition: initialStatus must be a function");
+  }
+  if (typeof definition.reconcile !== "function") {
+    throw new Error("Invalid controller definition: reconcile must be a function");
+  }
+  if (
+    definition.timeoutMs !== undefined &&
+    (!Number.isSafeInteger(definition.timeoutMs) || definition.timeoutMs <= 0)
+  ) {
+    throw new Error("Invalid controller definition: timeoutMs must be a positive safe integer");
+  }
+}
+
+export function asAnyControllerDefinition<TSpec, TStatus>(
+  definition: ControllerDefinition<TSpec, TStatus>,
+): AnyControllerDefinition {
+  return definition as unknown as ControllerDefinition<unknown, unknown>;
+}
+
+export function asTypedResource<TSpec, TStatus>(
+  resource: ControllerResource,
+): ControllerResource<TSpec, TStatus> {
+  return resource as ControllerResource<TSpec, TStatus>;
+}

package/src/controllers/effects.ts

@@ -0,0 +1,123 @@
+import { jsonFingerprint } from "./json.js";
+import type { ControllerStore } from "./store.js";
+import type {
+  ControllerEffects,
+  ControllerResource,
+  EffectApplication,
+  EffectDefinition,
+  EffectObservation,
+  EffectRecord,
+  JsonObject,
+} from "./types.js";
+
+export class ControllerEffectService implements ControllerEffects {
+  private used = false;
+
+  constructor(
+    private readonly store: ControllerStore,
+    private readonly resource: ControllerResource,
+    private readonly signal: AbortSignal,
+  ) {}
+
+  async ensure<TRequest>(definition: EffectDefinition<TRequest>): Promise<EffectRecord> {
+    if (this.used) {
+      throw new Error("A reconciliation pass may ensure only one external effect");
+    }
+    this.used = true;
+    const requestFingerprint = jsonFingerprint(definition.request);
+    const reservation = this.store.reserveEffect({
+      key: definition.key,
+      resourceUid: this.resource.metadata.uid,
+      generation: this.resource.metadata.generation,
+      kind: definition.kind,
+      requestFingerprint,
+    });
+    if (reservation.record.state === "applied" || reservation.record.state === "rejected") {
+      return reservation.record;
+    }
+
+    if (!reservation.created) {
+      const observed = await this.observe(definition);
+      const recovered = this.applyObservation(definition.key, observed);
+      if (recovered !== undefined) {
+        return recovered;
+      }
+    }
+
+    return await this.apply(definition);
+  }
+
+  private async observe<TRequest>(
+    definition: EffectDefinition<TRequest>,
+  ): Promise<EffectObservation> {
+    try {
+      return await definition.observe(this.signal);
+    } catch (error) {
+      this.recordEvent("effect_observe_failed", definition.key, {
+        error: boundedError(error),
+      });
+      throw error;
+    }
+  }
+
+  private applyObservation(key: string, observation: EffectObservation): EffectRecord | undefined {
+    if (observation.state === "not_applied") {
+      return undefined;
+    }
+    const record = this.store.updateEffect({
+      resourceUid: this.resource.metadata.uid,
+      key,
+      state: observation.state === "applied" ? "applied" : "indeterminate",
+      ...("externalRef" in observation && observation.externalRef !== undefined
+        ? { externalRef: observation.externalRef }
+        : {}),
+    });
+    this.recordEvent(
+      observation.state === "applied" ? "effect_recovered" : "effect_indeterminate",
+      key,
+    );
+    return record;
+  }
+
+  private async apply<TRequest>(definition: EffectDefinition<TRequest>): Promise<EffectRecord> {
+    let result: EffectApplication;
+    try {
+      result = await definition.apply(this.signal);
+    } catch (error) {
+      const message = boundedError(error);
+      const record = this.store.updateEffect({
+        resourceUid: this.resource.metadata.uid,
+        key: definition.key,
+        state: "indeterminate",
+        error: message,
+      });
+      this.recordEvent("effect_indeterminate", definition.key, { error: message });
+      return record;
+    }
+    const record = this.store.updateEffect({
+      resourceUid: this.resource.metadata.uid,
+      key: definition.key,
+      state: result.state,
+      ...(result.state === "applied" && result.externalRef !== undefined
+        ? { externalRef: result.externalRef }
+        : {}),
+      ...(result.state !== "applied" && result.error !== undefined ? { error: result.error } : {}),
+    });
+    this.recordEvent(`effect_${result.state}`, definition.key);
+    return record;
+  }
+
+  private recordEvent(type: string, effectKey: string, extra: JsonObject = {}): void {
+    this.store.recordEvent({
+      controller: this.resource.metadata.controller,
+      key: this.resource.metadata.key,
+      type,
+      payload: { effectKey, ...extra },
+    });
+  }
+}
+
+function boundedError(error: unknown): string {
+  const message = error instanceof Error ? error.message : String(error);
+  return message.length <= 8_192 ? message : `${message.slice(0, 8_192)}…`;
+}

package/src/controllers/errors.ts

@@ -0,0 +1,27 @@
+export class ResourceConflictError extends Error {
+  constructor(controller: string, key: string) {
+    super(`Controller resource ${controller}/${key} changed during reconciliation`);
+    this.name = "ResourceConflictError";
+  }
+}
+
+export class ResourceNotFoundError extends Error {
+  constructor(controller: string, key: string) {
+    super(`Controller resource not found: ${controller}/${key}`);
+    this.name = "ResourceNotFoundError";
+  }
+}
+
+export class EffectRequestConflictError extends Error {
+  constructor(key: string) {
+    super(`Effect key ${JSON.stringify(key)} was reused with a different request`);
+    this.name = "EffectRequestConflictError";
+  }
+}
+
+export class WorkflowRequestConflictError extends Error {
+  constructor(key: string) {
+    super(`Workflow request key ${JSON.stringify(key)} was reused with different input`);
+    this.name = "WorkflowRequestConflictError";
+  }
+}

package/src/controllers/index.ts

@@ -0,0 +1,90 @@
+export {
+  assertValidControllerDefinition,
+  defineController,
+  isControllerDefinition,
+} from "./definition.js";
+export {
+  applyStatusPatch,
+  conditionFalse,
+  conditionTrue,
+  conditionUnknown,
+  mergeConditions,
+} from "./conditions.js";
+export {
+  EffectRequestConflictError,
+  ResourceConflictError,
+  ResourceNotFoundError,
+  WorkflowRequestConflictError,
+} from "./errors.js";
+export { ControllerEffectService } from "./effects.js";
+export { canonicalJson, jsonFingerprint } from "./json.js";
+export { ControllerManager, type ControllerManagerOptions } from "./manager.js";
+export { createResultHelpers, requeue, requeueAfter, settled } from "./results.js";
+export {
+  SqliteControllerStore,
+  type RunEventRecord,
+  type WorkflowRunQueueRecord,
+} from "./sqlite.js";
+export {
+  CONTROLLER_STORE_SCHEMA,
+  controllerProjectScope,
+  controllerStoreBaseDir,
+  controllerStorePath,
+  projectControllerStoreBaseDir,
+  projectControllerStorePath,
+  type ControllerStore,
+  type EffectReservation,
+  type QueueItem,
+  type QueueRequeueOptions,
+  type WorkflowRecordUpdate,
+  type WorkflowReservation,
+} from "./store.js";
+export {
+  controllerFileStem,
+  controllerSearchDirs,
+  discoverControllers,
+  loadControllerFile,
+  loadDiscoveredControllers,
+  type DiscoveredController,
+} from "./loader.js";
+export {
+  WorkflowEngineScheduler,
+  type ResolvedChildWorkflow,
+  type WorkflowEngineSchedulerOptions,
+} from "./workflow-engine-scheduler.js";
+export {
+  ControllerWorkflowCoordinator,
+  type ControllerWorkflowScheduler,
+  type WorkflowSchedulerRequest,
+  type WorkflowSchedulerResult,
+} from "./workflows.js";
+export type {
+  AnyControllerDefinition,
+  ChildWorkflowRecord,
+  ChildWorkflowReference,
+  ChildWorkflowRequest,
+  ChildWorkflowState,
+  ControllerCondition,
+  ControllerConditionInput,
+  ControllerConditionStatus,
+  ControllerDefinition,
+  ControllerEffects,
+  ControllerEvent,
+  ControllerQueueClaim,
+  ControllerResource,
+  ControllerResourceRef,
+  ControllerResourceStatus,
+  ControllerStatusPatch,
+  ControllerWorkflows,
+  EffectApplication,
+  EffectDefinition,
+  EffectObservation,
+  EffectRecord,
+  EffectState,
+  JsonObject,
+  JsonPrimitive,
+  JsonValue,
+  MaybePromise,
+  ReconcileContext,
+  ReconcileResult,
+} from "./types.js";

package/src/controllers/json.ts

@@ -0,0 +1,62 @@
+import { createHash } from "node:crypto";
+import type { JsonValue } from "./types.js";
+
+export function assertJsonValue(value: unknown, description: string): asserts value is JsonValue {
+  normalizeJson(value, description, new Set());
+}
+
+export function canonicalJson(value: unknown, description = "value"): string {
+  return JSON.stringify(normalizeJson(value, description, new Set()));
+}
+
+export function jsonFingerprint(value: unknown): string {
+  return createHash("sha256").update(canonicalJson(value)).digest("hex");
+}
+
+export function parseStoredJson<T>(value: string, description: string): T {
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(value);
+  } catch (error) {
+    throw new Error(
+      `${description} contains invalid JSON: ${error instanceof Error ? error.message : String(error)}`,
+    );
+  }
+  assertJsonValue(parsed, description);
+  return parsed as T;
+}
+
+function normalizeJson(value: unknown, path: string, seen: Set<object>): JsonValue {
+  if (value === null || typeof value === "string" || typeof value === "boolean") {
+    return value;
+  }
+  if (typeof value === "number") {
+    if (!Number.isFinite(value)) {
+      throw new Error(`${path} contains a non-finite number`);
+    }
+    return value;
+  }
+  if (typeof value !== "object") {
+    throw new Error(`${path} is not JSON-serializable`);
+  }
+  if (seen.has(value)) {
+    throw new Error(`${path} contains a cycle`);
+  }
+  seen.add(value);
+  try {
+    if (Array.isArray(value)) {
+      return value.map((item, index) => normalizeJson(item, `${path}[${index}]`, seen));
+    }
+    const prototype = Object.getPrototypeOf(value) as object | null;
+    if (prototype !== Object.prototype && prototype !== null) {
+      throw new Error(`${path} must contain only plain objects and arrays`);
+    }
+    const result: Record<string, JsonValue> = {};
+    for (const key of Object.keys(value as Record<string, unknown>).sort()) {
+      result[key] = normalizeJson((value as Record<string, unknown>)[key], `${path}.${key}`, seen);
+    }
+    return result;
+  } finally {
+    seen.delete(value);
+  }
+}

package/src/controllers/loader.ts

@@ -0,0 +1,104 @@
+import fs from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+import { fileURLToPath, pathToFileURL } from "node:url";
+import { createJiti } from "jiti";
+import { isControllerDefinition } from "./definition.js";
+import type { AnyControllerDefinition } from "./types.js";
+
+const CONTROLLER_FILE_SUFFIXES = [
+  ".controller.ts",
+  ".controller.js",
+  ".controller.mts",
+  ".controller.mjs",
+];
+
+export type DiscoveredController = {
+  name: string;
+  path: string;
+  source: "project" | "global";
+};
+
+export function controllerSearchDirs(options: {
+  cwd: string;
+  homeDir?: string;
+}): { dir: string; source: DiscoveredController["source"] }[] {
+  const homeDir = options.homeDir ?? os.homedir();
+  return [
+    { dir: path.join(options.cwd, ".pi", "controllers"), source: "project" },
+    { dir: path.join(homeDir, ".pi", "agent", "controllers"), source: "global" },
+  ];
+}
+
+export function controllerFileStem(filePath: string): string {
+  const base = path.basename(filePath);
+  const suffix = CONTROLLER_FILE_SUFFIXES.find((candidate) => base.endsWith(candidate));
+  return suffix === undefined ? base : base.slice(0, -suffix.length);
+}
+
+const CONTROLLER_ENTRY = path.join(path.dirname(fileURLToPath(import.meta.url)), "index");
+const WORKFLOW_ENTRY = path.join(
+  path.dirname(fileURLToPath(import.meta.url)),
+  "../workflows/index",
+);
+
+export async function loadControllerFile(filePath: string): Promise<AnyControllerDefinition> {
+  const absolutePath = path.resolve(filePath);
+  const jiti = createJiti(pathToFileURL(absolutePath).href, {
+    interopDefault: true,
+    moduleCache: false,
+    alias: {
+      "@osolmaz/pi-workflows/controllers": CONTROLLER_ENTRY,
+      "@osolmaz/pi-workflows": WORKFLOW_ENTRY,
+    },
+  });
+  const loaded = (await jiti.import(absolutePath, { default: true })) as unknown;
+  if (!isControllerDefinition(loaded)) {
+    throw new Error(`Controller module must default-export defineController(...): ${absolutePath}`);
+  }
+  return loaded;
+}
+
+export async function discoverControllers(options: {
+  cwd: string;
+  homeDir?: string;
+}): Promise<DiscoveredController[]> {
+  const discovered: DiscoveredController[] = [];
+  const seen = new Set<string>();
+  for (const { dir, source } of controllerSearchDirs(options)) {
+    for (const filePath of await listControllerFiles(dir)) {
+      const name = controllerFileStem(filePath);
+      if (seen.has(name)) {
+        continue;
+      }
+      seen.add(name);
+      discovered.push({ name, path: filePath, source });
+    }
+  }
+  return discovered;
+}
+
+export async function loadDiscoveredControllers(options: {
+  cwd: string;
+  homeDir?: string;
+}): Promise<AnyControllerDefinition[]> {
+  return await Promise.all(
+    (await discoverControllers(options)).map(async (entry) => await loadControllerFile(entry.path)),
+  );
+}
+
+async function listControllerFiles(dir: string): Promise<string[]> {
+  let entries: import("node:fs").Dirent[];
+  try {
+    entries = await fs.readdir(dir, { withFileTypes: true });
+  } catch {
+    return [];
+  }
+  return entries
+    .filter(
+      (entry) =>
+        entry.isFile() && CONTROLLER_FILE_SUFFIXES.some((suffix) => entry.name.endsWith(suffix)),
+    )
+    .map((entry) => path.join(dir, entry.name))
+    .sort();
+}