alchemy 2.0.0-beta.13 → 2.0.0-beta.15

package/src/State/HttpStateApi.ts

@@ -0,0 +1,155 @@
+import * as Context from "effect/Context";
+import * as Effect from "effect/Effect";
+import * as Layer from "effect/Layer";
+import * as Redacted from "effect/Redacted";
+import * as Schema from "effect/Schema";
+import * as HttpApi from "effect/unstable/httpapi/HttpApi";
+import * as HttpApiEndpoint from "effect/unstable/httpapi/HttpApiEndpoint";
+import * as HttpApiError from "effect/unstable/httpapi/HttpApiError";
+import * as HttpApiGroup from "effect/unstable/httpapi/HttpApiGroup";
+import * as HttpApiMiddleware from "effect/unstable/httpapi/HttpApiMiddleware";
+import * as HttpApiSchema from "effect/unstable/httpapi/HttpApiSchema";
+import * as HttpApiSecurity from "effect/unstable/httpapi/HttpApiSecurity";
+
+export const ResourceStateSchema = Schema.Any;
+
+export class BearerTokenValidator extends Context.Service<
+  BearerTokenValidator,
+  {
+    readonly validate: (
+      token: string,
+    ) => Effect.Effect<void, HttpApiError.Unauthorized>;
+  }
+>()("alchemy/State/BearerTokenValidator") {}
+
+export class StateAuth extends HttpApiMiddleware.Service<
+  StateAuth,
+  { requires: BearerTokenValidator }
+>()("alchemy/State/StateAuth", {
+  security: {
+    bearer: HttpApiSecurity.bearer,
+  },
+  error: HttpApiError.UnauthorizedNoContent,
+}) {}
+
+export const StateAuthLive: Layer.Layer<
+  StateAuth,
+  never,
+  BearerTokenValidator
+> = Layer.effect(
+  StateAuth,
+  Effect.gen(function* () {
+    const validator = yield* BearerTokenValidator;
+    return {
+      bearer: (httpEffect, { credential }) =>
+        validator
+          .validate(Redacted.value(credential))
+          .pipe(Effect.flatMap(() => httpEffect)),
+    };
+  }),
+);
+
+/** `stack` path segment for nested REST resources. */
+const StackParams = Schema.Struct({
+  stack: Schema.String,
+});
+
+/** Optional stage selector for stack deletion. */
+const OptionalStageQuery = Schema.Struct({
+  stage: Schema.optional(Schema.String),
+});
+
+/** `(stack, stage)` path segments shared by stage-scoped endpoints. */
+const StackStage = Schema.Struct({
+  stack: Schema.String,
+  stage: Schema.String,
+});
+
+/** `(stack, stage, fqn)` path segments for a single resource. */
+const ResourceKey = Schema.Struct({
+  stack: Schema.String,
+  stage: Schema.String,
+  fqn: Schema.String,
+});
+
+export const ListStacks = HttpApiEndpoint.get("listStacks", "/state/stacks", {
+  success: Schema.Array(Schema.String),
+});
+
+export const ListStages = HttpApiEndpoint.get(
+  "listStages",
+  "/state/stacks/:stack/stages",
+  {
+    params: StackParams,
+    success: Schema.Array(Schema.String),
+  },
+);
+
+export const ListResources = HttpApiEndpoint.get(
+  "listResources",
+  "/state/stacks/:stack/stages/:stage/resources",
+  {
+    params: StackStage,
+    success: Schema.Array(Schema.String),
+  },
+);
+
+export const GetState = HttpApiEndpoint.get(
+  "getState",
+  "/state/stacks/:stack/stages/:stage/resources/:fqn",
+  {
+    params: ResourceKey,
+    success: Schema.UndefinedOr(ResourceStateSchema),
+  },
+);
+
+export const SetState = HttpApiEndpoint.put(
+  "setState",
+  "/state/stacks/:stack/stages/:stage/resources/:fqn",
+  {
+    params: ResourceKey,
+    payload: ResourceStateSchema,
+    success: ResourceStateSchema,
+  },
+);
+
+export const DeleteState = HttpApiEndpoint.delete(
+  "deleteState",
+  "/state/stacks/:stack/stages/:stage/resources/:fqn",
+  {
+    params: ResourceKey,
+    success: HttpApiSchema.NoContent,
+  },
+);
+
+export const DeleteStack = HttpApiEndpoint.delete(
+  "deleteStack",
+  "/state/stacks/:stack",
+  {
+    params: StackParams,
+    query: OptionalStageQuery,
+    success: HttpApiSchema.NoContent,
+  },
+);
+
+export const GetReplacedResources = HttpApiEndpoint.get(
+  "getReplacedResources",
+  "/state/stacks/:stack/stages/:stage/replaced-resources",
+  {
+    params: StackStage,
+    success: Schema.Array(ResourceStateSchema),
+  },
+);
+
+export class StateGroup extends HttpApiGroup.make("state")
+  .add(ListStacks)
+  .add(ListStages)
+  .add(ListResources)
+  .add(GetState)
+  .add(SetState)
+  .add(DeleteState)
+  .add(GetReplacedResources)
+  .add(DeleteStack)
+  .middleware(StateAuth) {}
+
+export class StateApi extends HttpApi.make("alchemy-state").add(StateGroup) {}

