alchemy 2.0.0-beta.3 → 2.0.0-beta.31

package/src/Apply.ts

@@ -1,3 +1,4 @@
+import * as Cause from "effect/Cause";
 import * as Deferred from "effect/Deferred";
 import * as Effect from "effect/Effect";
 import * as Option from "effect/Option";
@@ -25,6 +26,7 @@ import { findProviderByType } from "./Provider.ts";
 import type { ResourceBinding } from "./Resource.ts";
 import { Stack } from "./Stack.ts";
 import { Stage } from "./Stage.ts";
+import { recordResourceOp, type ResourceOp } from "./Telemetry/Metrics.ts";
 import {
   type CreatedResourceState,
   type CreatingResourceState,
@@ -81,6 +83,41 @@ const provideLifecycleScope =
       ),
     ) as Effect.Effect<A, E, Exclude<R, InstanceId | Artifacts>>;
 
+/**
+ * Instruments a single provider lifecycle call with an OTel span
+ * (`provider.<op>`), the resource counter / duration histogram, and the
+ * scoped artifacts/instance services normally supplied by
+ * {@link provideLifecycleScope}.
+ *
+ * This is the only call site through which provider lifecycle methods
+ * are dispatched, so wrapping it here gives us a fully-instrumented
+ * toolchain without touching any individual provider implementation.
+ */
+const instrumentLifecycle =
+  (
+    op: ResourceOp,
+    fqn: string,
+    resourceType: string,
+    logicalId: string,
+    instanceId: string,
+  ) =>
+  <A, E, R>(
+    effect: Effect.Effect<A, E, R>,
+  ): Effect.Effect<A, E, Exclude<R, InstanceId | Artifacts>> =>
+    effect.pipe(
+      provideLifecycleScope(fqn, instanceId),
+      recordResourceOp(resourceType, op),
+      Effect.withSpan(`provider.${op}`, {
+        attributes: {
+          "alchemy.resource.fqn": fqn,
+          "alchemy.resource.type": resourceType,
+          "alchemy.resource.logical_id": logicalId,
+          "alchemy.resource.instance_id": instanceId,
+          "alchemy.resource.op": op,
+        },
+      }),
+    );
+
 export const apply = <P extends Plan>(
   plan: P,
 ): Effect.Effect<
