The best way to control Claude Code, Codex and more from any computer or phone

main
ts 118 lines 4.03 KB
Raw
1 import { dynamoDBState, type DynamoDBStateOptions } from "./DynamoDBState.ts";
2 import { s3State, type S3StateOptions } from "./State.ts";
3
4 export interface StateOptions extends DynamoDBStateOptions {
5 /**
6 * The store to keep state in. `"dynamodb"` keeps it in a DynamoDB table;
7 * `"s3"` keeps it in the S3 bucket earlier versions used. Passing
8 * {@link StateOptions.bucketName}, {@link StateOptions.prefix} or
9 * {@link StateOptions.encryption} without a backend selects `"s3"`.
10 *
11 * @default "dynamodb"
12 */
13 backend?: "dynamodb" | "s3";
14 /** With the S3 store: see {@link S3StateOptions.bucketName}. */
15 bucketName?: S3StateOptions["bucketName"];
16 /** With the S3 store: see {@link S3StateOptions.prefix}. */
17 prefix?: S3StateOptions["prefix"];
18 /** With the S3 store: see {@link S3StateOptions.encryption}. */
19 encryption?: S3StateOptions["encryption"];
20 }
21
22 /** Options only the S3 store takes. A config that sets one keeps using it. */
23 const usesS3 = (options: StateOptions) =>
24 options.backend === "s3" ||
25 (options.backend === undefined &&
26 (options.bucketName !== undefined ||
27 options.prefix !== undefined ||
28 options.encryption !== undefined));
29
30 /**
31 * The AWS state store: one DynamoDB table per account and region,
32 * `alchemy-state`.
33 *
34 * A deploy loads a stage's state with one query and writes each change as
35 * it happens. Records too large for a DynamoDB item go to an S3 overflow
36 * bucket. Concurrent deploys of a stage fail fast on its lease instead of
37 * mixing writes.
38 *
39 * The table is created on first use, except in CI, where `alchemy state
40 * bootstrap --backend aws` provisions it ahead.
41 *
42 * ### Using the State Store
43 * **Example:** Default table
44 * ```typescript
45 * import * as Alchemy from "alchemy";
46 * import * as AWS from "@alchemy.run/aws";
47 *
48 * const Stack = Alchemy.Stack(
49 * "my-stack",
50 * { providers: AWS.providers(), state: AWS.state() },
51 * Effect.gen(function* () {
52 * // ...
53 * }),
54 * );
55 * ```
56 *
57 * **Example:** A separate, named store
58 * ```typescript
59 * const stateStore = AWS.state({ name: "team-a" }); // table alchemy-state-team-a
60 * ```
61 *
62 * ### Migrating from the S3 State Store
63 * Earlier versions kept state in an S3 bucket,
64 * `alchemy-state-<accountId>-<region>-an`. A stage still there is refused
65 * until it is moved. In the project, so the store the entrypoint
66 * configures is the one migrated:
67 *
68 * ```sh
69 * alchemy state migrate --profile <your-profile>
70 * ```
71 *
72 * The command moves every stage, or those `--stack` and `--stage` select.
73 * The bucket policy closes each moved stage's S3 objects, so every older
74 * alchemy fails at its first read instead of deploying from the old copy;
75 * the objects are kept. A stage another deploy holds is reported and
76 * skipped: run the command again once it finishes. `--rollback`, run with
77 * the same version, moves stages back to S3 before going back to an older
78 * one.
79 *
80 * ### Keeping State in S3
81 * **Example:** The S3 store
82 * ```typescript
83 * const stateStore = AWS.state({ backend: "s3" });
84 * ```
85 *
86 * **Example:** A custom bucket, prefix and KMS key
87 * ```typescript
88 * const stateStore = AWS.state({
89 * bucketName: "my-company-state-123456789012-us-east-1-an",
90 * prefix: "alchemy",
91 * encryption: { sseAlgorithm: "aws:kms", kmsMasterKeyId: "alias/alchemy-state" },
92 * });
93 * ```
94 *
95 * ### Supplying the AWS Environment
96 * The store resolves its account, region and credentials from the configured
97 * profile, CI credentials or the ambient AWS environment. Provide an
98 * `AWSEnvironment` to use another credential source, and the same layer to
99 * `AWS.providers()`.
100 *
101 * **Example:** Deploy-role credentials shared with the providers
102 * ```typescript
103 * const Stack = Alchemy.Stack(
104 * "my-stack",
105 * {
106 * providers: AWS.providers().pipe(Layer.provide(environment)),
107 * state: AWS.state().pipe(Layer.provide(environment)),
108 * },
109 * Effect.gen(function* () {
110 * // ...
111 * }),
112 * );
113 * ```
114 *
115 * @resource
116 */
117 export const state = (options: StateOptions = {}) =>
118 usesS3(options) ? s3State(options) : dynamoDBState(options);