package/src/State/HttpStateStore.ts

@@ -0,0 +1,156 @@
+import * as Effect from "effect/Effect";
+import * as Schedule from "effect/Schedule";
+import * as HttpClient from "effect/unstable/http/HttpClient";
+import * as HttpClientRequest from "effect/unstable/http/HttpClientRequest";
+import * as HttpApiClient from "effect/unstable/httpapi/HttpApiClient";
+import { StateApi } from "./HttpStateApi.ts";
+
+import type { ReplacedResourceState, ResourceState } from "./ResourceState.ts";
+import { StateStoreError, type StateService } from "./State.ts";
+import { encodeState, reviveStateRecursive } from "./StateEncoding.ts";
+
+export interface HttpStateStoreProps {
+  url: string;
+  /** Bearer token used to authenticate every request. */
+  authToken: string;
+}
+
+export const makeHttpStateStore = ({ url, authToken }: HttpStateStoreProps) =>
+  Effect.gen(function* () {
+    const apiClient = yield* HttpApiClient.make(StateApi, {
+      baseUrl: url,
+      transformClient: HttpClient.mapRequest(
+        HttpClientRequest.bearerToken(authToken),
+      ),
+    });
+    const state = apiClient.state;
+
+    const service: StateService = {
+      listStacks: () =>
+        state.listStacks().pipe(
+          Effect.map((stacks) => [...stacks]),
+          mapStateStoreError,
+        ),
+      listStages: (stack) =>
+        state.listStages({ params: { stack } }).pipe(mapStateStoreError),
+      list: (request) =>
+        state.listResources({ params: request }).pipe(mapStateStoreError),
+      get: (request) =>
+        state
+          .getState({
+            params: {
+              stack: request.stack,
+              stage: request.stage,
+              fqn: encodeURIComponent(request.fqn),
+            },
+          })
+          .pipe(
+            Effect.map((s) =>
+              s == null
+                ? undefined
+                : (reviveStateRecursive(s) as ResourceState),
+            ),
+            mapStateStoreError,
+          ),
+      getReplacedResources: (request) =>
+        state.getReplacedResources({ params: request }).pipe(
+          Effect.map((resources) =>
+            resources.map(
+              (s) => reviveStateRecursive(s) as ReplacedResourceState,
+            ),
+          ),
+          mapStateStoreError,
+        ),
+      set: <V extends ResourceState>(request: {
+        stack: string;
+        stage: string;
+        fqn: string;
+        value: V;
+      }) =>
+        state
+          .setState({
+            params: {
+              stack: request.stack,
+              stage: request.stage,
+              fqn: encodeURIComponent(request.fqn),
+            },
+            payload: encodeState(request.value),
+          })
+          .pipe(
+            // Server echoes the stored value, but the client already
+            // has the canonical object (including any Redacted<T>
+            // instances); returning the input avoids a lossy round-trip.
+            Effect.map(() => request.value),
+            mapStateStoreError,
+          ),
+      delete: (request) =>
+        state
+          .deleteState({
+            params: {
+              stack: request.stack,
+              stage: request.stage,
+              fqn: encodeURIComponent(request.fqn),
+            },
+          })
+          .pipe(Effect.asVoid, mapStateStoreError),
+      deleteStack: (request) =>
+        state
+          .deleteStack({
+            params: { stack: request.stack },
+            query: request.stage === undefined ? {} : { stage: request.stage },
+          })
+          .pipe(Effect.asVoid, mapStateStoreError),
+    };
+    return service;
+  });
+
+/**
+ * Predicate over an `HttpClientError`-shaped failure that returns `true`
+ * for failures we expect to clear up on their own.
+ *
+ * We retry:
+ * - all transport-level errors (no `response` — DNS, TCP reset, TLS,
+ *   abort, etc.)
+ * - 408 (request timeout) and 429 (rate limit)
+ * - 404, which is normal in the seconds after a worker is first
+ *   deployed and the route hasn't propagated yet
+ * - every 5xx
+ *
+ * Anything else (400/401/403/etc.) is a real client-side problem and
+ * shouldn't be hidden behind retries.
+ */
+const isTransient = (e: any): boolean => {
+  if (e?._tag !== "HttpClientError") return false;
+  const status: number | undefined = e.response?.status;
+  if (status == null) return true;
+  if (status === 404 || status === 408 || status === 429) return true;
+  return status >= 500 && status < 600;
+};
+
+const retryTransient = <A, Err, Req>(eff: Effect.Effect<A, Err, Req>) =>
+  Effect.retry(eff, {
+    while: isTransient,
+    // Exponential backoff capped at 2s, no attempt limit. The state
+    // store is on the deploy critical path; we'd rather block than
+    // surface a transient blip as a hard failure (which historically
+    // stranded `syncState` mid-flight, leaving the remote store
+    // partially populated).
+    schedule: Schedule.exponential(100).pipe(
+      Schedule.either(Schedule.spaced("2 seconds")),
+    ),
+  });
+
+/** Collapse any client failure into a {@link StateStoreError}. */
+const mapStateStoreError = <A, E, R>(eff: Effect.Effect<A, E, R>) =>
+  eff.pipe(
+    Effect.tapError(Effect.log),
+    retryTransient,
+    Effect.catch((e: E) =>
+      Effect.fail(
+        new StateStoreError({
+          message: e instanceof Error ? e.message : String(e),
+          cause: e instanceof Error ? e : undefined,
+        }),
+      ),
+    ),
+  ) as Effect.Effect<A, StateStoreError, R>;

