The best way to control Claude Code, Codex and more from any computer or phone
Mirrored from https://github.com/Camo67/t3code.git
Synced Nov 21, 04:45 UTC
| 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); |