@@ -88,68 +125,74 @@ export const apply = <P extends Plan>(
   Output.InvalidReferenceError | Output.MissingSourceError | StateStoreError,
   Cli | State | Stack | Stage
 > =>
-  ensureArtifactStore(
-    Effect.gen(function* () {
-      const cli = yield* Cli;
-      const session = yield* cli.startApplySession(plan);
-      const state = yield* State;
-      const stack = yield* Stack;
-      const stage = yield* Stage;
-      const stackName = stack.name;
-
-      const tracker: Record<string, ResourceTracker> = {};
-      const terminalStatuses = new Map<
-        string,
-        {
-          id: string;
-          type: string;
-          status: Extract<ApplyStatus, "created" | "updated">;
-        }
-      >();
-
-      yield* executePlan(
-        plan,
-        tracker,
-        terminalStatuses,
-        session,
-        state,
-        stackName,
-        stage,
-      );
+  Effect.gen(function* () {
+    const cli = yield* Cli;
+    const session = yield* cli.startApplySession(plan);
+    const state = yield* State;
+    const stack = yield* Stack;
+    const stage = yield* Stage;
+    const stackName = stack.name;
+
+    const tracker: Record<string, ResourceTracker> = {};
+    const terminalStatuses = new Map<
+      string,
+      {
+        id: string;
+        type: string;
+        status: Extract<ApplyStatus, "created" | "updated">;
+      }
+    >();
+
+    yield* executePlan(
+      plan,
+      tracker,
+      terminalStatuses,
+      session,
+      state,
+      stackName,
+      stage,
+    );
 
-      // TODO(sam): support roll back to previous state if errors occur during expansion
-      // -> RISK: some UPDATEs may not be reversible (i.e. trigger replacements)
-      // TODO(sam): should pivot be done separately? E.g shift traffic?
+    // TODO(sam): support roll back to previous state if errors occur during expansion
+    // -> RISK: some UPDATEs may not be reversible (i.e. trigger replacements)
+    // TODO(sam): should pivot be done separately? E.g shift traffic?
 
-      yield* collectGarbage(plan, session);
+    yield* collectGarbage(plan, session);
 
-      yield* converge(
-        plan,
-        tracker,
-        terminalStatuses,
-        session,
-        state,
-        stackName,
-        stage,
-      );
+    yield* converge(
+      plan,
+      tracker,
+      terminalStatuses,
+      session,
+      state,
+      stackName,
+      stage,
+    );
 
-      yield* Effect.forEach(
-        Array.from(terminalStatuses.values()),
-        ({ id, type, status }) =>
-          session.emit({ kind: "status-change", id, type, status }),
-        { concurrency: "unbounded" },
-      );
+    yield* Effect.forEach(
+      Array.from(terminalStatuses.values()),
+      ({ id, type, status }) =>
+        session.emit({ kind: "status-change", id, type, status }),
+      { concurrency: "unbounded" },
+    );
 
-      yield* session.done();
+    yield* session.done();
 
-      if (!plan.output) {
-        return undefined;
-      }
+    if (!plan.output) {
+      return undefined;
+    }
 
-      const outputs = Object.fromEntries(
-        Object.entries(tracker).map(([fqn, t]) => [fqn, t.output]),
-      );
-      return yield* Output.evaluate(plan.output, outputs);
+    const outputs = Object.fromEntries(
+      Object.entries(tracker).map(([fqn, t]) => [fqn, t.output]),
+    );
+    return yield* Output.evaluate(plan.output, outputs);
+  }).pipe(
+    ensureArtifactStore,
+    Effect.withSpan("apply", {
+      attributes: {
+        "alchemy.resources.count": Object.keys(plan.resources).length,
+        "alchemy.deletions.count": Object.keys(plan.deletions).length,
+      },
     }),
   );
 
@@ -204,6 +247,8 @@ const executePlan = Effect.fnUntraced(function* (
       { concurrency: "unbounded" },
     );
 
+  const failures: LifecycleFailure[] = [];
+
   yield* Effect.all(
     Object.entries(plan.resources).map(([fqn, node]) =>
       executeNode(
@@ -218,12 +263,28 @@ const executePlan = Effect.fnUntraced(function* (
         stage,
         getOutputs,
         waitForDeps,
+        failures,
+        plan.cycleMembers.has(fqn),
       ),
     ),
     { concurrency: "unbounded" },
   );
+
+  if (failures.length > 0) {
+    // Aggregate every collected lifecycle failure into a single parallel Cause
+    // so the apply ends with one combined error containing every distinct
+    // failure / defect that occurred across the concurrent fibers.
+    yield* Effect.failCause(failures.map((f) => f.cause).reduce(Cause.combine));
+  }
 });
 
+interface LifecycleFailure {
+  fqn: string;
+  logicalId: string;
+  type: string;
+  cause: Cause.Cause<unknown>;
+}
+
 const executeNode = (
   fqn: string,
   node: Apply,
@@ -250,6 +311,8 @@ const executeNode = (
   stage: string,
   getOutputs: () => Record<string, any>,
   waitForDeps: (fqns: string[]) => Effect.Effect<void[], never, never>,
+  failures: LifecycleFailure[],
+  inCycle: boolean,
 ): Effect.Effect<void, never, never> =>
   Effect.gen(function* () {
     const logicalId = node.resource.LogicalId;
@@ -413,7 +476,15 @@ const executeNode = (
               instanceId,
               bindings: excludeDeletedBindings(node.bindings),
             })
-            .pipe(provideLifecycleScope(fqn, instanceId));
+            .pipe(
+              instrumentLifecycle(
+                "precreate",
+                fqn,
+                node.resource.Type,
+                logicalId,
+                instanceId,
+              ),
+            );
           yield* commit<CreatingResourceState>({
             status: "creating",
             fqn,
@@ -452,15 +523,24 @@ const executeNode = (
         );
 
         attr = yield* node.provider
-          .create({
+          .reconcile({
             id: logicalId,
             news,
             instanceId,
             bindings: bindingOutputs,
             session: scopedSession,
+            olds: undefined,
             output: attr,
           })
-          .pipe(provideLifecycleScope(fqn, instanceId));
+          .pipe(
+            instrumentLifecycle(
+              "create",
+              fqn,
+              node.resource.Type,
+              logicalId,
+              instanceId,
+            ),
+          );
 
         yield* commit<CreatedResourceState>({
           status: "created",
@@ -490,14 +570,26 @@ const executeNode = (
 
       // ── update ──
       if (node.action === "update") {
-        // Updates always begin by exposing the currently live output so downstream
-        // resources can continue to resolve references during the update pass.
-        yield* storeAndSignal({
-          output: node.state.attr,
-          props: node.state.props,
-          bindings: node.state.bindings ?? [],
-          instanceId,
-        });
+        // Cycle members publish their previous live attr *before* waiting on
+        // upstreams so the SCC can converge — peers in the cycle would
+        // otherwise deadlock waiting on each other. Phase 3 (`converge`)
+        // re-runs each peer's update against fresh outputs once everyone
+        // has settled.
+        //
+        // Linear (DAG) update nodes skip this entirely and simply wait for
+        // fresh upstream outputs, mirroring the create flow. This is the
+        // important property: a downstream of a non-cycle update never
+        // observes the upstream's stale attr, which prevents wasted/
+        // destructive intermediate updates (e.g. a Worker deploying with
+        // stale Build assets).
+        if (inCycle) {
+          yield* storeAndSignal({
+            output: node.state.attr,
+            props: node.state.props,
+            bindings: node.state.bindings ?? [],
+            instanceId,
+          });
+        }
 
         yield* waitForDeps(allUpstreamFqns());
         const outputs = getOutputs();
@@ -549,17 +641,24 @@ const executeNode = (
         );
 
         const attr = yield* node.provider
-          .update({
+          .reconcile({
             id: logicalId,
             news,
             instanceId,
             bindings: bindingOutputs,
             session: scopedSession,
             olds: previousProps,
-            // @ts-expect-error - type system says this can be undefined, can it be?
             output: node.state.attr,
           })
-          .pipe(provideLifecycleScope(fqn, instanceId));
+          .pipe(
+            instrumentLifecycle(
+              "update",
+              fqn,
+              node.resource.Type,
+              logicalId,
+              instanceId,
+            ),
+          );
 
         if (node.state.status === "replaced") {
           yield* commit<ReplacedResourceState>({
@@ -591,6 +690,10 @@ const executeNode = (
           bindings: bindingOutputs,
           instanceId,
         };
+        // Signal here for the linear (non-cycle) path. For in-cycle updates
+        // the deferred has already been resolved by the early `storeAndSignal`
+        // above and `signalReady` is a no-op the second time.
+        yield* signalReady;
 
         yield* markTerminal("updated");
         return;
@@ -659,7 +762,15 @@ const executeNode = (
               instanceId,
               bindings: excludeDeletedBindings(node.bindings),
             })
-            .pipe(provideLifecycleScope(fqn, instanceId));
+            .pipe(
+              instrumentLifecycle(
+                "precreate",
+                fqn,
+                node.resource.Type,
+                logicalId,
+                instanceId,
+              ),
+            );
           yield* commit<ReplacingResourceState>({
             status: "replacing",
             fqn,
@@ -700,15 +811,24 @@ const executeNode = (
         );
 
         attr = yield* node.provider
-          .create({
+          .reconcile({
             id: logicalId,
             news,
             instanceId,
             bindings: bindingOutputs,
             session: scopedSession,
+            olds: undefined,
             output: attr,
           })
-          .pipe(provideLifecycleScope(fqn, instanceId));
+          .pipe(
+            instrumentLifecycle(
+              "create",
+              fqn,
+              node.resource.Type,
+              logicalId,
+              instanceId,
+            ),
+          );
 
         yield* commit<ReplacedResourceState>({
           // Creation of the new generation succeeded; from here on the only remaining
@@ -747,14 +867,45 @@ const executeNode = (
       // @ts-expect-error - node is never, this should be unreachable
       return yield* Effect.die(`Unknown action: ${node.action}`);
     });
-  }) as Effect.Effect<void, never, never>;
+  }).pipe(
+    Effect.catchCause((cause) =>
+      // Record the failure, propagate it to any downstream resources waiting on
+      // our Deferred (so their waitForDeps short-circuits instead of deadlocking),
+      // emit a "fail" status to the session, and resolve to void so Effect.all
+      // does not interrupt sibling fibers. The aggregated cause is raised at
+      // the end of executePlan.
+      Effect.gen(function* () {
+        failures.push({
+          fqn,
+          logicalId: node.resource.LogicalId,
+          type: node.resource.Type,
+          cause,
+        });
+        yield* Deferred.failCause(ready[fqn], cause as Cause.Cause<never>);
+        yield* session.emit({
+          kind: "status-change",
+          id: node.resource.LogicalId,
+          type: node.resource.Type,
+          status: "fail",
+        });
+      }),
+    ),
+    Effect.withSpan("apply.resource", {
+      attributes: {
+        "alchemy.resource.fqn": fqn,
+        "alchemy.resource.type": node.resource.Type,
+        "alchemy.resource.logical_id": node.resource.LogicalId,
+        "alchemy.resource.action": node.action,
+      },
+    }),
+  ) as Effect.Effect<void, never, never>;
 
 // ── Phase 3: imperative convergence loop ───────────────────────────────────
 //
 // After the initial concurrent pass, some resources may have been created
 // with stale upstream values (e.g. a precreate stub instead of the final
 // output). Walk the plan and re-evaluate each resource's props/bindings
-// against the current tracker outputs. Call provider.update for any
+// against the current tracker outputs. Call provider.reconcile for any
 // resource whose resolved inputs differ from what it was last applied with.
 // Repeat until no resource needs updating.
 
@@ -823,7 +974,7 @@ const converge = Effect.fnUntraced(function* (
       } satisfies ScopedPlanStatusSession;
 
       const attr = yield* node.provider
-        .update({
+        .reconcile({
           id: logicalId,
           news: newProps,
           instanceId,
@@ -832,7 +983,15 @@ const converge = Effect.fnUntraced(function* (
           olds: oldProps,
           output: tracker[fqn].output,
         })
-        .pipe(provideLifecycleScope(fqn, instanceId));
+        .pipe(
+          instrumentLifecycle(
+            "update",
+            fqn,
+            node.resource.Type,
+            logicalId,
+            instanceId,
+          ),
+        );
 
       tracker[fqn] = {
         output: attr,
@@ -1009,7 +1168,15 @@ const collectGarbage = Effect.fnUntraced(function* (
                   session: scopedSession,
                   bindings: [],
                 })
-                .pipe(provideLifecycleScope(fqn, instanceId));
+                .pipe(
+                  instrumentLifecycle(
+                    "delete",
+                    fqn,
+                    resourceType,
+                    logicalId,
+                    instanceId,
+                  ),
+                );
             }
 
             if (isDeleteNode(node)) {