alchemy 2.0.0-beta.17 → 2.0.0-beta.19

package/src/AWS/Providers.ts

@@ -49,13 +49,18 @@ export const providers = () =>
       AutoScaling.AutoScalingGroup,
       AutoScaling.LaunchTemplate,
       AutoScaling.ScalingPolicy,
+      CloudFront.CachePolicy,
       CloudFront.Distribution,
       CloudFront.Function,
       CloudFront.Invalidation,
+      CloudFront.KeyGroup,
       CloudFront.KeyValueStore,
       CloudFront.KvEntries,
       CloudFront.KvRoutesUpdate,
       CloudFront.OriginAccessControl,
+      CloudFront.OriginRequestPolicy,
+      CloudFront.PublicKey,
+      CloudFront.ResponseHeadersPolicy,
       CloudWatch.Alarm,
       CloudWatch.AlarmMuteRule,
       CloudWatch.AnomalyDetector,
@@ -124,6 +129,7 @@ export const providers = () =>
       EC2.Vpc,
       EC2.VpcEndpoint,
       ECR.Repository,
+      ECS.CapacityProvider,
       ECS.Cluster,
       ECS.DescribeTasksPolicy,
       ECS.ListTasksPolicy,
@@ -282,13 +288,18 @@ export const providers = () =>
         AutoScaling.AutoScalingGroupProvider(),
         AutoScaling.LaunchTemplateProvider(),
         AutoScaling.ScalingPolicyProvider(),
+        CloudFront.CachePolicyProvider(),
         CloudFront.DistributionProvider(),
         CloudFront.FunctionProvider(),
         CloudFront.InvalidationProvider(),
+        CloudFront.KeyGroupProvider(),
         CloudFront.KeyValueStoreProvider(),
         CloudFront.KvEntriesProvider(),
         CloudFront.KvRoutesUpdateProvider(),
         CloudFront.OriginAccessControlProvider(),
+        CloudFront.OriginRequestPolicyProvider(),
+        CloudFront.PublicKeyProvider(),
+        CloudFront.ResponseHeadersPolicyProvider(),
         CloudWatch.AlarmMuteRuleProvider(),
         CloudWatch.AlarmProvider(),
         CloudWatch.AnomalyDetectorProvider(),
@@ -357,6 +368,7 @@ export const providers = () =>
         EC2.VpcEndpointProvider(),
         EC2.VpcProvider(),
         ECR.RepositoryProvider(),
+        ECS.CapacityProviderProvider(),
         ECS.ClusterProvider(),
         ECS.DescribeTasksPolicyLive,
         ECS.ListTasksPolicyLive,

package/src/Apply.ts

@@ -25,6 +25,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 +82,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<
@@ -149,7 +185,15 @@ export const apply = <P extends Plan>(
       Object.entries(tracker).map(([fqn, t]) => [fqn, t.output]),
     );
     return yield* Output.evaluate(plan.output, outputs);
-  }).pipe(ensureArtifactStore);
+  }).pipe(
+    ensureArtifactStore,
+    Effect.withSpan("apply", {
+      attributes: {
+        "alchemy.resources.count": Object.keys(plan.resources).length,
+        "alchemy.deletions.count": Object.keys(plan.deletions).length,
+      },
+    }),
+  );
 
 // ── Phase 1: concurrent initial execution ──────────────────────────────────
 //
@@ -411,7 +455,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,
@@ -458,7 +510,15 @@ const executeNode = (
             session: scopedSession,
             output: attr,
           })
