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

main
ts 489 lines 15.8 KB
Raw
1 import { createHash } from "node:crypto";
2 import * as s3 from "@distilled.cloud/aws/s3";
3 import * as Provider from "alchemy/Provider";
4 import { Resource } from "alchemy/Resource";
5 import { initialCwd } from "alchemy/Util/Node";
6 import * as Duration from "effect/Duration";
7 import * as Effect from "effect/Effect";
8 import * as FileSystem from "effect/FileSystem";
9 import * as Path from "effect/Path";
10 import * as Schedule from "effect/Schedule";
11 import * as Stream from "effect/Stream";
12 import type { Providers } from "../Providers.ts";
13 import type { WebsiteTextEncoding } from "./shared.ts";
14
15 export interface AssetFileOption {
16 /**
17 * Glob or globs of files to match.
18 */
19 files: string | string[];
20 /**
21 * Override `Content-Type` for matched files.
22 */
23 contentType?: string;
24 /**
25 * Override `Cache-Control` for matched files.
26 */
27 cacheControl?: string;
28 /**
29 * Optional glob or globs excluded from this rule.
30 */
31 ignore?: string | string[];
32 }
33
34 export interface AssetDeploymentProps {
35 /**
36 * Destination bucket.
37 */
38 bucket: {
39 bucketName: string;
40 };
41 /**
42 * Local directory to upload.
43 */
44 sourcePath: string;
45 /**
46 * Optional key prefix within the bucket.
47 */
48 prefix?: string;
49 /**
50 * Remove old files under the prefix that are not part of the current deploy.
51 * @default false
52 */
53 purge?: boolean;
54 /**
55 * Optional per-file overrides.
56 */
57 fileOptions?: AssetFileOption[];
58 /**
59 * Character encoding applied to inferred text-based asset content types.
60 * @default "utf-8"
61 */
62 textEncoding?: WebsiteTextEncoding;
63 }
64
65 export interface AssetDeployment extends Resource<
66 "AWS.Website.AssetDeployment",
67 AssetDeploymentProps,
68 {
69 /**
70 * Name of the destination bucket.
71 */
72 bucketName: string;
73 /**
74 * Normalized key prefix the files were uploaded under (empty string when
75 * no prefix was configured).
76 */
77 prefix: string;
78 /**
79 * Content hash of the uploaded file set — changes whenever any file body,
80 * content type, or cache-control changes. Useful as an invalidation token.
81 */
82 version: string;
83 /**
84 * Number of files uploaded in this deployment.
85 */
86 fileCount: number;
87 /**
88 * POSIX-relative paths of every uploaded file (before the `prefix` is
89 * applied), sorted. Downstream consumers derive routing manifests from
90 * this list (e.g. `StaticSite`'s CloudFront KV file manifest), so the
91 * manifest always reflects exactly what was uploaded.
92 */
93 files: string[];
94 /**
95 * MD5 of each uploaded file's object in the bucket, keyed by its path in
96 * `files` (absent when the object is missing), as observed. Lets
97 * `alchemy drift` detect out-of-band edits and deletions.
98 */
99 objectHashes?: Record<string, string>;
100 /**
101 * With `purge`, the keys under the prefix that are not part of the
102 * deployment, as observed. Lets `alchemy drift` detect objects added
103 * out of band.
104 */
105 strayKeys?: string[];
106 },
107 never,
108 Providers
109 > {}
110
111 /**
112 * Upload a local directory into S3 with website-friendly defaults.
113 *
114 * `AssetDeployment` is a helper resource for website hosting. It uploads all
115 * files in a directory, infers content types, applies cache-control defaults
116 * (HTML is never cached; everything else is immutable), and can optionally
117 * purge stale files under a prefix. `StaticSite` and `SsrSite` use it
118 * internally — reach for it directly when you manage the bucket and CDN
119 * yourself.
120 * ### Deploying Files
121 * **Example:** Upload A Build Directory
122 * ```typescript
123 * const bucket = yield* AWS.S3.Bucket("SiteBucket", {});
124 *
125 * const files = yield* AssetDeployment("WebsiteFiles", {
126 * bucket,
127 * sourcePath: "./dist",
128 * prefix: "_assets",
129 * });
130 * ```
131 *
132 * **Example:** Purge Stale Files And Override Caching
133 * ```typescript
134 * const files = yield* AssetDeployment("WebsiteFiles", {
135 * bucket,
136 * sourcePath: "./dist",
137 * purge: true,
138 * fileOptions: [
139 * {
140 * files: "**\/*.json",
141 * cacheControl: "max-age=300,public",
142 * },
143 * ],
144 * });
145 * ```
146 *
147 * ### Invalidation
148 * **Example:** Invalidate CloudFront On Content Change
149 * ```typescript
150 * const files = yield* AssetDeployment("WebsiteFiles", {
151 * bucket,
152 * sourcePath: "./dist",
153 * });
154 *
155 * // `version` only changes when file contents change, so the
156 * // invalidation re-runs exactly when a new deploy ships new bytes.
157 * yield* AWS.CloudFront.Invalidation("Invalidation", {
158 * distributionId: distribution.distributionId,
159 * version: files.version,
160 * paths: ["/*"],
161 * });
162 * ```
163 *
164 * @resource
165 */
166 export const AssetDeployment = Resource<AssetDeployment>("AWS.Website.AssetDeployment");
167
168 const defaultHtmlCacheControl = "max-age=0,no-cache,no-store,must-revalidate";
169 const defaultAssetCacheControl = "max-age=31536000,public,immutable";
170
171 export const AssetDeploymentProvider = () =>
172 Provider.effect(
173 AssetDeployment,
174 Effect.gen(function* () {
175 const reconcileSync = Effect.fn(function* (news: AssetDeploymentProps) {
176 const fs = yield* FileSystem.FileSystem;
177 const path = yield* Path.Path;
178 const bucketName = news.bucket.bucketName;
179 const prefix = normalizePrefix(news.prefix);
180 // Resolve against the process's INITIAL cwd, never the live cwd:
181 // Server persists build dirs relative to initialCwd, and a sibling
182 // framework build may transiently chdir this shared process while
183 // the upload walks the tree.
184 const root = path.resolve(initialCwd, news.sourcePath);
185 const files = yield* walkFiles(root);
186 const observed = yield* listObjects(bucketName, prefix ? `${prefix}/` : prefix);
187 const prepared = yield* Effect.forEach(
188 files,
189 (relativePath) =>
190 Effect.gen(function* () {
191 const body = yield* fs.readFile(path.join(root, relativePath));
192 const normalizedRelativePath = toPosix(relativePath);
193 const key = prefix ? `${prefix}/${normalizedRelativePath}` : normalizedRelativePath;
194 const options = getFileOptions(
195 normalizedRelativePath,
196 news.fileOptions,
197 news.textEncoding,
198 );
199 return {
200 relative: normalizedRelativePath,
201 key,
202 body,
203 contentType: options.contentType,
204 cacheControl: options.cacheControl,
205 };
206 }),
207 { concurrency: "unbounded" },
208 );
209 const version = yield* Effect.sync(() => {
210 const hash = createHash("sha256");
211 for (const file of prepared) {
212 hash.update(file.relative);
213 hash.update(file.body);
214 hash.update(file.contentType);
215 hash.update(file.cacheControl);
216 }
217 return hash.digest("hex");
218 });
219 const desiredKeys = new Set(prepared.map((file) => file.key));
220 const objectHashes = yield* Effect.sync(() =>
221 Object.fromEntries(
222 prepared.map((file) => [
223 file.relative,
224 createHash("md5").update(file.body).digest("hex"),
225 ]),
226 ),
227 );
228 yield* Effect.all(
229 prepared.flatMap((file) => {
230 const expectedETag = objectHashes[file.relative];
231 const observedETag = observed.get(file.key)?.replace(/^"|"$/g, "");
232 if (observedETag === expectedETag) return [];
233 return [
234 s3.putObject({
235 Bucket: bucketName,
236 Key: file.key,
237 Body: file.body,
238 ContentType: file.contentType,
239 CacheControl: file.cacheControl,
240 }),
241 ];
242 }),
243 { concurrency: 16 },
244 );
245
246 if (news.purge ?? false) {
247 yield* deleteKeys(
248 bucketName,
249 [...observed.keys()].filter((key) => !desiredKeys.has(key)),
250 );
251 }
252
253 return {
254 bucketName,
255 prefix,
256 version,
257 fileCount: files.length,
258 files: prepared.map((file) => file.relative),
259 objectHashes,
260 strayKeys: news.purge ? [] : undefined,
261 };
262 });
263
264 return {
265 // Non-listable: an AssetDeployment is an action (uploading a local
266 // directory into a bucket under a prefix), keyed by {bucketName,
267 // prefix}, not a standalone cloud resource. There is no AWS API that
268 // enumerates "asset deployments" — the uploaded objects are plain S3
269 // objects owned by their bucket — so there is nothing to enumerate.
270 list: () => Effect.succeed([]),
271 // The uploaded objects are the managed state: report each file's
272 // live hash (and, with purge, any stray keys) so drift sees edits
273 // and deletions made in the bucket.
274 read: Effect.fn(function* ({ olds, output }) {
275 if (output === undefined) return undefined;
276 const prefix = output.prefix ? `${output.prefix}/` : output.prefix;
277 const observed = yield* listObjects(output.bucketName, prefix).pipe(
278 Effect.catchTag("NoSuchBucket", () => Effect.undefined),
279 );
280 if (observed === undefined) return undefined;
281 const keyOf = (file: string) => (output.prefix ? `${output.prefix}/${file}` : file);
282 const objectHashes: Record<string, string> = {};
283 for (const file of output.files) {
284 const etag = observed.get(keyOf(file))?.replace(/^"|"$/g, "");
285 if (etag !== undefined) objectHashes[file] = etag;
286 }
287 const desiredKeys = new Set(output.files.map(keyOf));
288 return {
289 ...output,
290 objectHashes,
291 strayKeys: olds?.purge
292 ? [...observed.keys()].filter((key) => !desiredKeys.has(key)).sort()
293 : undefined,
294 };
295 }),
296 reconcile: Effect.fn(function* ({ news, session }) {
297 const output = yield* retryForBucketReadiness(reconcileSync(news));
298 yield* session.note(
299 `Uploaded ${output.fileCount} file(s) to s3://${output.bucketName}/${output.prefix}`,
300 );
301 return output;
302 }),
303 delete: Effect.fn(function* ({ olds, output }) {
304 if (!(olds.purge ?? false)) {
305 return;
306 }
307 const prefix = output.prefix ? `${output.prefix}/` : output.prefix;
308 yield* retryForBucketReadiness(
309 Effect.gen(function* () {
310 const existingKeys = yield* listKeys(output.bucketName, prefix);
311 yield* deleteKeys(output.bucketName, existingKeys);
312 }),
313 ).pipe(Effect.catchTag("NoSuchBucket", () => Effect.void));
314 }),
315 };
316 }),
317 );
318
319 const normalizePrefix = (prefix: string | undefined) =>
320 prefix ? prefix.replace(/^\/+|\/+$/g, "") : "";
321
322 const toPosix = (value: string) => value.replaceAll("\\", "/");
323
324 const extname = (file: string) => {
325 const base = toPosix(file).split("/").pop() ?? file;
326 const dot = base.lastIndexOf(".");
327 return dot > 0 ? base.slice(dot).toLowerCase() : "";
328 };
329
330 const withCharset = (mimeType: string, textEncoding: WebsiteTextEncoding) =>
331 textEncoding === "none" ? mimeType : `${mimeType}; charset=${textEncoding}`;
332
333 const inferContentType = (file: string, textEncoding: WebsiteTextEncoding = "utf-8") => {
334 const ext = extname(file);
335 switch (ext) {
336 case ".html":
337 return withCharset("text/html", textEncoding);
338 case ".css":
339 return withCharset("text/css", textEncoding);
340 case ".js":
341 case ".mjs":
342 return withCharset("application/javascript", textEncoding);
343 case ".json":
344 return withCharset("application/json", textEncoding);
345 case ".svg":
346 return "image/svg+xml";
347 case ".png":
348 return "image/png";
349 case ".jpg":
350 case ".jpeg":
351 return "image/jpeg";
352 case ".gif":
353 return "image/gif";
354 case ".webp":
355 return "image/webp";
356 case ".ico":
357 return "image/x-icon";
358 case ".txt":
359 return withCharset("text/plain", textEncoding);
360 case ".xml":
361 return withCharset("application/xml", textEncoding);
362 case ".woff":
363 return "font/woff";
364 case ".woff2":
365 return "font/woff2";
366 default:
367 return "application/octet-stream";
368 }
369 };
370
371 const defaultCacheControlFor = (file: string) =>
372 extname(file) === ".html" ? defaultHtmlCacheControl : defaultAssetCacheControl;
373
374 const escapeRegex = (value: string) => value.replace(/[|\\{}()[\]^$+?.]/g, "\\$&");
375
376 const globToRegExp = (glob: string) =>
377 new RegExp(
378 `^${escapeRegex(toPosix(glob))
379 .replace(/\\\*\\\*/g, ".*")
380 .replace(/\\\*/g, "[^/]*")
381 .replace(/\\\?/g, ".")}$`,
382 );
383
384 const matchesAny = (file: string, globs: string | string[]) =>
385 (Array.isArray(globs) ? globs : [globs]).some((glob) => globToRegExp(glob).test(file));
386
387 const getFileOptions = (
388 file: string,
389 options: AssetFileOption[] | undefined,
390 textEncoding: WebsiteTextEncoding | undefined,
391 ): {
392 contentType: string;
393 cacheControl: string;
394 } => {
395 const matched = [...(options ?? [])]
396 .reverse()
397 .find(
398 (option) =>
399 matchesAny(file, option.files) && !(option.ignore && matchesAny(file, option.ignore)),
400 );
401
402 return {
403 contentType: matched?.contentType ?? inferContentType(file, textEncoding ?? "utf-8"),
404 cacheControl: matched?.cacheControl ?? defaultCacheControlFor(file),
405 };
406 };
407
408 const walkFiles = Effect.fn(function* (root: string) {
409 const fs = yield* FileSystem.FileSystem;
410 const path = yield* Path.Path;
411 if (!(yield* fs.exists(root))) return [] as string[];
412 const names = yield* fs.readDirectory(root, { recursive: true });
413 const files = yield* Effect.forEach(
414 names,
415 (name) =>
416 Effect.gen(function* () {
417 const full = path.join(root, name);
418 const stat = yield* fs.stat(full);
419 return stat.type === "File" ? toPosix(name) : undefined;
420 }),
421 { concurrency: "unbounded" },
422 );
423 return files
424 .filter((name): name is string => name !== undefined)
425 .sort((a, b) => a.localeCompare(b));
426 });
427
428 const listObjectPages = (bucketName: string, prefix: string) =>
429 s3.listObjectsV2
430 .pages({
431 Bucket: bucketName,
432 Prefix: prefix || undefined,
433 })
434 .pipe(Stream.flatMap((page) => Stream.fromIterable(page.Contents ?? [])));
435
436 const listKeys = (bucketName: string, prefix: string) =>
437 listObjectPages(bucketName, prefix).pipe(
438 Stream.map((object) => object.Key),
439 Stream.filter((key): key is string => key !== undefined),
440 Stream.runCollect,
441 Effect.map((keys) => Array.from(keys)),
442 );
443
444 /** List `{key -> ETag}` pairs under `prefix`. ETag from S3 is wrapped in
445 * quotes; for non-multipart uploads it is the hex MD5 of the object body. */
446 const listObjects = (bucketName: string, prefix: string) =>
447 listObjectPages(bucketName, prefix).pipe(
448 Stream.runFold(
449 () => new Map<string, string>(),
450 (out, item) => {
451 if (item.Key && item.ETag) {
452 out.set(item.Key, item.ETag);
453 }
454 return out;
455 },
456 ),
457 );
458
459 const deleteKeys = Effect.fn(function* (bucketName: string, keys: string[]) {
460 for (let i = 0; i < keys.length; i += 1000) {
461 const batch = keys.slice(i, i + 1000);
462 if (batch.length === 0) {
463 continue;
464 }
465 yield* s3.deleteObjects({
466 Bucket: bucketName,
467 Delete: {
468 Objects: batch.map((Key) => ({ Key })),
469 Quiet: true,
470 },
471 });
472 }
473 });
474
475 const isMissingBucket = (error: unknown) => (error as { _tag?: string })._tag === "NoSuchBucket";
476
477 const retryForBucketReadiness = <A, E, R>(effect: Effect.Effect<A, E, R>) =>
478 effect.pipe(
479 Effect.retry({
480 while: isMissingBucket,
481 schedule: Schedule.max([Schedule.exponential("100 millis"), Schedule.recurs(30)]).pipe(
482 Schedule.modifyDelay(({ duration }) =>
483 Effect.succeed(
484 Duration.isGreaterThan(duration, Duration.seconds(2)) ? Duration.seconds(2) : duration,
485 ),
486 ),
487 ),
488 }),
489 );