@synth-deploy/server 0.1.0

package/src/fleet/fleet-executor.ts

@@ -0,0 +1,309 @@
+import type {
+  FleetDeployment,
+  FleetProgress,
+  FleetValidationResult,
+  EnvoyValidationResult,
+  DeploymentPlan,
+  RolloutConfig,
+} from "@synth-deploy/core";
+import type { EnvoyRegistry } from "../agent/envoy-registry.js";
+import { EnvoyClient } from "../agent/envoy-client.js";
+
+// ---------------------------------------------------------------------------
+// Fleet progress event types
+// ---------------------------------------------------------------------------
+
+export interface FleetProgressEvent {
+  type:
+    | "validation-started"
+    | "validation-complete"
+    | "batch-started"
+    | "envoy-started"
+    | "envoy-completed"
+    | "envoy-failed"
+    | "batch-completed"
+    | "fleet-completed"
+    | "fleet-failed"
+    | "fleet-paused";
+  envoyId?: string;
+  envoyName?: string;
+  batchIndex?: number;
+  progress: FleetProgress;
+  error?: string;
+}
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+function delay(ms: number): Promise<void> {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+function makeProgress(
+  totalEnvoys: number,
+  validated: number,
+  executing: number,
+  succeeded: number,
+  failed: number,
+  currentBatch?: number,
+  totalBatches?: number,
+): FleetProgress {
+  return {
+    totalEnvoys,
+    validated,
+    executing,
+    succeeded,
+    failed,
+    pending: totalEnvoys - succeeded - failed - executing,
+    currentBatch,
+    totalBatches,
+  };
+}
+
+// ---------------------------------------------------------------------------
+// FleetExecutor — orchestrates validation and progressive rollout
+// ---------------------------------------------------------------------------
+
+export class FleetExecutor {
+  constructor(
+    private envoyRegistry: EnvoyRegistry,
+    private createEnvoyClient: (url: string, token: string) => EnvoyClient,
+  ) {}
+
+  /**
+   * Validate a deployment plan against all target envoys in the fleet.
+   * Probes each envoy and asks it to validate the plan steps.
+   */
+  async validateFleet(
+    fleetDeployment: FleetDeployment,
+    plan: DeploymentPlan,
+  ): Promise<FleetValidationResult> {
+    const targetEnvoyIds =
+      fleetDeployment.envoyFilter ?? this.getEnvironmentEnvoyIds(fleetDeployment.environmentId);
+
+    const results: EnvoyValidationResult[] = [];
+
+    for (const envoyId of targetEnvoyIds) {
+      const entry = this.envoyRegistry.get(envoyId);
+      if (!entry) {
+        results.push({
+          envoyId,
+          envoyName: "unknown",
+          validated: false,
+          issues: [`Envoy ${envoyId} not found in registry`],
+        });
+        continue;
+      }
+
+      const client = this.createEnvoyClient(entry.url, entry.token);
+      try {
+        const validation = await client.validatePlan(plan.steps);
+        results.push({
+          envoyId,
+          envoyName: entry.name,
+          validated: validation.valid,
+          issues: validation.violations?.map((v) => v.reason),
+        });
+      } catch (err) {
+        results.push({
+          envoyId,
+          envoyName: entry.name,
+          validated: false,
+          issues: [
+            `Validation failed: ${err instanceof Error ? err.message : String(err)}`,
+          ],
+        });
+      }
+    }
+
+    return {
+      total: results.length,
+      validated: results.filter((r) => r.validated).length,
+      failed: results.filter((r) => !r.validated).length,
+      results,
+    };
+  }
+
+  /**
+   * Execute a progressive rollout across the fleet.
+   * Yields progress events as an async generator so callers can stream them.
+   */
+  async *executeRollout(
+    fleetDeployment: FleetDeployment,
+    plan: DeploymentPlan,
+    rollbackPlan?: DeploymentPlan,
+  ): AsyncGenerator<FleetProgressEvent> {
+    const validatedEnvoys =
+      fleetDeployment.validationResult?.results.filter((r) => r.validated) ?? [];
+    const config = fleetDeployment.rolloutConfig;
+    const totalEnvoys = validatedEnvoys.length;
+
+    if (totalEnvoys === 0) {
+      yield {
+        type: "fleet-failed",
+        progress: makeProgress(0, 0, 0, 0, 0),
+        error: "No validated envoys to execute against",
+      };
+      return;
+    }
+
+    // Build batches based on rollout strategy
+    const batches = this.buildBatches(validatedEnvoys, config);
+    const totalBatches = batches.length;
+
+    let succeeded = 0;
+    let failureCount = 0;
+
+    for (let i = 0; i < batches.length; i++) {
+      yield {
+        type: "batch-started",
+        batchIndex: i,
+        progress: makeProgress(totalEnvoys, totalEnvoys, batches[i].length, succeeded, failureCount, i, totalBatches),
+      };
+
+      for (const envoy of batches[i]) {
+        yield {
+          type: "envoy-started",
+          envoyId: envoy.envoyId,
+          envoyName: envoy.envoyName,
+          batchIndex: i,
+          progress: makeProgress(totalEnvoys, totalEnvoys, 1, succeeded, failureCount, i, totalBatches),
+        };
+
+        const entry = this.envoyRegistry.get(envoy.envoyId);
+        if (!entry) {
+          failureCount++;
+          yield {
+            type: "envoy-failed",
+            envoyId: envoy.envoyId,
+            envoyName: envoy.envoyName,
+            batchIndex: i,
+            progress: makeProgress(totalEnvoys, totalEnvoys, 0, succeeded, failureCount, i, totalBatches),
+            error: `Envoy ${envoy.envoyId} not found in registry`,
+          };
+
+          if (failureCount >= config.haltOnFailureCount) {
+            yield {
+              type: "fleet-failed",
+              progress: makeProgress(totalEnvoys, totalEnvoys, 0, succeeded, failureCount, i, totalBatches),
+              error: `Halted: ${failureCount} failure(s) reached threshold of ${config.haltOnFailureCount}`,
+            };
+            return;
+          }
+          continue;
+        }
+
+        const client = this.createEnvoyClient(entry.url, entry.token);
+        try {
+          await client.executeApprovedPlan({
+            deploymentId: fleetDeployment.id,
+            plan,
+            rollbackPlan: rollbackPlan ?? plan,
+            artifactType: "fleet",
+            artifactName: fleetDeployment.artifactId,
+            environmentId: fleetDeployment.environmentId,
+          });
+          succeeded++;
+          yield {
+            type: "envoy-completed",
+            envoyId: envoy.envoyId,
+            envoyName: envoy.envoyName,
+            batchIndex: i,
+            progress: makeProgress(totalEnvoys, totalEnvoys, 0, succeeded, failureCount, i, totalBatches),
+          };
+        } catch (err) {
+          failureCount++;
+          yield {
+            type: "envoy-failed",
+            envoyId: envoy.envoyId,
+            envoyName: envoy.envoyName,
+            batchIndex: i,
+            progress: makeProgress(totalEnvoys, totalEnvoys, 0, succeeded, failureCount, i, totalBatches),
+            error: err instanceof Error ? err.message : String(err),
+          };
+
+          if (failureCount >= config.haltOnFailureCount) {
+            yield {
+              type: "fleet-failed",
+              progress: makeProgress(totalEnvoys, totalEnvoys, 0, succeeded, failureCount, i, totalBatches),
+              error: `Halted: ${failureCount} failure(s) reached threshold of ${config.haltOnFailureCount}`,
+            };
+            return;
+          }
+        }
+      }
+
+      yield {
+        type: "batch-completed",
+        batchIndex: i,
+        progress: makeProgress(totalEnvoys, totalEnvoys, 0, succeeded, failureCount, i, totalBatches),
+      };
+
+      // Health check wait between batches
+      if (config.healthCheckWaitMs > 0 && i < batches.length - 1) {
+        await delay(config.healthCheckWaitMs);
+      }
+
+      // Pause between batches if configured — yield paused event and return.
+      // Caller resumes by calling executeRollout again with remaining batches.
+      if (config.pauseBetweenBatches && i < batches.length - 1) {
+        yield {
+          type: "fleet-paused",
+          batchIndex: i,
+          progress: makeProgress(totalEnvoys, totalEnvoys, 0, succeeded, failureCount, i, totalBatches),
+        };
+        return;
+      }
+    }
+
+    yield {
+      type: "fleet-completed",
+      progress: makeProgress(totalEnvoys, totalEnvoys, 0, succeeded, failureCount, totalBatches - 1, totalBatches),
+    };
+  }
+
+  /**
+   * Build execution batches based on the rollout strategy.
+   */
+  private buildBatches(
+    envoys: EnvoyValidationResult[],
+    config: RolloutConfig,
+  ): EnvoyValidationResult[][] {
+    if (envoys.length === 0) return [];
+
+    if (config.strategy === "all-at-once") {
+      return [envoys];
+    }
+
+    if (config.strategy === "canary") {
+      // First batch: single canary, second batch: everything else
+      return [[envoys[0]], envoys.slice(1)];
+    }
+
+    // batched strategy
+    const size =
+      config.batchSize ??
+      Math.max(1, Math.ceil(envoys.length * (config.batchPercent ?? 10) / 100));
+
+    const batches: EnvoyValidationResult[][] = [];
+    for (let i = 0; i < envoys.length; i += size) {
+      batches.push(envoys.slice(i, i + size));
+    }
+    return batches;
+  }
+
+  /**
+   * Get all envoy IDs assigned to a given environment.
+   */
+  private getEnvironmentEnvoyIds(environmentId: string): string[] {
+    return this.envoyRegistry
+      .list()
+      .filter(
+        (e) =>
+          e.assignedEnvironments.length === 0 ||
+          e.assignedEnvironments.includes(environmentId),
+      )
+      .map((e) => e.id);
+  }
+}

package/src/fleet/fleet-store.ts

@@ -0,0 +1,13 @@
+/**
+ * Re-exports the persistent fleet deployment store from @synth-deploy/core.
+ * Fleet deployments are now SQLite-backed to survive server restarts.
+ *
+ * Note: In-flight fleet operations that are mid-execution when the server
+ * crashes cannot be resumed — their status is persisted, but the active
+ * orchestration state (batch progress, in-flight envoy connections) is
+ * ephemeral. On restart, in-flight operations will appear as stale entries
+ * that users can inspect and manually re-trigger. Terminal states (completed,
+ * failed, rolled_back) are fully durable.
+ */
+
+export { PersistentFleetDeploymentStore as FleetDeploymentStore } from "@synth-deploy/core";

package/src/fleet/index.ts

@@ -0,0 +1,4 @@
+export { selectRepresentatives } from "./representative-selector.js";
+export { FleetExecutor } from "./fleet-executor.js";
+export type { FleetProgressEvent } from "./fleet-executor.js";
+export { FleetDeploymentStore } from "./fleet-store.js";

package/src/fleet/representative-selector.ts

@@ -0,0 +1,83 @@
+import type { EnvoyRegistryEntry } from "../agent/envoy-registry.js";
+
+/**
+ * Maximum number of representative envoys to select for plan validation.
+ * Keeps validation fast while covering platform diversity.
+ */
+const MAX_REPRESENTATIVES = 3;
+
+/**
+ * Select a representative subset of envoys for plan validation.
+ *
+ * Strategy:
+ * 1. Filter to healthy envoys only (health === "OK")
+ * 2. Group by platform (e.g. linux, darwin, windows)
+ * 3. Pick one per platform group, preferring most recently seen
+ * 4. Cap at MAX_REPRESENTATIVES
+ * 5. If all envoys share the same platform, pick 1
+ *
+ * Returns an array of envoy IDs.
+ */
+export function selectRepresentatives(
+  envoys: EnvoyRegistryEntry[],
+  _artifactId: string,
+): string[] {
+  // 1. Filter to healthy envoys
+  const healthy = envoys.filter((e) => e.health === "OK");
+  if (healthy.length === 0) return [];
+
+  // 2. Group by platform
+  const byPlatform = new Map<string, EnvoyRegistryEntry[]>();
+  for (const envoy of healthy) {
+    // Normalize: null/undefined platform treated as "unknown"
+    const platform = (envoy as { platform?: string | null }).platform ?? "unknown";
+    const group = byPlatform.get(platform) ?? [];
+    group.push(envoy);
+    byPlatform.set(platform, group);
+  }
+
+  // 3. If all same platform, pick the most recently seen one
+  if (byPlatform.size <= 1) {
+    const best = pickMostRecentlySeen(healthy);
+    return best ? [best.id] : [];
+  }
+
+  // 4. Pick one per platform group (prefer most recently seen)
+  const representatives: EnvoyRegistryEntry[] = [];
+  for (const group of byPlatform.values()) {
+    const best = pickMostRecentlySeen(group);
+    if (best) representatives.push(best);
+  }
+
+  // 5. Cap at MAX_REPRESENTATIVES (sort by lastSeen descending, take top N)
+  representatives.sort((a, b) => {
+    const aTime = a.lastSeen ? new Date(a.lastSeen).getTime() : 0;
+    const bTime = b.lastSeen ? new Date(b.lastSeen).getTime() : 0;
+    return bTime - aTime;
+  });
+
+  return representatives.slice(0, MAX_REPRESENTATIVES).map((e) => e.id);
+}
+
+/**
+ * Pick the envoy with the most recent `lastSeen` timestamp from a group.
+ */
+function pickMostRecentlySeen(
+  group: EnvoyRegistryEntry[],
+): EnvoyRegistryEntry | undefined {
+  if (group.length === 0) return undefined;
+  if (group.length === 1) return group[0];
+
+  let best = group[0];
+  let bestTime = best.lastSeen ? new Date(best.lastSeen).getTime() : 0;
+
+  for (let i = 1; i < group.length; i++) {
+    const t = group[i].lastSeen ? new Date(group[i].lastSeen!).getTime() : 0;
+    if (t > bestTime) {
+      best = group[i];
+      bestTime = t;
+    }
+  }
+
+  return best;
+}