-          .pipe(provideLifecycleScope(fqn, instanceId));
+          .pipe(
+            instrumentLifecycle(
+              "create",
+              fqn,
+              node.resource.Type,
+              logicalId,
+              instanceId,
+            ),
+          );
 
         yield* commit<CreatedResourceState>({
           status: "created",
@@ -557,7 +617,15 @@ const executeNode = (
             // @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>({
@@ -657,7 +725,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,
@@ -706,7 +782,15 @@ const executeNode = (
             session: scopedSession,
             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
@@ -745,7 +829,16 @@ 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.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 ───────────────────────────────────
 //
@@ -830,7 +923,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,
@@ -1007,7 +1108,15 @@ const collectGarbage = Effect.fnUntraced(function* (
                   session: scopedSession,
                   bindings: [],
                 })
-                .pipe(provideLifecycleScope(fqn, instanceId));
+                .pipe(
+                  instrumentLifecycle(
+                    "delete",
+                    fqn,
+                    resourceType,
+                    logicalId,
+                    instanceId,
+                  ),
+                );
             }
 
             if (isDeleteNode(node)) {

package/src/Axiom/Annotation.ts

@@ -0,0 +1,95 @@
+import * as Operations from "@distilled.cloud/axiom/Operations";
+import * as Effect from "effect/Effect";
+import * as Provider from "../Provider.ts";
+import { Resource } from "../Resource.ts";
+import type { Providers } from "./Providers.ts";
+
+export type AnnotationProps = Operations.CreateAnnotationInput;
+
+export type Annotation = Resource<
+  "Axiom.Annotation",
+  AnnotationProps,
+  Operations.CreateAnnotationOutput,
+  never,
+  Providers
+>;
+
+/**
+ * An Axiom annotation — a vertical marker overlaid on charts to flag a
+ * deploy, incident, feature flag flip, or any other point/range event you
+ * want correlated with telemetry.
+ *
+ * Annotations are scoped to one or more `datasets`. Use a single `time` for
+ * a point marker or `time` + `endTime` for a range. The `type` (e.g.
+ * `"deploy"`, `"incident"`) groups markers visually in the UI.
+ *
+ * Although typically created at deploy/release time (out-of-band of
+ * regular IaC), modelling them as resources makes per-environment
+ * annotation history reproducible.
+ *
+ * @see https://axiom.co/docs/query-data/annotate-charts
+ *
+ * @section Creating an Annotation
+ * @example Point-in-time deploy marker
+ * ```typescript
+ * yield* Axiom.Annotation("deploy-1.2.3", {
+ *   type: "deploy",
+ *   title: "Release 1.2.3",
+ *   description: "https://github.com/acme/app/releases/tag/v1.2.3",
+ *   datasets: ["my-app-traces", "my-app-logs"],
+ *   time: new Date().toISOString(),
+ *   url: "https://github.com/acme/app/releases/tag/v1.2.3",
+ * });
+ * ```
+ *
+ * @example Incident time-range
+ * ```typescript
+ * yield* Axiom.Annotation("inc-2026-04-27", {
+ *   type: "incident",
+ *   title: "Database failover",
+ *   datasets: ["my-app-traces"],
+ *   time:    "2026-04-27T18:05:00Z",
+ *   endTime: "2026-04-27T18:32:00Z",
+ *   url: "https://incident.io/incidents/abc123",
+ * });
+ * ```
+ */
+export const Annotation = Resource<Annotation>("Axiom.Annotation");
+
+export const AnnotationProvider = () =>
+  Provider.effect(
+    Annotation,
+    Effect.gen(function* () {
+      const create = yield* Operations.createAnnotation;
+      const update = yield* Operations.updateAnnotation;
+      const get = yield* Operations.getAnnotation;
+      const del = yield* Operations.deleteAnnotation;
+
+      return {
+        stables: ["id"],
+        create: Effect.fn(function* ({ news }) {
+          return yield* create(news);
+        }),
+        update: Effect.fn(function* ({ news, output }) {
+          const result = yield* update({ ...news, id: output.id });
+          return { ...result, id: output.id, time: result.time ?? output.time };
+        }),
+        delete: Effect.fn(function* ({ output }) {
+          yield* del({ id: output.id }).pipe(
+            Effect.catchTag("NotFound", () => Effect.void),
+          );
+        }),
+        read: Effect.fn(function* ({ output }) {
+          if (!output?.id) return undefined;
+          return yield* get({ id: output.id }).pipe(
+            Effect.map((current) => ({
+              ...current,
+              id: current.id ?? output.id,
+              time: current.time ?? output.time,
+            })),
+            Effect.catchTag("NotFound", () => Effect.succeed(undefined)),
+          );
+        }),
+      };
+    }),
+  );

package/src/Axiom/ApiToken.ts

@@ -0,0 +1,125 @@
+import * as Operations from "@distilled.cloud/axiom/Operations";
+import * as Effect from "effect/Effect";
+import * as Redacted from "effect/Redacted";
+import { deepEqual, isResolved } from "../Diff.ts";
+import * as Provider from "../Provider.ts";
+import { Resource } from "../Resource.ts";
+import type { Providers } from "./Providers.ts";
+
+export type ApiTokenProps = Omit<Operations.CreateAPITokenInput, never>;
+
+export type ApiToken = Resource<
+  "Axiom.ApiToken",
+  ApiTokenProps,
+  Omit<Operations.CreateAPITokenOutput, "token"> & {
+    /**
+     * The bearer token. Returned only by `create` (and `regenerate`); Axiom
+     * does not return it on subsequent reads. Persisted in resource state via
+     * `Redacted` — handle with care.
+     */
+    token: Redacted.Redacted<string>;
+  },
+  never,
+  Providers
+>;
+
+/**
+ * An Axiom API token — a scoped bearer token used to authenticate API
+ * requests (ingest, query, admin). Capabilities are pinned at creation time;
+ * changing any field triggers a **replacement** because Axiom does not
+ * expose an update endpoint.
+ *
+ * The raw token value is returned only by `create`. After that, Axiom
+ * never echoes it back, so it is captured into `output.token` (as a
+ * {@link Redacted}) on initial create and persisted in resource state.
+ * Treat resource state as sensitive — anyone with read access can recover
+ * the token. Pair with a secret store for downstream consumption.
+ *
+ * @see https://axiom.co/docs/reference/tokens
+ *
+ * @section Creating an API Token
+ * @example Ingest-only token scoped to one dataset
+ * ```typescript
+ * const ingest = yield* Axiom.ApiToken("ingest", {
+ *   name: "prod-ingest",
+ *   description: "OTEL collector ingest",
+ *   datasetCapabilities: {
+ *     "my-app-traces": { ingest: ["create"] },
+ *   },
+ * });
+ * ```
+ *
+ * @example Read-only query token
+ * ```typescript
+ * yield* Axiom.ApiToken("query", {
+ *   name: "grafana-reader",
+ *   datasetCapabilities: {
+ *     "my-app-traces": { query: ["read"] },
+ *     "my-app-logs":   { query: ["read"] },
+ *   },
+ * });
+ * ```
+ *
+ * @section Consuming the Token
+ * @example Forward the token via Cloudflare Secrets
+ * ```typescript
+ * const secret = yield* Cloudflare.Secret("axiom-token", {
+ *   value: ingest.token,
+ * });
+ * ```
+ */
+export const ApiToken = Resource<ApiToken>("Axiom.ApiToken");
+
+export const ApiTokenProvider = () =>
+  Provider.effect(
+    ApiToken,
+    Effect.gen(function* () {
+      const create = yield* Operations.createAPIToken;
+      const get = yield* Operations.getAPIToken;
+      const del = yield* Operations.deleteAPIToken;
+
+      return {
+        stables: ["id", "token"],
+        diff: Effect.fn(function* ({ olds, news, output }) {
+          if (!isResolved(news)) return undefined;
+          // First create — let the engine create normally.
+          if (output == null) return undefined;
+          // Axiom has no update endpoint for tokens, so any actual change
+          // to the inputs forces a replacement (which mints a new bearer
+          // value). If nothing changed, fall through to `noop` so we don't
+          // needlessly rotate the token on every deploy.
+          if (deepEqual(olds, news)) return undefined;
+          return { action: "replace" } as const;
+        }),
+        create: Effect.fn(function* ({ news }) {
+          const result = yield* create(news);
+          if (!result.token) {
+            return yield* Effect.die(
+              new Error("Axiom did not return a token on create"),
+            );
+          }
+          return {
+            ...result,
+            token: Redacted.make(result.token),
+          };
+        }),
+        update: Effect.fn(function* ({ output }) {
+          // Diff returns "replace" for every change, so update should never
+          // run. If invoked, just return current state unchanged.
+          return output;
+        }),
+        delete: Effect.fn(function* ({ output }) {
+          yield* del({ id: output.id }).pipe(
+            Effect.catchTag("NotFound", () => Effect.void),
+          );
+        }),
+        read: Effect.fn(function* ({ output }) {
+          if (!output?.id) return undefined;
+          return yield* get({ id: output.id }).pipe(
+            Effect.map((current) => ({ ...current, token: output.token })),
+            Effect.catchTag("NotFound", () => Effect.succeed(undefined)),
+          );
+        }),
+      };
+    }),
+  );