package/src/State/InMemoryState.ts

@@ -1,32 +1,23 @@
 import * as Effect from "effect/Effect";
 import * as Layer from "effect/Layer";
 import type { ResourceState } from "./ResourceState.ts";
-import { State, type StateService } from "./State.ts";
+import { State } from "./State.ts";
 
 type StackId = string;
 type StageId = string;
 type Fqn = string;
 
-export const InMemory = (
+export const inMemoryState = (
   initialState: Record<
     StackId,
     Record<StageId, Record<Fqn, ResourceState>>
   > = {},
-) =>
-  Layer.succeed(State, InMemoryService(initialState)) as Layer.Layer<
-    State,
-    never,
-    never
-  >;
+) => Layer.succeed(State, InMemoryService(initialState));
 
 export const InMemoryService = (
-  initialState: Record<
-    StackId,
-    Record<StageId, Record<Fqn, ResourceState>>
-  > = {},
-) => {
-  const state = initialState;
-  return {
+  state: Record<StackId, Record<StageId, Record<Fqn, ResourceState>>> = {},
+) =>
+  State.of({
     listStacks: () => Effect.succeed(Array.from(Object.keys(state))),
     listStages: (stack: string) =>
       Effect.succeed(
@@ -78,9 +69,16 @@ export const InMemoryService = (
       stage: string;
       fqn: string;
     }) => Effect.succeed(delete state[stack]?.[stage]?.[fqn]),
+    deleteStack: ({ stack, stage }: { stack: string; stage?: string }) =>
+      Effect.sync(() => {
+        if (stage === undefined) {
+          delete state[stack];
+        } else {
+          delete state[stack]?.[stage];
+        }
+      }),
     list: ({ stack, stage }: { stack: string; stage: string }) =>
       Effect.succeed(
         Array.from(Object.keys(state[stack]?.[stage] ?? {}) ?? []),
       ),
-  } satisfies StateService;
-};
+  });

