@osolmaz/pi-workflows 0.16.1 → 0.16.3

package/src/{controllers/manager.ts → resource-managers/runtime.ts}

@@ -1,21 +1,24 @@
 import { randomUUID } from "node:crypto";
 import { applyStatusPatch } from "./conditions.js";
-import { asAnyControllerDefinition, asTypedResource } from "./definition.js";
-import { ControllerEffectService } from "./effects.js";
-import { ResourceConflictError } from "./errors.js";
+import { asAnyResourceManagerDefinition, asTypedResource } from "./definition.js";
+import { ResourceManagerEffectService } from "./effects.js";
+import { ManagedResourceConflictError } from "./errors.js";
 import { createResultHelpers } from "./results.js";
-import type { ControllerStore } from "./store.js";
+import type { ResourceManagerStore } from "./store.js";
 import type {
-  AnyControllerDefinition,
-  ControllerDefinition,
-  ControllerQueueClaim,
-  ControllerResource,
-  ControllerResourceRef,
+  AnyResourceManagerDefinition,
+  ResourceManagerDefinition,
+  ResourceManagerQueueClaim,
+  ManagedResource,
+  ManagedResourceRef,
   JsonObject,
   ReconcileContext,
   ReconcileResult,
 } from "./types.js";
-import { ControllerWorkflowCoordinator, type ControllerWorkflowScheduler } from "./workflows.js";
+import {
+  ResourceManagerWorkflowCoordinator,
+  type ResourceManagerWorkflowScheduler,
+} from "./workflows.js";
 
 const DEFAULT_MAX_CONCURRENT = 4;
 const DEFAULT_TIMEOUT_MS = 60_000;
@@ -26,12 +29,12 @@ const DEFAULT_MAX_BACKOFF_MS = 60_000;
 const DEFAULT_JITTER_RATIO = 0.2;
 const MIN_LEASE_MS = 300;
 
