The best way to control Claude Code, Codex and more from any computer or phone
| 1 | import type { Credentials } from "@distilled.cloud/aws/Credentials"; |
| 2 | import { Region } from "@distilled.cloud/aws/Region"; |
| 3 | import * as s3 from "@distilled.cloud/aws/s3"; |
| 4 | import * as Context from "effect/Context"; |
| 5 | import * as Data from "effect/Data"; |
| 6 | import * as Effect from "effect/Effect"; |
| 7 | import type { HttpClient } from "effect/http/HttpClient"; |
| 8 | import * as Layer from "effect/Layer"; |
| 9 | import * as Option from "effect/Option"; |
| 10 | import * as Schedule from "effect/Schedule"; |
| 11 | import * as Stream from "effect/Stream"; |
| 12 | import { AWSEnvironment } from "./Environment.ts"; |
| 13 | |
| 14 | /** |
| 15 | * Tag key used to identify the alchemy assets bucket. |
| 16 | */ |
| 17 | export const ASSETS_BUCKET_TAG = "alchemy::assets-bucket"; |
| 18 | |
| 19 | /** |
| 20 | * Error type for Assets service operations. |
| 21 | */ |
| 22 | export type AssetsError = |
| 23 | | { |
| 24 | readonly _tag: "AssetsUploadError"; |
| 25 | readonly message: string; |
| 26 | readonly cause?: unknown; |
| 27 | } |
| 28 | | { |
| 29 | readonly _tag: "AssetsCheckError"; |
| 30 | readonly message: string; |
| 31 | readonly cause?: unknown; |
| 32 | }; |
| 33 | |
| 34 | /** |
| 35 | * Requirements for Assets operations (S3 operations need these). |
| 36 | */ |
| 37 | export type AssetsRequirements = Region | Credentials | HttpClient | AWSEnvironment; |
| 38 | |
| 39 | export class Assets extends Context.Service< |
| 40 | Assets, |
| 41 | { |
| 42 | /** |
| 43 | * The name of the assets bucket. |
| 44 | */ |
| 45 | readonly bucketName: Effect.Effect<string, never, AssetsRequirements>; |
| 46 | |
| 47 | /** |
| 48 | * Upload an asset to the assets bucket. |
| 49 | * Uses content-addressed storage: `lambda/{hash}.zip` |
| 50 | * |
| 51 | * @param hash - The content hash of the asset |
| 52 | * @param content - The asset content (zip file) |
| 53 | * @returns The S3 key where the asset was uploaded |
| 54 | */ |
| 55 | readonly uploadAsset: ( |
| 56 | hash: string, |
| 57 | content: Uint8Array, |
| 58 | ) => Effect.Effect<string, AssetsError, AssetsRequirements>; |
| 59 | |
| 60 | /** |
| 61 | * Check if an asset already exists in the assets bucket. |
| 62 | * |
| 63 | * @param hash - The content hash to check |
| 64 | * @returns true if the asset exists |
| 65 | */ |
| 66 | readonly hasAsset: (hash: string) => Effect.Effect<boolean, AssetsError, AssetsRequirements>; |
| 67 | } |
| 68 | >()("AWS::Assets") { |
| 69 | static BucketName = Assets.use((assets) => assets.bucketName); |
| 70 | } |
| 71 | |
| 72 | /** |
| 73 | * Layer that provides the Assets service. |
| 74 | * Looks up the assets bucket on initialization. |
| 75 | * If the bucket doesn't exist, the layer will fail - use `assetsLayerWithFallback` for graceful fallback. |
| 76 | */ |
| 77 | export const AssetsLive = Layer.effect( |
| 78 | Assets, |
| 79 | Effect.gen(function* () { |
| 80 | const bucketName = yield* lookupAssetsBucket.pipe( |
| 81 | Effect.flatMap( |
| 82 | Option.match({ |
| 83 | onNone: () => |
| 84 | Effect.gen(function* () { |
| 85 | const environment = yield* AWSEnvironment.current; |
| 86 | if (!environment.endpoint) { |
| 87 | return yield* Effect.die( |
| 88 | new Error( |
| 89 | "Assets bucket not found. Run 'alchemy provider aws bootstrap' to create it.", |
| 90 | ), |
| 91 | ); |
| 92 | } |
| 93 | // Local emulator (floci/LocalStack): bootstrap transparently — |
| 94 | // the bucket is free, instant, and disposable with the emulator. |
| 95 | return yield* createAssetsBucket; |
| 96 | }), |
| 97 | onSome: (bucketName) => Effect.succeed(bucketName), |
| 98 | }), |
| 99 | ), |
| 100 | Effect.orDie, |
| 101 | Effect.cached, |
| 102 | ); |
| 103 | |
| 104 | const getLambdaAssetKey = (hash: string) => `lambda/${hash}.zip`; |
| 105 | |
| 106 | return { |
| 107 | bucketName, |
| 108 | uploadAsset: (hash: string, content: Uint8Array) => { |
| 109 | const key = getLambdaAssetKey(hash); |
| 110 | |
| 111 | return Effect.gen(function* () { |
| 112 | // Check if asset already exists |
| 113 | const exists = yield* s3.headObject({ Bucket: yield* bucketName, Key: key }).pipe( |
| 114 | Effect.map(() => true), |
| 115 | Effect.catchTag("NotFound", () => Effect.succeed(false)), |
| 116 | ); |
| 117 | |
| 118 | if (exists) { |
| 119 | yield* Effect.logDebug(`Asset already exists: s3://${yield* bucketName}/${key}`); |
| 120 | return key; |
| 121 | } |
| 122 | |
| 123 | // Upload the asset |
| 124 | yield* s3.putObject({ |
| 125 | Bucket: yield* bucketName, |
| 126 | Key: key, |
| 127 | Body: content, |
| 128 | ContentType: "application/zip", |
| 129 | }); |
| 130 | |
| 131 | yield* Effect.logDebug(`Uploaded asset: s3://${yield* bucketName}/${key}`); |
| 132 | return key; |
| 133 | }).pipe( |
| 134 | Effect.mapError((err): AssetsError => ({ |
| 135 | _tag: "AssetsUploadError", |
| 136 | message: `Failed to upload asset ${key}`, |
| 137 | cause: err, |
| 138 | })), |
| 139 | ); |
| 140 | }, |
| 141 | hasAsset: Effect.fn(function* (hash: string) { |
| 142 | const key = getLambdaAssetKey(hash); |
| 143 | |
| 144 | return yield* s3.headObject({ Bucket: yield* bucketName, Key: key }).pipe( |
| 145 | Effect.map(() => true), |
| 146 | Effect.catchTag("NotFound", () => Effect.succeed(false)), |
| 147 | Effect.mapError((err): AssetsError => ({ |
| 148 | _tag: "AssetsCheckError", |
| 149 | message: `Failed to check asset ${key}`, |
| 150 | cause: err, |
| 151 | })), |
| 152 | ); |
| 153 | }), |
| 154 | }; |
| 155 | }), |
| 156 | ); |
| 157 | |
| 158 | export const lookupAssetsBuckets = Effect.gen(function* () { |
| 159 | const { region } = yield* AWSEnvironment.current; |
| 160 | |
| 161 | return yield* s3.listBuckets |
| 162 | .pages({ |
| 163 | Prefix: "alchemy-assets-", |
| 164 | BucketRegion: region, |
| 165 | }) |
| 166 | .pipe( |
| 167 | Stream.flatMap((page) => Stream.fromIterable(page.Buckets ?? [])), |
| 168 | Stream.filterEffect((bucket) => |
| 169 | bucket.Name === undefined |
| 170 | ? Effect.succeed(false) |
| 171 | : getBucketTags(bucket.Name).pipe( |
| 172 | Effect.map((tags) => hasAssetsBucketTag(tags)), |
| 173 | Effect.orElseSucceed(() => false), |
| 174 | ), |
| 175 | ), |
| 176 | Stream.map((bucket) => bucket.Name!), |
| 177 | Stream.runCollect, |
| 178 | ); |
| 179 | }); |
| 180 | |
| 181 | export const lookupAssetsBucket = Effect.gen(function* () { |
| 182 | const matchingBuckets = yield* lookupAssetsBuckets; |
| 183 | for (const bucketName of matchingBuckets) { |
| 184 | return Option.some(bucketName); |
| 185 | } |
| 186 | return Option.none<string>(); |
| 187 | }); |
| 188 | |
| 189 | const hasAssetsBucketTag = (tags: Array<{ Key?: string; Value?: string }>) => |
| 190 | tags.some((tag) => tag.Key === ASSETS_BUCKET_TAG && tag.Value === "true"); |
| 191 | |
| 192 | /** |
| 193 | * Build an account-regional namespace bucket name. |
| 194 | * |
| 195 | * Account-regional buckets must follow the naming convention: |
| 196 | * `<prefix>-<accountId>-<region>-an` |
| 197 | * |
| 198 | * @see https://docs.aws.amazon.com/AmazonS3/latest/userguide/gpbucketnamespaces.html#account-regional-gp-buckets |
| 199 | */ |
| 200 | export const createAssetsBucketName = (accountId: string, region: string) => |
| 201 | `alchemy-assets-${accountId}-${region}-an`.toLowerCase(); |
| 202 | |
| 203 | const getBucketTags = (bucketName: string) => |
| 204 | s3.getBucketTagging({ Bucket: bucketName }).pipe( |
| 205 | Effect.map((response) => response.TagSet ?? []), |
| 206 | Effect.catchTag("NoSuchTagSet", () => |
| 207 | Effect.succeed<Array<{ Key?: string; Value?: string }>>([]), |
| 208 | ), |
| 209 | ); |
| 210 | |
| 211 | /** |
| 212 | * Create the tagged assets bucket for the current account+region and wait for |
| 213 | * it to be addressable. Idempotent — used by `alchemy provider aws bootstrap` and by |
| 214 | * the transparent local-emulator bootstrap in {@link AssetsLive}. |
| 215 | */ |
| 216 | export const createAssetsBucket = Effect.gen(function* () { |
| 217 | const { accountId, region } = yield* AWSEnvironment.current; |
| 218 | const bucketName = createAssetsBucketName(accountId, region); |
| 219 | yield* s3 |
| 220 | .createBucket({ |
| 221 | Bucket: bucketName, |
| 222 | BucketNamespace: "account-regional", |
| 223 | CreateBucketConfiguration: { |
| 224 | Tags: [{ Key: ASSETS_BUCKET_TAG, Value: "true" }], |
| 225 | ...(region === "us-east-1" |
| 226 | ? {} |
| 227 | : { |
| 228 | LocationConstraint: region as s3.BucketLocationConstraint, |
| 229 | }), |
| 230 | }, |
| 231 | }) |
| 232 | .pipe( |
| 233 | Effect.catchTag("BucketAlreadyOwnedByYou", () => Effect.void), |
| 234 | Effect.retry({ |
| 235 | while: (e): boolean => e._tag === "OperationAborted" || e._tag === "ServiceUnavailable", |
| 236 | schedule: Schedule.exponential(100), |
| 237 | }), |
| 238 | ); |
| 239 | |
| 240 | yield* s3.headBucket({ Bucket: bucketName }).pipe( |
| 241 | Effect.retry({ |
| 242 | schedule: Schedule.max([Schedule.exponential(100), Schedule.recurs(10)]), |
| 243 | }), |
| 244 | ); |
| 245 | |
| 246 | yield* Effect.logInfo(`Created assets bucket: ${bucketName}`); |
| 247 | return bucketName; |
| 248 | }); |
| 249 | |
| 250 | export const ensureAssetsBucketTags = Effect.fn(function* (bucketName: string) { |
| 251 | const existingTags = yield* getBucketTags(bucketName); |
| 252 | const tagSet = [ |
| 253 | ...existingTags.filter((tag) => tag.Key !== ASSETS_BUCKET_TAG), |
| 254 | { Key: ASSETS_BUCKET_TAG, Value: "true" }, |
| 255 | ]; |
| 256 | |
| 257 | yield* s3.putBucketTagging({ |
| 258 | Bucket: bucketName, |
| 259 | Tagging: { |
| 260 | TagSet: tagSet.map((tag) => ({ |
| 261 | Key: tag.Key!, |
| 262 | Value: tag.Value!, |
| 263 | })), |
| 264 | }, |
| 265 | }); |
| 266 | }); |
| 267 | |
| 268 | /** The assets bucket carries a bucket policy that is not valid JSON. */ |
| 269 | export class AssetsBucketPolicyInvalid extends Data.TaggedError("AssetsBucketPolicyInvalid")<{ |
| 270 | bucketName: string; |
| 271 | message: string; |
| 272 | }> {} |
| 273 | |
| 274 | /** |
| 275 | * Policy statement id granting Lambda read access to Web Function code. |
| 276 | */ |
| 277 | export const LAMBDA_WEB_CODE_ACCESS_SID = "AlchemyLambdaWebFunctionCode"; |
| 278 | |
| 279 | /** |
| 280 | * Prepare the assets bucket to serve `AWS.Lambda.WebFunction` code. Lambda |
| 281 | * reads a Web Function's deployment package from S3 itself, pinned to an |
| 282 | * object version, so the bucket needs versioning and a bucket policy that |
| 283 | * lets the Lambda service principal read `lambda/*` for this account's Web |
| 284 | * Function revisions. Both are observed first and only written when |
| 285 | * missing, so concurrent deploys converge on the same configuration. |
| 286 | */ |
| 287 | export const ensureLambdaWebCodeAccess = Effect.fn(function* (bucketName: string) { |
| 288 | const { accountId } = yield* AWSEnvironment.current; |
| 289 | |
| 290 | const versioning = yield* s3.getBucketVersioning({ Bucket: bucketName }); |
| 291 | if (versioning.Status !== "Enabled") { |
| 292 | yield* s3.putBucketVersioning({ |
| 293 | Bucket: bucketName, |
| 294 | VersioningConfiguration: { Status: "Enabled" }, |
| 295 | }); |
| 296 | } |
| 297 | |
| 298 | const statement = { |
| 299 | Sid: LAMBDA_WEB_CODE_ACCESS_SID, |
| 300 | Effect: "Allow", |
| 301 | Principal: { Service: "lambda.amazonaws.com" }, |
| 302 | Action: ["s3:GetObject", "s3:GetObjectVersion"], |
| 303 | Resource: `arn:aws:s3:::${bucketName}/lambda/*`, |
| 304 | Condition: { |
| 305 | StringEquals: { "aws:SourceAccount": accountId }, |
| 306 | ArnLike: { "aws:SourceArn": `arn:aws:lambda:*:${accountId}:web-function/*/revision/*` }, |
| 307 | }, |
| 308 | }; |
| 309 | const observed = yield* s3.getBucketPolicy({ Bucket: bucketName }).pipe( |
| 310 | Effect.map((response) => response.Policy), |
| 311 | Effect.catchTag("NoSuchBucketPolicy", () => Effect.undefined), |
| 312 | Effect.flatMap((policy) => |
| 313 | policy === undefined |
| 314 | ? Effect.undefined |
| 315 | : Effect.try({ |
| 316 | try: () => JSON.parse(policy) as { Version?: string; Statement?: unknown[] }, |
| 317 | catch: (cause) => new AssetsBucketPolicyInvalid({ bucketName, message: String(cause) }), |
| 318 | }), |
| 319 | ), |
| 320 | ); |
| 321 | const statements = (observed?.Statement ?? []) as Array<{ Sid?: string }>; |
| 322 | const existing = statements.find((s) => s.Sid === LAMBDA_WEB_CODE_ACCESS_SID); |
| 323 | if (existing !== undefined && JSON.stringify(existing) === JSON.stringify(statement)) { |
| 324 | return; |
| 325 | } |
| 326 | yield* s3.putBucketPolicy({ |
| 327 | Bucket: bucketName, |
| 328 | Policy: JSON.stringify({ |
| 329 | Version: observed?.Version ?? "2012-10-17", |
| 330 | Statement: [...statements.filter((s) => s.Sid !== LAMBDA_WEB_CODE_ACCESS_SID), statement], |
| 331 | }), |
| 332 | }); |
| 333 | }); |