package/src/State/LocalState.ts

@@ -3,53 +3,13 @@ import * as FileSystem from "effect/FileSystem";
 import * as Layer from "effect/Layer";
 import * as Path from "effect/Path";
 import type { PlatformError } from "effect/PlatformError";
-import * as Redacted from "effect/Redacted";
 import { decodeFqn, encodeFqn } from "../FQN.ts";
-import { isResource } from "../Resource.ts";
 import { State, StateStoreError, type StateService } from "./State.ts";
+import { encodeState, reviveState } from "./StateEncoding.ts";
 
-const REDACTED_MARKER = "__redacted__";
+export const localState = () => Layer.effect(State, makeLocalState());
 
-const encodeState = (value: unknown): unknown => {
-  if (value === null || value === undefined) return value;
-  if (Redacted.isRedacted(value)) {
-    return {
-      [REDACTED_MARKER]: encodeState(Redacted.value(value)),
-    };
-  }
-  if (isResource(value)) {
-    return {
-      id: value.LogicalId,
-      type: value.Type,
-      props: encodeState(value.Props),
-      attr: encodeState(value.Attributes),
-    };
-  }
-  if (Array.isArray(value)) return value.map(encodeState);
-  if (typeof value === "object") {
-    const result: Record<string, unknown> = {};
-    for (const [k, v] of Object.entries(value)) {
-      result[k] = encodeState(v);
-    }
-    return result;
-  }
-  return value;
-};
-
-const reviveState = (_key: string, value: unknown): unknown => {
-  if (
-    value !== null &&
-    typeof value === "object" &&
-    !Array.isArray(value) &&
-    REDACTED_MARKER in value
-  ) {
-    return Redacted.make((value as Record<string, unknown>)[REDACTED_MARKER]);
-  }
-  return value;
-};
-
-export const LocalState = Layer.effect(
-  State,
+export const makeLocalState = () =>
   Effect.gen(function* () {
     const fs = yield* FileSystem.FileSystem;
     const path = yield* Path.Path;
@@ -132,6 +92,15 @@ export const LocalState = Layer.effect(
           Effect.map(() => request.value),
         ),
       delete: (request) => fs.remove(resource(request)).pipe(recover),
+      deleteStack: ({ stack, stage }) =>
+        fs
+          .remove(
+            stage === undefined
+              ? path.join(stateDir, stack)
+              : stageDir({ stack, stage }),
+            { recursive: true },
+          )
+          .pipe(recover),
       list: (request) =>
         fs.readDirectory(stageDir(request)).pipe(
           recover,
@@ -143,5 +112,4 @@ export const LocalState = Layer.effect(
         ),
     };
     return state;
-  }),
-);
+  });

package/src/State/State.ts