-export type ControllerManagerOptions = {
-  store: ControllerStore;
-  controllers: AnyControllerDefinition[];
-  workflowScheduler?: ControllerWorkflowScheduler;
+export type ResourceManagerRuntimeOptions = {
+  store: ResourceManagerStore;
+  resourceManagers: AnyResourceManagerDefinition[];
+  workflowScheduler?: ResourceManagerWorkflowScheduler;
   maxConcurrent?: number;
-  controllerConcurrency?: Record<string, number>;
+  resourceManagerConcurrency?: Record<string, number>;
   defaultTimeoutMs?: number;
   leaseMs?: number;
   pollIntervalMs?: number;
@@ -42,13 +45,13 @@ export type ControllerManagerOptions = {
   random?: () => number;
 };
 
-export class ControllerManager {
-  readonly store: ControllerStore;
-  private readonly ownerId = `controller-manager-${randomUUID()}`;
-  private readonly definitions = new Map<string, AnyControllerDefinition>();
-  private readonly workflowCoordinator: ControllerWorkflowCoordinator;
+export class ResourceManagerRuntime {
+  readonly store: ResourceManagerStore;
+  private readonly ownerId = `resource-manager-runtime-${randomUUID()}`;
+  private readonly definitions = new Map<string, AnyResourceManagerDefinition>();
+  private readonly workflowCoordinator: ResourceManagerWorkflowCoordinator;
   private readonly maxConcurrent: number;
-  private readonly controllerConcurrency: Record<string, number>;
+  private readonly resourceManagerConcurrency: Record<string, number>;
   private readonly defaultTimeoutMs: number;
   private readonly leaseMs: number;
   private readonly pollIntervalMs: number;
@@ -57,20 +60,20 @@ export class ControllerManager {
   private readonly jitterRatio: number;
   private readonly now: () => Date;
   private readonly random: () => number;
-  private readonly activeByController = new Map<string, number>();
+  private readonly activeByResourceManager = new Map<string, number>();
   private readonly activeReconciles = new Map<string, AbortController>();
   private runAbort: AbortController | null = null;
-  private workerTasks: Promise<void>[] = [];
+  private runnerTasks: Promise<void>[] = [];
 
-  constructor(options: ControllerManagerOptions) {
+  constructor(options: ResourceManagerRuntimeOptions) {
     this.store = options.store;
-    for (const definition of options.controllers) {
+    for (const definition of options.resourceManagers) {
       if (this.definitions.has(definition.name)) {
-        throw new Error(`Duplicate controller definition: ${definition.name}`);
+        throw new Error(`Duplicate resource manager definition: ${definition.name}`);
       }
       this.definitions.set(definition.name, definition);
     }
-    this.workflowCoordinator = new ControllerWorkflowCoordinator(
+    this.workflowCoordinator = new ResourceManagerWorkflowCoordinator(
       options.store,
       options.workflowScheduler,
     );
@@ -78,12 +81,12 @@ export class ControllerManager {
       options.maxConcurrent ?? DEFAULT_MAX_CONCURRENT,
       "maxConcurrent",
     );
-    this.controllerConcurrency = options.controllerConcurrency ?? {};
-    for (const [name, value] of Object.entries(this.controllerConcurrency)) {
+    this.resourceManagerConcurrency = options.resourceManagerConcurrency ?? {};
+    for (const [name, value] of Object.entries(this.resourceManagerConcurrency)) {
       if (!this.definitions.has(name)) {
-        throw new Error(`Concurrency limit names an unknown controller: ${name}`);
+        throw new Error(`Concurrency limit names an unknown resource manager: ${name}`);
       }
-      positiveInteger(value, `controllerConcurrency.${name}`);
+      positiveInteger(value, `resourceManagerConcurrency.${name}`);
     }
     this.defaultTimeoutMs = positiveInteger(
       options.defaultTimeoutMs ?? DEFAULT_TIMEOUT_MS,
@@ -117,67 +120,67 @@ export class ControllerManager {
   }
 
   putResource<TSpec, TStatus>(
-    definition: ControllerDefinition<TSpec, TStatus>,
+    definition: ResourceManagerDefinition<TSpec, TStatus>,
     key: string,
     spec: TSpec,
-  ): ControllerResource<TSpec, TStatus> {
+  ): ManagedResource<TSpec, TStatus> {
     const registered = this.definitions.get(definition.name);
-    if (registered !== asAnyControllerDefinition(definition)) {
-      throw new Error(`Controller definition is not registered: ${definition.name}`);
+    if (registered !== asAnyResourceManagerDefinition(definition)) {
+      throw new Error(`ResourceManager definition is not registered: ${definition.name}`);
     }
     const initialStatus = definition.initialStatus(spec);
     const resource = this.store.putResource({
-      controller: definition.name,
+      resourceManager: definition.name,
       key,
       spec,
       initialStatus,
       now: this.now().toISOString(),
     });
     this.recordEvent(
-      { controller: definition.name, key },
+      { resourceManager: definition.name, key },
       resource.metadata.generation === 1 ? "resource_applied" : "resource_updated",
       { generation: resource.metadata.generation },
     );
     const current = this.store.getResource<TSpec, TStatus>({
-      controller: definition.name,
+      resourceManager: definition.name,
       key,
     });
-    if (current === undefined) throw new Error("Controller resource disappeared after its event");
+    if (current === undefined) throw new Error("Managed resource disappeared after its event");
     return current;
   }
 
-  putResourceByName(controller: string, key: string, spec: unknown): ControllerResource {
-    const definition = this.definitions.get(controller);
+  putResourceByName(resourceManager: string, key: string, spec: unknown): ManagedResource {
+    const definition = this.definitions.get(resourceManager);
     if (definition === undefined) {
-      throw new Error(`Unknown controller: ${controller}`);
+      throw new Error(`Unknown resource manager: ${resourceManager}`);
     }
     const initialStatus = definition.initialStatus(spec);
     const resource = this.store.putResource({
-      controller,
+      resourceManager,
       key,
       spec,
       initialStatus,
       now: this.now().toISOString(),
     });
     this.recordEvent(
-      { controller, key },
+      { resourceManager, key },
       resource.metadata.generation === 1 ? "resource_applied" : "resource_updated",
       { generation: resource.metadata.generation },
     );
-    const current = this.store.getResource({ controller, key });
-    if (current === undefined) throw new Error("Controller resource disappeared after its event");
+    const current = this.store.getResource({ resourceManager, key });
+    if (current === undefined) throw new Error("Managed resource disappeared after its event");
     return current;
   }
 
-  requestDeletion(ref: ControllerResourceRef): ControllerResource {
+  requestDeletion(ref: ManagedResourceRef): ManagedResource {
     this.store.requestDeletion(ref, this.now().toISOString());
     this.recordEvent(ref, "deletion_requested");
     const current = this.store.getResource(ref);
-    if (current === undefined) throw new Error("Controller resource disappeared after its event");
+    if (current === undefined) throw new Error("Managed resource disappeared after its event");
     return current;
   }
 
-  enqueue(ref: ControllerResourceRef, afterMs = 0): void {
+  enqueue(ref: ManagedResourceRef, afterMs = 0): void {
     if (!Number.isSafeInteger(afterMs) || afterMs < 0) {
       throw new Error("afterMs must be a non-negative safe integer");
     }
@@ -189,8 +192,8 @@ export class ControllerManager {
       return;
     }
     this.runAbort = new AbortController();
-    this.workerTasks = Array.from({ length: this.maxConcurrent }, () =>
-      this.workerLoop(this.runAbort?.signal as AbortSignal),
+    this.runnerTasks = Array.from({ length: this.maxConcurrent }, () =>
+      this.runnerLoop(this.runAbort?.signal as AbortSignal),
     );
   }
 
@@ -200,12 +203,12 @@ export class ControllerManager {
       return;
     }
     this.runAbort = null;
-    abort.abort(new Error("Controller manager stopped"));
-    for (const controller of this.activeReconciles.values()) {
-      controller.abort(new Error("Controller manager stopped"));
+    abort.abort(new Error("Resource manager stopped"));
+    for (const abortController of this.activeReconciles.values()) {
+      abortController.abort(new Error("Resource manager stopped"));
     }
-    await Promise.allSettled(this.workerTasks);
-    this.workerTasks = [];
+    await Promise.allSettled(this.runnerTasks);
+    this.runnerTasks = [];
   }
 
   async runOne(): Promise<boolean> {
@@ -224,16 +227,16 @@ export class ControllerManager {
       count += 1;
     }
     if (count === maxReconciles && this.readyQueueExists()) {
-      throw new Error(`Controller manager exceeded ${maxReconciles} reconciliations`);
+      throw new Error(`Resource manager exceeded ${maxReconciles} reconciliations`);
     }
     return count;
   }
 
-  get workflowRequests(): ControllerWorkflowCoordinator {
+  get workflowRequests(): ResourceManagerWorkflowCoordinator {
     return this.workflowCoordinator;
   }
 
-  private async workerLoop(signal: AbortSignal): Promise<void> {
+  private async runnerLoop(signal: AbortSignal): Promise<void> {
     while (!signal.aborted) {
       const claim = this.claimNext();
       if (claim === undefined) {
@@ -245,54 +248,54 @@ export class ControllerManager {
       } catch {
         if (signal.aborted) return;
         // A stale claim means another owner now controls that resource. Keep
-        // this worker alive so it can reconcile other queued resources.
+        // this runner alive so it can reconcile other queued resources.
       }
     }
   }
 
-  private claimNext(): ControllerQueueClaim | undefined {
+  private claimNext(): ResourceManagerQueueClaim | undefined {
     return this.store.claimNext({
-      controllers: this.eligibleControllers(),
+      resourceManagers: this.eligibleResourceManagers(),
       ownerId: this.ownerId,
       leaseMs: this.leaseMs,
       now: this.now().toISOString(),
     });
   }
 
-  private eligibleControllers(): string[] {
+  private eligibleResourceManagers(): string[] {
     return [...this.definitions.keys()].filter((name) => {
-      const active = this.activeByController.get(name) ?? 0;
-      const limit = this.controllerConcurrency[name] ?? this.maxConcurrent;
+      const active = this.activeByResourceManager.get(name) ?? 0;
+      const limit = this.resourceManagerConcurrency[name] ?? this.maxConcurrent;
       return active < limit;
     });
   }
 
-  private async processClaim(claim: ControllerQueueClaim): Promise<void> {
-    const definition = this.definitions.get(claim.controller);
+  private async processClaim(claim: ResourceManagerQueueClaim): Promise<void> {
+    const definition = this.definitions.get(claim.resourceManager);
     if (definition === undefined) {
       return;
     }
-    this.activeByController.set(
-      claim.controller,
-      (this.activeByController.get(claim.controller) ?? 0) + 1,
+    this.activeByResourceManager.set(
+      claim.resourceManager,
+      (this.activeByResourceManager.get(claim.resourceManager) ?? 0) + 1,
     );
     try {
       await this.reconcileClaim(definition, claim);
     } finally {
-      const active = (this.activeByController.get(claim.controller) ?? 1) - 1;
+      const active = (this.activeByResourceManager.get(claim.resourceManager) ?? 1) - 1;
       if (active === 0) {
-        this.activeByController.delete(claim.controller);
+        this.activeByResourceManager.delete(claim.resourceManager);
       } else {
-        this.activeByController.set(claim.controller, active);
+        this.activeByResourceManager.set(claim.resourceManager, active);
       }
     }
   }
 
   private async reconcileClaim(
-    definition: AnyControllerDefinition,
-    claim: ControllerQueueClaim,
+    definition: AnyResourceManagerDefinition,
+    claim: ResourceManagerQueueClaim,
   ): Promise<void> {
-    const ref = { controller: claim.controller, key: claim.key };
+    const ref = { resourceManager: claim.resourceManager, key: claim.key };
     const resource = this.store.getResource(ref);
     if (resource === undefined) {
       this.store.settleClaim(claim, this.now().toISOString());
@@ -314,7 +317,7 @@ export class ControllerManager {
       () => {
         const renewed = this.store.renewClaim(claim, this.leaseMs, this.now().toISOString());
         if (!renewed) {
-          abort.abort(new Error("Controller queue claim was lost"));
+          abort.abort(new Error("ResourceManager queue claim was lost"));
         }
       },
       Math.max(100, Math.floor(this.leaseMs / 3)),
@@ -350,14 +353,14 @@ export class ControllerManager {
   }
 
   private async callReconciler(
-    definition: AnyControllerDefinition,
-    resource: ControllerResource,
-    claim: ControllerQueueClaim,
+    definition: AnyResourceManagerDefinition,
+    resource: ManagedResource,
+    claim: ResourceManagerQueueClaim,
     signal: AbortSignal,
   ): Promise<ReconcileResult<unknown>> {
     const context: ReconcileContext<unknown> = {
       signal,
-      effects: new ControllerEffectService(this.store, resource, claim, signal),
+      effects: new ResourceManagerEffectService(this.store, resource, claim, signal),
       workflows: this.workflowCoordinator.forResource(resource, claim, signal),
       ...createResultHelpers<unknown>(),
     };
@@ -367,13 +370,13 @@ export class ControllerManager {
   }
 
   private async finishSuccessfulClaim(
-    claim: ControllerQueueClaim,
-    resource: ControllerResource,
+    claim: ResourceManagerQueueClaim,
+    resource: ManagedResource,
     result: ReconcileResult<unknown>,
     reconcileId: string,
     startedAtMs: number,
   ): Promise<void> {
-    const ref = { controller: claim.controller, key: claim.key };
+    const ref = { resourceManager: claim.resourceManager, key: claim.key };
     const now = this.now();
     const status = applyStatusPatch(
       resource.status,
@@ -416,7 +419,7 @@ export class ControllerManager {
         return;
       }
     } catch (error) {
-      if (error instanceof ResourceConflictError) {
+      if (error instanceof ManagedResourceConflictError) {
         this.recordEvent(ref, "reconcile_conflict", { reconcileId }, claim);
         this.store.requeueClaim(claim, { availableAt: now.toISOString() }, now.toISOString());
         return;
@@ -436,8 +439,8 @@ export class ControllerManager {
   }
 
   private async finishFailedClaim(
-    claim: ControllerQueueClaim,
-    ref: ControllerResourceRef,
+    claim: ResourceManagerQueueClaim,
+    ref: ManagedResourceRef,
     reconcileId: string,
     error: unknown,
     startedAtMs: number,
@@ -479,13 +482,13 @@ export class ControllerManager {
   }
 
   private recordEvent(
-    ref: ControllerResourceRef,
+    ref: ManagedResourceRef,
     type: string,
     payload: JsonObject = {},
-    claim?: ControllerQueueClaim,
+    claim?: ResourceManagerQueueClaim,
   ): void {
     this.store.recordEvent({
-      controller: ref.controller,
+      resourceManager: ref.resourceManager,
       key: ref.key,
       ...(claim === undefined ? {} : { claim }),
       type,
@@ -521,10 +524,10 @@ function raceWithAbort<T>(operation: Promise<T>, signal: AbortSignal): Promise<T
 
 function validateResult(result: ReconcileResult<unknown>): void {
   if (result === null || typeof result !== "object") {
-    throw new Error("Controller reconcile must return a result object");
+    throw new Error("ResourceManager reconcile must return a result object");
   }
   if (result.kind !== "settled" && result.kind !== "requeue") {
-    throw new Error("Controller reconcile returned an unknown result kind");
+    throw new Error("ResourceManager reconcile returned an unknown result kind");
   }
   if (result.kind === "settled" && "afterMs" in result) {
     throw new Error("A settled reconcile result cannot specify afterMs");