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

main
ts 333 lines 10.9 KB
Raw
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 });