@@ -9,7 +9,7 @@ export class StateStoreError extends Data.TaggedError("StateStoreError")<{
 }> {}
 
 export class State extends Context.Service<State, StateService>()(
-  "AWS::Lambda::State",
+  "alchemy/State",
 ) {}
 
 /**
@@ -21,8 +21,10 @@ export class State extends Context.Service<State, StateService>()(
  * for provider operations.
  */
 export interface StateService {
-  listStacks(): Effect.Effect<string[], StateStoreError, never>;
-  listStages(stack: string): Effect.Effect<string[], StateStoreError, never>;
+  listStacks(): Effect.Effect<readonly string[], StateStoreError, never>;
+  listStages(
+    stack: string,
+  ): Effect.Effect<readonly string[], StateStoreError, never>;
   /**
    * Get a resource by its FQN (namespace-qualified key).
    */
@@ -62,11 +64,18 @@ export interface StateService {
     stage: string;
     fqn: string;
   }): Effect.Effect<void, StateStoreError, never>;
+  /**
+   * Delete an entire stack, or a single stage when `stage` is provided.
+   */
+  deleteStack(request: {
+    stack: string;
+    stage?: string;
+  }): Effect.Effect<void, StateStoreError, never>;
   /**
    * List all resource FQNs in a stack/stage.
    */
   list(request: {
     stack: string;
     stage: string;
-  }): Effect.Effect<string[], StateStoreError, never>;
+  }): Effect.Effect<readonly string[], StateStoreError, never>;
 }

package/src/State/StateEncoding.ts

@@ -0,0 +1,83 @@
+import * as Redacted from "effect/Redacted";
+import { isResource } from "../Resource.ts";
+
+/**
+ * JSON marker used to tag a `Redacted<T>` value when writing state.
+ * The reviver recognises objects with exactly this key and rebuilds
+ * the `Redacted` wrapper on read.
+ */
+export const REDACTED_MARKER = "__redacted__";
+
+/**
+ * Recursively encode a state value for JSON serialisation.
+ *
+ * - `Redacted<T>` values are wrapped as `{ [REDACTED_MARKER]: <inner> }`
+ *   so the actual string is persisted rather than the `<redacted>`
+ *   placeholder produced by the default `toJSON`.
+ * - `Resource` instances are flattened to `{ id, type, props, attr }`
+ *   so persisted state matches the schema used by the loader.
+ * - Plain objects and arrays are walked structurally.
+ */
+export const encodeState = (value: unknown): unknown => {
+  if (value === null || value === undefined) return value;
+  if (Redacted.isRedacted(value)) {
+    return {
+      [REDACTED_MARKER]: encodeState(Redacted.value(value)),
+    };
+  }
+  if (isResource(value)) {
+    return {
+      id: value.LogicalId,
+      type: value.Type,
+      props: encodeState(value.Props),
+      attr: encodeState(value.Attributes),
+    };
+  }
+  if (Array.isArray(value)) return value.map(encodeState);
+  if (typeof value === "object") {
+    const result: Record<string, unknown> = {};
+    for (const [k, v] of Object.entries(value)) {
+      result[k] = encodeState(v);
+    }
+    return result;
+  }
+  return value;
+};
+
+/**
+ * JSON reviver that rebuilds `Redacted<T>` values that were written
+ * through {@link encodeState}. Intended for use with `JSON.parse`.
+ */
+export const reviveState = (_key: string, value: unknown): unknown => {
+  if (
+    value !== null &&
+    typeof value === "object" &&
+    !Array.isArray(value) &&
+    REDACTED_MARKER in value
+  ) {
+    return Redacted.make((value as Record<string, unknown>)[REDACTED_MARKER]);
+  }
+  return value;
+};
+
+/**
+ * Recursively walk an already-decoded value and rebuild `Redacted<T>`
+ * instances from `{ [REDACTED_MARKER]: <inner> }` envelopes. Mirror
+ * image of {@link encodeState} for callers that hold a parsed JS
+ * value rather than a JSON string (e.g. the HTTP state-store client,
+ * which receives values pre-parsed by `HttpApiClient`).
+ */
+export const reviveStateRecursive = (value: unknown): unknown => {
+  if (value === null || typeof value !== "object") return value;
+  if (Array.isArray(value)) return value.map(reviveStateRecursive);
+  const obj = value as Record<string, unknown>;
+  const keys = Object.keys(obj);
+  if (keys.length === 1 && keys[0] === REDACTED_MARKER) {
+    return Redacted.make(reviveStateRecursive(obj[REDACTED_MARKER]));
+  }
+  const result: Record<string, unknown> = {};
+  for (const [k, v] of Object.entries(obj)) {
+    result[k] = reviveStateRecursive(v);
+  }
+  return result;
+};

package/src/State/Sync.ts

@@ -0,0 +1,89 @@
+import * as Effect from "effect/Effect";
+import { type StateService } from "./State.ts";
+
+/**
+ * Synchronize all state (every stack/stage/resource) from `source` into
+ * `destination` so that `destination` becomes a mirror of `source`.
+ *
+ * For each `{ stack, stage, fqn }` present in `source`, the resource is
+ * written into `destination`, overwriting any existing entry under the same
+ * key. Any keys present in `destination` but absent from `source` are
+ * deleted, ensuring the two stores end up structurally identical.
+ *
+ * Stacks are walked sequentially; stages within a stack and resources
+ * within a stage are processed concurrently for throughput.
+ */
+export const syncState = Effect.fnUntraced(function* (
+  source: StateService,
+  destination: StateService,
+  options?: {
+    stacks?: string[];
+    /**
+     * Maximum number of resources to copy in parallel within a single stage.
+     * @default "unbounded".
+     */
+    concurrency?: number | "unbounded";
+  },
+) {
+  const concurrency = options?.concurrency ?? "unbounded";
+  const [sourceStacks, destStacks] = yield* Effect.all([
+    source.listStacks(),
+    destination.listStacks(),
+  ]);
+  const sourceStackSet = new Set(
+    sourceStacks.filter((stack) => options?.stacks?.includes(stack) ?? true),
+  );
+
+  yield* Effect.forEach(
+    sourceStacks,
+    Effect.fnUntraced(function* (stack) {
+      const [sourceStages, destStages] = yield* Effect.all([
+        source.listStages(stack),
+        destination.listStages(stack),
+      ]);
+      const stages = union(sourceStages, destStages);
+
+      yield* Effect.forEach(
+        stages,
+        Effect.fnUntraced(function* (stage) {
+          const sourceFqns = yield* source.list({ stack, stage });
+          const destFqns = yield* destination.list({ stack, stage });
+
+          const sourceSet = new Set(sourceFqns);
+          const toDelete = destFqns.filter((fqn) => !sourceSet.has(fqn));
+
+          yield* Effect.all(
+            [
+              Effect.forEach(
+                sourceFqns,
+                Effect.fnUntraced(function* (fqn) {
+                  const value = yield* source.get({ stack, stage, fqn });
+                  if (value) {
+                    yield* destination.set({ stack, stage, fqn, value });
+                  }
+                }),
+                { concurrency },
+              ),
+              Effect.forEach(
+                toDelete,
+                (fqn) => destination.delete({ stack, stage, fqn }),
+                { concurrency },
+              ),
+            ],
+            { concurrency: "unbounded" },
+          );
+        }),
+        { concurrency: "unbounded" },
+      );
+    }),
+  );
+
+  yield* Effect.forEach(
+    destStacks.filter((stack) => !sourceStackSet.has(stack)),
+    (stack) => destination.deleteStack({ stack }),
+  );
+});
+
+const union = <T>(left: Iterable<T>, right: Iterable<T>) => [
+  ...new Set([...left, ...right]),
+];

package/src/State/index.ts

@@ -1,4 +1,8 @@
+export * from "./HttpStateApi.ts";
+export * from "./HttpStateStore.ts";
 export * from "./InMemoryState.ts";
 export * from "./LocalState.ts";
 export * from "./ResourceState.ts";
 export * from "./State.ts";
+export * from "./StateEncoding.ts";
+export * from "./Sync.ts";