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

main
ts 1,836 lines 65.8 KB
Raw
1 import * as r2 from "@distilled.cloud/cloudflare/r2";
2 import { deepEqual, isResolved } from "alchemy/Diff";
3 import * as ProviderLayer from "alchemy/Local/ProviderLayer";
4 import { createPhysicalName } from "alchemy/PhysicalName";
5 import * as Provider from "alchemy/Provider";
6 import { isResourceOfType, Resource } from "alchemy/Resource";
7 import * as Data from "effect/Data";
8 import * as Effect from "effect/Effect";
9 import * as Schedule from "effect/Schedule";
10 import * as Stream from "effect/Stream";
11 import { CloudflareEnvironment } from "../CloudflareEnvironment.ts";
12 import { localAccountId } from "../LocalAccount.ts";
13 import { generateLocalId } from "../LocalRuntime.ts";
14 import type * as Cloudflare from "../Providers.ts";
15 import * as Zone from "../Zone/index.ts";
16 import { abortMultipartUploads } from "./internal/MultipartUploads.ts";
17
18 export class BucketOperationFailed extends Data.TaggedError("BucketOperationFailed")<{
19 readonly message: string;
20 readonly cause?: unknown;
21 }> {}
22
23 export const isBucket = (value: any): value is Bucket =>
24 isResourceOfType(value, "Cloudflare.R2.Bucket");
25
26 export type BucketName = string;
27
28 export type BucketCustomDomainZone = Zone.Reference;
29
30 export type BucketCustomDomain = {
31 /**
32 * Custom domain name to attach to the bucket.
33 */
34 name: string;
35 /**
36 * Zone that contains the custom domain. If omitted, the zone is inferred
37 * from `domain`. Pass a zone ID string, a hostname in the zone, or any object
38 * with a `zoneId` attribute such as `Cloudflare.Zone.Zone`.
39 */
40 zone?: BucketCustomDomainZone;
41 /**
42 * Whether public bucket access is enabled at this custom domain.
43 * @default true
44 */
45 enabled?: boolean;
46 /**
47 * Allowlist of TLS ciphers in BoringSSL format.
48 */
49 ciphers?: string[];
50 /**
51 * Minimum TLS version accepted by the custom domain.
52 * @default "1.0"
53 */
54 minTLS?: "1.0" | "1.1" | "1.2" | "1.3";
55 };
56
57 export type BucketLifecycleCondition =
58 | {
59 type: "Age";
60 /**
61 * Maximum age of an object, in seconds, before the rule's action applies.
62 */
63 maxAge: number;
64 }
65 | {
66 type: "Date";
67 /**
68 * Absolute date (ISO 8601) at which the rule's action applies.
69 */
70 date: string;
71 };
72
73 export type BucketLifecycleRule = {
74 /**
75 * Unique identifier for the rule within the bucket.
76 */
77 id: string;
78 /**
79 * Whether the rule is enabled.
80 * @default true
81 */
82 enabled?: boolean;
83 /**
84 * Object key prefix the rule applies to. Use `""` (or omit) to match all
85 * objects in the bucket.
86 * @default ""
87 */
88 prefix?: string;
89 /**
90 * Abort incomplete multipart uploads after the configured age.
91 */
92 abortMultipartUploadsTransition?: {
93 condition?: { type: "Age"; maxAge: number };
94 };
95 /**
96 * Delete matching objects after the configured age or on a specific date.
97 */
98 deleteObjectsTransition?: {
99 condition?: BucketLifecycleCondition;
100 };
101 /**
102 * Transition matching objects to a different storage class. Cloudflare R2
103 * only supports transitioning to `InfrequentAccess` today.
104 */
105 storageClassTransitions?: {
106 condition: BucketLifecycleCondition;
107 storageClass: "InfrequentAccess";
108 }[];
109 };
110
111 export type BucketCorsRule = {
112 /**
113 * Optional label for this rule, shown in the Cloudflare dashboard. Not
114 * used to correlate rules across updates — the CORS configuration is
115 * always replaced as a whole.
116 */
117 id?: string;
118 /**
119 * HTTP methods browsers are allowed to use in cross-origin requests.
120 */
121 allowedMethods: ("GET" | "PUT" | "POST" | "DELETE" | "HEAD")[];
122 /**
123 * Origins allowed to make cross-origin requests, e.g.
124 * `"https://example.com"`. Use `"*"` to allow any origin.
125 */
126 allowedOrigins: string[];
127 /**
128 * Request headers browsers are allowed to send, e.g. `"range"` for
129 * range reads. If omitted, only simple headers are allowed.
130 */
131 allowedHeaders?: string[];
132 /**
133 * Response headers the browser is allowed to expose to the requesting
134 * JavaScript, e.g. `"etag"` or `"content-range"`.
135 */
136 exposeHeaders?: string[];
137 /**
138 * How long (in seconds) browsers may cache CORS preflight responses.
139 * Browsers may cap this at 2 hours or less, even if 86400 is specified.
140 */
141 maxAgeSeconds?: number;
142 };
143
144 export type BucketLockCondition =
145 | {
146 /**
147 * Lock matching objects permanently. They can never be deleted or
148 * overwritten, so the bucket can never be emptied or deleted.
149 */
150 type: "Indefinite";
151 }
152 | {
153 type: "Age";
154 /**
155 * Seconds after upload during which matching objects stay locked.
156 */
157 maxAgeSeconds: number;
158 }
159 | {
160 type: "Date";
161 /**
162 * Absolute date (ISO 8601) until which matching objects stay locked.
163 */
164 date: string;
165 };
166
167 export type BucketLockRule = {
168 /**
169 * Unique identifier for the rule within the bucket.
170 */
171 id: string;
172 /**
173 * Whether the rule is in effect.
174 */
175 enabled: boolean;
176 /**
177 * Object key prefix the rule applies to. Use `""` (or omit) to lock every
178 * object in the bucket.
179 * @default ""
180 */
181 prefix?: string;
182 /**
183 * How long matching objects stay locked.
184 */
185 condition: BucketLockCondition;
186 };
187
188 export type BucketProps = {
189 /**
190 * Name of the bucket. If omitted, a unique name will be generated.
191 * @default ${app}-${stage}-${id}
192 */
193 name?: string;
194 /**
195 * Storage class for newly uploaded objects.
196 * @default "Standard"
197 */
198 storageClass?: Bucket.StorageClass;
199 /**
200 * Jurisdiction where objects in this bucket are guaranteed to be stored:
201 * `"eu"` (the European Union), `"us"` (the United States), or `"fedramp"`
202 * (FedRAMP-compliant data centers). `"default"` places no restriction.
203 * Changing it replaces the bucket.
204 * @default "default"
205 */
206 jurisdiction?: Bucket.Jurisdiction;
207 /**
208 * Location hint for the bucket.
209 */
210 locationHint?: Bucket.Location;
211 /**
212 * Custom domains to attach to the bucket. Pass an empty array (or omit)
213 * to remove all custom domains.
214 */
215 domains?: BucketCustomDomain[];
216 /**
217 * Whether the bucket is publicly readable at Cloudflare's managed
218 * `r2.dev` domain. Cloudflare's default is off; omit or pass `false`
219 * to disable it.
220 *
221 * Once enabled, the hostname is reported on `publicDomain`. This
222 * endpoint is rate-limited and intended for non-production use — use
223 * `domains` for production public access.
224 *
225 * @default false
226 */
227 publicAccess?: boolean;
228 /**
229 * Object lifecycle rules applied to the bucket. Pass an empty array (or
230 * omit) to clear all lifecycle rules. See the Cloudflare R2 docs for
231 * supported transitions.
232 */
233 lifecycleRules?: BucketLifecycleRule[];
234 /**
235 * CORS rules applied to the bucket, controlling which cross-origin
236 * browser requests are allowed against the bucket's public or S3 API
237 * endpoints. Pass an empty array (or omit) to remove the CORS
238 * configuration.
239 */
240 cors?: BucketCorsRule[];
241 /**
242 * Object lock rules applied to the bucket. While a rule's condition
243 * holds, R2 refuses to delete or overwrite any object whose key matches
244 * the rule's prefix, whoever signs the request (S3 API credentials
245 * included). An `Indefinite` rule never lapses: matching objects are
246 * permanent and the bucket can never be emptied, so `forceDestroy`
247 * cannot delete it.
248 *
249 * A bucket that never declared `locks` keeps whatever rules it has: they
250 * are left unmanaged. Pass an empty array, or drop `locks` after
251 * declaring it, to remove every rule.
252 */
253 locks?: BucketLockRule[];
254 /**
255 * Whether R2 Local Uploads is enabled. Uploads from clients far from the
256 * bucket's region are written near the client first and replicated to the
257 * bucket asynchronously. Toggling it updates the bucket in place.
258 *
259 * Not available for jurisdiction-restricted buckets: enabling it on a
260 * bucket whose `jurisdiction` is not `"default"` fails the deploy.
261 *
262 * A bucket that never declared `localUploads` keeps whatever setting it
263 * has. Drop `localUploads` after declaring it to disable it.
264 */
265 localUploads?: boolean;
266 /**
267 * Allow alchemy to delete every object in the bucket when the bucket
268 * itself is deleted.
269 *
270 * R2 refuses to delete a bucket that still has objects in it — that
271 * refusal is the last line of defense for your data, so alchemy does not
272 * bypass it by default: destroying a non-empty bucket fails with
273 * `BucketNotEmpty` and both the bucket and its objects survive. Set this
274 * to `true` for buckets whose contents are disposable (caches, previews,
275 * test fixtures).
276 *
277 * Incomplete multipart uploads also hold a bucket. Only R2's S3 API can
278 * abort them, so alchemy aborts them only when it is authenticated with
279 * an API token that may write the bucket's objects (it never creates a
280 * token). Otherwise destroying fails with `BucketNotEmpty`: abort them,
281 * or add an `abortMultipartUploadsTransition` lifecycle rule, first.
282 *
283 * `alchemy unsafe nuke` empties buckets regardless, since it is an
284 * explicitly operator-confirmed account teardown.
285 *
286 * @default false
287 */
288 forceDestroy?: boolean;
289 };
290
291 export type Bucket = Resource<
292 "Cloudflare.R2.Bucket",
293 BucketProps,
294 {
295 bucketName: BucketName;
296 storageClass: Bucket.StorageClass;
297 jurisdiction: Bucket.Jurisdiction;
298 location: Bucket.Location | undefined;
299 accountId: string;
300 domains: Bucket.CustomDomain[];
301 lifecycleRules: Bucket.LifecycleRule[];
302 cors: Bucket.CorsRule[];
303 /**
304 * Lock rules on the bucket. `undefined` while `locks` is unmanaged
305 * (omitted from the props).
306 */
307 locks: Bucket.LockRule[] | undefined;
308 /**
309 * Whether Local Uploads is enabled. `undefined` while `localUploads` is
310 * unmanaged (omitted from the props).
311 */
312 localUploads: boolean | undefined;
313 /**
314 * Hostname of the bucket's Cloudflare-managed `r2.dev` domain.
315 * Set only while `publicAccess` is enabled; `undefined` when
316 * disabled (the domain still exists but serves 401).
317 */
318 publicDomain: string | undefined;
319 },
320 never,
321 Cloudflare.Providers
322 >;
323
324 /**
325 * A Cloudflare R2 object storage bucket with S3-compatible API.
326 *
327 * R2 provides zero-egress-fee object storage. Create a bucket as a resource,
328 * then bind it to a Worker to read and write objects at runtime.
329 * ### Creating a Bucket
330 * **Example:** Basic R2 bucket
331 * ```typescript
332 * const bucket = yield* Cloudflare.R2.Bucket("MyBucket");
333 * ```
334 *
335 * **Example:** Bucket with location hint
336 * ```typescript
337 * const bucket = yield* Cloudflare.R2.Bucket("MyBucket", {
338 * locationHint: "wnam",
339 * });
340 * ```
341 *
342 * ### Binding to a Worker
343 * **Example:** Reading and writing objects
344 * ```typescript
345 * const bucket = yield* Cloudflare.R2.ReadWriteBucket(MyBucket);
346 *
347 * // Write an object
348 * yield* bucket.put("hello.txt", "Hello, World!");
349 *
350 * // Read an object
351 * const object = yield* bucket.get("hello.txt");
352 * if (object) {
353 * const text = yield* object.text();
354 * }
355 * ```
356 *
357 * **Example:** Streaming upload with content length
358 * ```typescript
359 * const bucket = yield* Cloudflare.R2.ReadWriteBucket(MyBucket);
360 *
361 * yield* bucket.put("upload.bin", request.stream, {
362 * contentLength: Number(request.headers["content-length"] ?? 0),
363 * });
364 * ```
365 *
366 * ### Custom Domains
367 *
368 * Attach one or more custom domains to serve bucket objects from a hostname
369 * you control. The domain's zone must already exist in your Cloudflare
370 * account; the zone is inferred from the hostname when omitted, or you can
371 * pass a `Cloudflare.Zone.Zone` resource, a zone ID, or any hostname inside the
372 * zone via the `zone` field.
373 *
374 * **Example:** Single custom domain
375 * ```typescript
376 * const bucket = yield* Cloudflare.R2.Bucket("MyBucket", {
377 * domains: [{ name: "assets.example.com" }],
378 * });
379 * ```
380 *
381 * **Example:** Multiple custom domains
382 * ```typescript
383 * const bucket = yield* Cloudflare.R2.Bucket("MyBucket", {
384 * domains: [
385 * { name: "assets.example.com" },
386 * { name: "static.example.com" },
387 * ],
388 * });
389 * ```
390 *
391 * **Example:** Disable a custom domain without removing it
392 * ```typescript
393 * const bucket = yield* Cloudflare.R2.Bucket("MyBucket", {
394 * domains: [{ name: "assets.example.com", enabled: false }],
395 * });
396 * ```
397 *
398 * **Example:** Custom domain with explicit zone and TLS settings
399 * ```typescript
400 * const zone = yield* Cloudflare.Zone.Zone("ExampleZone", {
401 * name: "example.com",
402 * });
403 *
404 * const bucket = yield* Cloudflare.R2.Bucket("MyBucket", {
405 * domains: [
406 * {
407 * name: "assets.example.com",
408 * zone,
409 * minTLS: "1.2",
410 * },
411 * ],
412 * });
413 * ```
414 *
415 * ### Public Development URL
416 *
417 * Enable Cloudflare's managed `r2.dev` domain so objects are publicly
418 * readable without attaching a custom domain. The hostname is reported
419 * on `publicDomain`. This endpoint is rate-limited and intended for
420 * non-production use — use `domains` for production public access.
421 *
422 * **Example:** Enable public access at r2.dev
423 * ```typescript
424 * const bucket = yield* Cloudflare.R2.Bucket("MyBucket", {
425 * publicAccess: true,
426 * });
427 * // objects are at https://${bucket.publicDomain}/<key>
428 * ```
429 *
430 * **Example:** Disable public access
431 * ```typescript
432 * const bucket = yield* Cloudflare.R2.Bucket("MyBucket", {
433 * publicAccess: false,
434 * });
435 * ```
436 *
437 * ### Object Lifecycle Rules
438 *
439 * Configure lifecycle rules to automatically delete objects, abort
440 * incomplete multipart uploads, or transition objects to InfrequentAccess
441 * storage. Pass an empty array (or omit) to clear all rules. See the
442 * [Cloudflare R2 docs](https://developers.cloudflare.com/r2/buckets/object-lifecycles/)
443 * for details and limits (max 1000 rules per bucket).
444 *
445 * **Example:** Delete objects 30 days after upload
446 * ```typescript
447 * const bucket = yield* Cloudflare.R2.Bucket("MyBucket", {
448 * lifecycleRules: [
449 * {
450 * id: "expire-old-objects",
451 * deleteObjectsTransition: {
452 * condition: { type: "Age", maxAge: 60 * 60 * 24 * 30 },
453 * },
454 * },
455 * ],
456 * });
457 * ```
458 *
459 * **Example:** Transition to InfrequentAccess after 60 days, delete after 365
460 * ```typescript
461 * const bucket = yield* Cloudflare.R2.Bucket("MyBucket", {
462 * lifecycleRules: [
463 * {
464 * id: "archive-then-delete",
465 * prefix: "logs/",
466 * storageClassTransitions: [
467 * {
468 * condition: { type: "Age", maxAge: 60 * 60 * 24 * 60 },
469 * storageClass: "InfrequentAccess",
470 * },
471 * ],
472 * deleteObjectsTransition: {
473 * condition: { type: "Age", maxAge: 60 * 60 * 24 * 365 },
474 * },
475 * },
476 * ],
477 * });
478 * ```
479 *
480 * **Example:** Abort incomplete multipart uploads after 7 days
481 * ```typescript
482 * const bucket = yield* Cloudflare.R2.Bucket("MyBucket", {
483 * lifecycleRules: [
484 * {
485 * id: "abort-stale-uploads",
486 * abortMultipartUploadsTransition: {
487 * condition: { type: "Age", maxAge: 60 * 60 * 24 * 7 },
488 * },
489 * },
490 * ],
491 * });
492 * ```
493 *
494 * ### CORS
495 *
496 * Configure CORS rules so browsers can make cross-origin requests against
497 * the bucket's public (custom domain / r2.dev) or S3 API endpoints. Pass an
498 * empty array (or omit) to remove the CORS configuration. See the
499 * [Cloudflare R2 docs](https://developers.cloudflare.com/r2/buckets/cors/)
500 * for details.
501 *
502 * **Example:** Allow cross-origin reads from any origin
503 * ```typescript
504 * const bucket = yield* Cloudflare.R2.Bucket("MyBucket", {
505 * cors: [
506 * {
507 * allowedMethods: ["GET", "HEAD"],
508 * allowedOrigins: ["*"],
509 * },
510 * ],
511 * });
512 * ```
513 *
514 * **Example:** Browser range reads (e.g. PMTiles map tiles)
515 * ```typescript
516 * const bucket = yield* Cloudflare.R2.Bucket("MyBucket", {
517 * domains: [{ name: "tiles.example.com" }],
518 * cors: [
519 * {
520 * allowedMethods: ["GET", "HEAD"],
521 * allowedOrigins: ["https://map.example.com"],
522 * allowedHeaders: ["range", "if-match"],
523 * exposeHeaders: ["etag", "content-range"],
524 * maxAgeSeconds: 3600,
525 * },
526 * ],
527 * });
528 * ```
529 *
530 * **Example:** Allow uploads from a web app
531 * ```typescript
532 * const bucket = yield* Cloudflare.R2.Bucket("MyBucket", {
533 * cors: [
534 * {
535 * allowedMethods: ["GET", "PUT", "POST"],
536 * allowedOrigins: ["https://app.example.com"],
537 * allowedHeaders: ["content-type"],
538 * exposeHeaders: ["etag"],
539 * },
540 * ],
541 * });
542 * ```
543 *
544 * ### Bucket Locks
545 *
546 * Lock rules make objects write-once: while a rule's condition holds, R2
547 * refuses to delete or overwrite any object under the rule's prefix,
548 * whoever signs the request. `Indefinite` locks never lapse, so a bucket
549 * with indefinitely locked objects can never be emptied or deleted. A
550 * bucket that never declares `locks` keeps its rules unmanaged; pass an
551 * empty array (or drop `locks` after declaring it) to remove them. See the
552 * [Cloudflare R2 docs](https://developers.cloudflare.com/r2/buckets/bucket-locks/)
553 * for details.
554 *
555 * **Example:** Write-once landing zone
556 * ```typescript
557 * const lake = yield* Cloudflare.R2.Bucket("Lake", {
558 * locks: [
559 * {
560 * id: "raw-write-once",
561 * enabled: true,
562 * prefix: "raw/",
563 * condition: { type: "Indefinite" },
564 * },
565 * ],
566 * });
567 * ```
568 *
569 * **Example:** Retain logs for 90 days
570 * ```typescript
571 * const audit = yield* Cloudflare.R2.Bucket("Audit", {
572 * locks: [
573 * {
574 * id: "retain-logs",
575 * enabled: true,
576 * prefix: "logs/",
577 * condition: { type: "Age", maxAgeSeconds: 60 * 60 * 24 * 90 },
578 * },
579 * ],
580 * });
581 * ```
582 *
583 * ### Local Uploads
584 *
585 * Local Uploads writes uploaded objects near the client and replicates them
586 * to the bucket's region asynchronously, cutting upload latency for clients
587 * far from the bucket. It is not available for jurisdiction-restricted
588 * buckets. See the
589 * [Cloudflare R2 docs](https://developers.cloudflare.com/r2/buckets/local-uploads/)
590 * for details.
591 *
592 * **Example:** Enable Local Uploads
593 * ```typescript
594 * const uploads = yield* Cloudflare.R2.Bucket("Uploads", {
595 * localUploads: true,
596 * });
597 * ```
598 *
599 * ### Deleting a Bucket
600 *
601 * R2 refuses to delete a bucket that still has objects in it, and alchemy
602 * does not bypass that refusal: destroying a non-empty bucket fails with
603 * `BucketNotEmpty` and both the bucket and its objects survive. Opt into
604 * emptying the bucket first with `forceDestroy` for buckets whose contents
605 * are disposable.
606 *
607 * **Example:** Empty the bucket on destroy
608 * ```typescript
609 * const cache = yield* Cloudflare.R2.Bucket("Cache", {
610 * forceDestroy: true,
611 * });
612 * ```
613 *
614 * **Example:** Keep the bucket even when the stack goes away
615 * ```typescript
616 * import * as RemovalPolicy from "alchemy/RemovalPolicy";
617 *
618 * const uploads = yield* Cloudflare.R2.Bucket("Uploads").pipe(
619 * RemovalPolicy.retain(),
620 * );
621 * ```
622 *
623 * @resource
624 * @product R2
625 * @category Storage & Databases
626 */
627 export const Bucket = Resource<Bucket>("Cloudflare.R2.Bucket", {
628 aliases: ["Cloudflare.R2Bucket"],
629 });
630
631 export declare namespace Bucket {
632 export type StorageClass = "Standard" | "InfrequentAccess";
633 export type Jurisdiction = "default" | "eu" | "us" | "fedramp";
634 export type Location = "apac" | "eeur" | "enam" | "weur" | "wnam" | "oc";
635 export type LifecycleRule = {
636 id: string;
637 enabled: boolean;
638 prefix: string;
639 abortMultipartUploadsTransition:
640 | { condition: { type: "Age"; maxAge: number } | undefined }
641 | undefined;
642 deleteObjectsTransition: { condition: BucketLifecycleCondition | undefined } | undefined;
643 storageClassTransitions:
644 | {
645 condition: BucketLifecycleCondition;
646 storageClass: "InfrequentAccess";
647 }[]
648 | undefined;
649 };
650 export type CorsRule = {
651 id: string | undefined;
652 allowedMethods: ("GET" | "PUT" | "POST" | "DELETE" | "HEAD")[];
653 allowedOrigins: string[];
654 allowedHeaders: string[] | undefined;
655 exposeHeaders: string[] | undefined;
656 maxAgeSeconds: number | undefined;
657 };
658 export type LockRule = {
659 id: string;
660 enabled: boolean;
661 prefix: string;
662 condition: BucketLockCondition;
663 };
664 export type CustomDomain = {
665 domain: string;
666 zoneId: string | undefined;
667 enabled: boolean;
668 ciphers: string[] | undefined;
669 minTLS: "1.0" | "1.1" | "1.2" | "1.3" | undefined;
670 status:
671 | {
672 ownership: "pending" | "active" | "deactivated" | "blocked" | "error" | "unknown";
673 ssl: "initializing" | "pending" | "active" | "deactivated" | "error" | "unknown";
674 }
675 | undefined;
676 };
677 }
678
679 export const ProviderLive = () =>
680 Provider.effect(
681 Bucket,
682 Effect.gen(function* () {
683 const emptyBucket = Effect.fn(function* (
684 bucketName: string,
685 jurisdiction: Bucket.Jurisdiction,
686 ) {
687 const { accountId } = yield* yield* CloudflareEnvironment;
688 return yield* r2.listObjects
689 .items({
690 accountId,
691 bucketName,
692 cfR2Jurisdiction: jurisdiction,
693 perPage: 1000,
694 })
695 .pipe(
696 Stream.filter(
697 (o): o is typeof o & { key: string } => typeof o.key === "string" && o.key !== "",
698 ),
699 Stream.map((o) => o.key),
700 Stream.runForEachArray((chunk) =>
701 r2.deleteObjects({
702 accountId,
703 bucketName,
704 cfR2Jurisdiction: jurisdiction,
705 body: [...chunk],
706 }),
707 ),
708 Effect.catchTag("NoSuchBucket", () => Effect.void),
709 );
710 });
711
712 const createBucketName = (id: string, name: string | undefined) =>
713 Effect.gen(function* () {
714 if (name) return name;
715 return (yield* createPhysicalName({
716 id,
717 maxLength: 63,
718 })).toLowerCase();
719 });
720
721 const normalizeLocation = (
722 location: string | undefined | null,
723 ): Bucket.Location | undefined => {
724 if (!location) return undefined;
725 return location.toLowerCase() as Bucket.Location;
726 };
727
728 const listCustomDomains = Effect.fn(function* (
729 bucketName: string,
730 jurisdiction: Bucket.Jurisdiction,
731 // `NoSuchBucket` after a *create* is endpoint-consistency lag worth
732 // retrying. During *enumeration* (`list`), a bucket that 404s is one a
733 // parallel suite just deleted — it's genuinely gone, so retrying the
734 // consistency schedule only burns ~3s per churned bucket and is what
735 // pushes an account-wide `list` past its timeout. Default to retrying
736 // (the reconcile path); opt out for enumeration.
737 options?: { retryMissing?: boolean },
738 ) {
739 const { accountId } = yield* yield* CloudflareEnvironment;
740 const fetch = r2.listBucketDomainCustoms({
741 accountId,
742 bucketName,
743 jurisdiction,
744 });
745 return yield* (
746 options?.retryMissing === false
747 ? fetch
748 : fetch.pipe(
749 Effect.retry({
750 while: (e) => e._tag === "NoSuchBucket",
751 schedule: r2BucketEndpointConsistencySchedule,
752 }),
753 )
754 ).pipe(
755 Effect.map((response) => response.domains.map(toCustomDomainAttributes)),
756 Effect.catchTag("NoSuchBucket", () => Effect.undefined),
757 );
758 });
759
760 const reconcileCustomDomains = (
761 bucketName: string,
762 jurisdiction: Bucket.Jurisdiction,
763 desired: BucketCustomDomain[],
764 previous: Bucket.CustomDomain[],
765 ) =>
766 Effect.gen(function* () {
767 const { accountId } = yield* yield* CloudflareEnvironment;
768 const observed = yield* listCustomDomains(bucketName, jurisdiction);
769 if (!observed) {
770 return yield* new BucketOperationFailed({
771 message: `Cannot reconcile custom domains for missing R2 bucket "${bucketName}"`,
772 });
773 }
774 const observedByDomain = new Map(observed.map((domain) => [domain.domain, domain]));
775 const desiredDomains = new Set(desired.map((domain) => domain.name));
776
777 // Remove domains that are no longer desired. Domains that keep the
778 // same hostname but move zones are intentionally skipped here and
779 // handled in the per-domain flow below.
780 yield* Effect.forEach(
781 previous,
782 (previousDomain) =>
783 desiredDomains.has(previousDomain.domain)
784 ? Effect.void
785 : r2
786 .deleteBucketDomainCustom({
787 accountId,
788 bucketName,
789 domain: previousDomain.domain,
790 jurisdiction,
791 })
792 .pipe(Effect.catchTag(["DomainNotFound", "NoSuchBucket"], () => Effect.void)),
793 { concurrency: "unbounded" },
794 );
795
796 const applied = yield* Effect.forEach(
797 desired,
798 (domain) =>
799 Effect.gen(function* () {
800 const zoneId = yield* Zone.resolveZoneId({
801 accountId,
802 zone: domain.zone,
803 hostname: domain.name,
804 });
805 const observedDomain = observedByDomain.get(domain.name);
806
807 if (observedDomain && sameCustomDomainConfig(observedDomain, domain, zoneId)) {
808 return observedDomain;
809 }
810
811 if (observedDomain && observedDomain.zoneId !== zoneId) {
812 // Cloudflare does not mutate the zone for an existing custom
813 // domain. This is not a duplicate of the stale-domain prune
814 // above: the hostname is still desired, so that prune skips it
815 // and this branch deletes only to recreate it in the new zone.
816 yield* r2
817 .deleteBucketDomainCustom({
818 accountId,
819 bucketName,
820 domain: domain.name,
821 jurisdiction,
822 })
823 .pipe(Effect.catchTag(["DomainNotFound", "NoSuchBucket"], () => Effect.void));
824 }
825
826 if (!observedDomain || observedDomain.zoneId !== zoneId) {
827 const created = yield* r2
828 .createBucketDomainCustom({
829 accountId,
830 bucketName,
831 jurisdiction,
832 domain: domain.name,
833 enabled: domain.enabled ?? true,
834 zoneId,
835 ciphers: domain.ciphers,
836 minTLS: domain.minTLS,
837 })
838 .pipe(
839 Effect.retry({
840 while: (e) => e._tag === "NoSuchBucket",
841 schedule: r2BucketEndpointConsistencySchedule,
842 }),
843 Effect.retry({
844 while: (e) => e._tag === "CustomDomainInUse",
845 schedule: r2CustomDomainConflictSchedule,
846 }),
847 );
848 return toCustomDomainAttributes({ ...created, zoneId });
849 }
850
851 const updated = yield* r2
852 .updateBucketDomainCustom({
853 accountId,
854 bucketName,
855 domain: domain.name,
856 jurisdiction,
857 enabled: domain.enabled ?? true,
858 ciphers: domain.ciphers,
859 minTLS: domain.minTLS,
860 })
861 .pipe(
862 Effect.retry({
863 while: (e) => e._tag === "NoSuchBucket",
864 schedule: r2BucketEndpointConsistencySchedule,
865 }),
866 );
867 return toCustomDomainAttributes({
868 ...updated,
869 enabled: updated.enabled ?? domain.enabled ?? true,
870 zoneId,
871 });
872 }),
873 { concurrency: "unbounded" },
874 );
875
876 return applied.sort((a, b) => a.domain.localeCompare(b.domain));
877 });
878
879 const listManagedDomain = Effect.fn(function* (
880 bucketName: string,
881 jurisdiction: Bucket.Jurisdiction,
882 options?: { retryMissing?: boolean },
883 ) {
884 const { accountId } = yield* yield* CloudflareEnvironment;
885 const fetch = r2.listBucketDomainManageds({
886 accountId,
887 bucketName,
888 jurisdiction,
889 });
890 return yield* (
891 options?.retryMissing === false
892 ? fetch
893 : fetch.pipe(
894 Effect.retry({
895 while: (e) => e._tag === "NoSuchBucket",
896 schedule: r2BucketEndpointConsistencySchedule,
897 }),
898 )
899 ).pipe(
900 // The hostname exists whether or not public access is on; a
901 // disabled domain serves 401, so only report it while enabled.
902 Effect.map((response) => (response.enabled ? response.domain : undefined)),
903 Effect.catchTag("NoSuchBucket", () => Effect.undefined),
904 );
905 });
906
907 const reconcileManagedDomain = (
908 bucketName: string,
909 jurisdiction: Bucket.Jurisdiction,
910 desired: boolean,
911 ) =>
912 Effect.gen(function* () {
913 const { accountId } = yield* yield* CloudflareEnvironment;
914 const observed = yield* r2
915 .listBucketDomainManageds({
916 accountId,
917 bucketName,
918 jurisdiction,
919 })
920 .pipe(
921 Effect.retry({
922 while: (e) => e._tag === "NoSuchBucket",
923 schedule: r2BucketEndpointConsistencySchedule,
924 }),
925 );
926
927 if (observed.enabled === desired) {
928 return desired ? observed.domain : undefined;
929 }
930
931 const updated = yield* r2
932 .putBucketDomainManaged({
933 accountId,
934 bucketName,
935 enabled: desired,
936 jurisdiction,
937 })
938 .pipe(
939 Effect.retry({
940 while: (e) => e._tag === "NoSuchBucket",
941 schedule: r2BucketEndpointConsistencySchedule,
942 }),
943 );
944
945 return updated.enabled ? updated.domain : undefined;
946 });
947
948 // R2's `listBuckets` is not modelled as paginated by distilled and its
949 // response omits a continuation cursor, so paginate exhaustively with the
950 // `startAfter` query param: keep fetching full pages (capped at 1000)
951 // until a short page signals the end.
952 const listBucketsInJurisdiction = (accountId: string, jurisdiction: Bucket.Jurisdiction) =>
953 Effect.gen(function* () {
954 const all: {
955 name: string;
956 jurisdiction: Bucket.Jurisdiction;
957 storageClass: Bucket.StorageClass;
958 location: Bucket.Location | undefined;
959 }[] = [];
960 let startAfter: string | undefined = undefined;
961 const perPage = 1000;
962 for (;;) {
963 const response: r2.ListBucketsResponse = yield* r2.listBuckets({
964 accountId,
965 jurisdiction,
966 perPage,
967 startAfter,
968 });
969 const raw = response.buckets ?? [];
970 const page = raw.filter(
971 (b): b is typeof b & { name: string } => typeof b.name === "string" && b.name !== "",
972 );
973 for (const b of page) {
974 all.push({
975 name: b.name,
976 jurisdiction: (b.jurisdiction ?? jurisdiction) as Bucket.Jurisdiction,
977 storageClass: (b.storageClass ?? "Standard") as Bucket.StorageClass,
978 location: normalizeLocation(b.location),
979 });
980 }
981 // Terminate on the RAW page length — the filtered length can be
982 // shorter on a full page (nameless entries), which would end the
983 // walk early and silently drop the remaining buckets.
984 if (raw.length < perPage || page.length === 0) break;
985 startAfter = page[page.length - 1].name;
986 }
987 return all;
988 });
989
990 const reconcileLifecycleRules = (
991 bucketName: string,
992 jurisdiction: Bucket.Jurisdiction,
993 desired: BucketLifecycleRule[],
994 ) =>
995 Effect.gen(function* () {
996 const { accountId } = yield* yield* CloudflareEnvironment;
997 const observed = yield* r2
998 .getBucketLifecycle({
999 accountId,
1000 bucketName,
1001 jurisdiction,
1002 })
1003 .pipe(
1004 Effect.retry({
1005 while: (e) => e._tag === "NoSuchBucket",
1006 schedule: r2BucketEndpointConsistencySchedule,
1007 }),
1008 );
1009
1010 const observedRules = (observed.rules ?? []).map(toLifecycleRule);
1011 const desiredRules = desired.map(normalizeLifecycleRule);
1012
1013 if (deepEqual(observedRules, desiredRules)) {
1014 return desiredRules;
1015 }
1016
1017 yield* r2
1018 .putBucketLifecycle({
1019 accountId,
1020 bucketName,
1021 jurisdiction,
1022 rules: desired.map(toLifecyclePutPayload),
1023 })
1024 .pipe(
1025 Effect.retry({
1026 while: (e) => e._tag === "NoSuchBucket",
1027 schedule: r2BucketEndpointConsistencySchedule,
1028 }),
1029 );
1030
1031 return desiredRules;
1032 });
1033
1034 const reconcileCorsRules = (
1035 bucketName: string,
1036 jurisdiction: Bucket.Jurisdiction,
1037 desired: BucketCorsRule[],
1038 ) =>
1039 Effect.gen(function* () {
1040 const { accountId } = yield* yield* CloudflareEnvironment;
1041 const observed = yield* r2
1042 .getBucketCors({
1043 accountId,
1044 bucketName,
1045 jurisdiction,
1046 })
1047 .pipe(
1048 Effect.map((response) => (response.rules ?? []).map(toCorsRule)),
1049 // A bucket with no CORS configuration is a typed error, not an
1050 // empty rule list — normalize it to [] for the diff below.
1051 Effect.catchTag("NoCorsConfiguration", () => Effect.succeed([] as Bucket.CorsRule[])),
1052 Effect.retry({
1053 while: (e) => e._tag === "NoSuchBucket",
1054 schedule: r2BucketEndpointConsistencySchedule,
1055 }),
1056 );
1057
1058 const desiredRules = desired.map(normalizeCorsRule);
1059
1060 if (deepEqual(observed, desiredRules)) {
1061 return desiredRules;
1062 }
1063
1064 if (desiredRules.length === 0) {
1065 yield* r2
1066 .deleteBucketCors({
1067 accountId,
1068 bucketName,
1069 jurisdiction,
1070 })
1071 .pipe(
1072 Effect.retry({
1073 while: (e) => e._tag === "NoSuchBucket",
1074 schedule: r2BucketEndpointConsistencySchedule,
1075 }),
1076 );
1077 return desiredRules;
1078 }
1079
1080 yield* r2
1081 .putBucketCors({
1082 accountId,
1083 bucketName,
1084 jurisdiction,
1085 rules: desired.map(toCorsPutPayload),
1086 })
1087 .pipe(
1088 Effect.retry({
1089 while: (e) => e._tag === "NoSuchBucket",
1090 schedule: r2BucketEndpointConsistencySchedule,
1091 }),
1092 );
1093
1094 return desiredRules;
1095 });
1096
1097 // PUT replaces the bucket's whole rule set, so `[]` clears it.
1098 const reconcileLockRules = (
1099 bucketName: string,
1100 jurisdiction: Bucket.Jurisdiction,
1101 desired: BucketLockRule[],
1102 ) =>
1103 Effect.gen(function* () {
1104 const { accountId } = yield* yield* CloudflareEnvironment;
1105 const observed = yield* r2
1106 .getBucketLock({
1107 accountId,
1108 bucketName,
1109 jurisdiction,
1110 })
1111 .pipe(
1112 Effect.map((response) => sortLockRules((response.rules ?? []).map(toLockRule))),
1113 Effect.retry({
1114 while: (e) => e._tag === "NoSuchBucket",
1115 schedule: r2BucketEndpointConsistencySchedule,
1116 }),
1117 );
1118
1119 // R2 returns rules sorted by id, not in the order they were PUT,
1120 // so compare (and report) both sides in id order.
1121 const desiredRules = sortLockRules(
1122 desired.map((rule): Bucket.LockRule => ({
1123 ...rule,
1124 prefix: rule.prefix ?? "",
1125 })),
1126 );
1127
1128 if (deepEqual(observed, desiredRules)) {
1129 return desiredRules;
1130 }
1131
1132 yield* r2
1133 .putBucketLock({
1134 accountId,
1135 bucketName,
1136 jurisdiction,
1137 rules: desiredRules,
1138 })
1139 .pipe(
1140 Effect.retry({
1141 while: (e) => e._tag === "NoSuchBucket",
1142 schedule: r2BucketEndpointConsistencySchedule,
1143 }),
1144 );
1145
1146 return desiredRules;
1147 });
1148
1149 const reconcileLocalUploads = Effect.fn(function* (
1150 bucketName: string,
1151 jurisdiction: Bucket.Jurisdiction,
1152 desired: boolean,
1153 ) {
1154 // Local Uploads has no jurisdiction-scoped endpoint: Cloudflare does
1155 // not offer it on jurisdiction-restricted buckets, so such a bucket
1156 // is always disabled (reconcile refuses `true` up front).
1157 if (jurisdiction !== "default") return false;
1158 const { accountId } = yield* yield* CloudflareEnvironment;
1159 const observed = yield* r2.getBucketLocalUploads({ accountId, bucketName }).pipe(
1160 Effect.retry({
1161 while: (e) => e._tag === "NoSuchBucket",
1162 schedule: r2BucketEndpointConsistencySchedule,
1163 }),
1164 );
1165 if (observed.enabled === desired) return desired;
1166 // The PUT response omits `enabled`; a successful PUT applied `desired`.
1167 yield* r2.putBucketLocalUploads({ accountId, bucketName, enabled: desired }).pipe(
1168 Effect.retry({
1169 while: (e) => e._tag === "NoSuchBucket",
1170 schedule: r2BucketEndpointConsistencySchedule,
1171 }),
1172 );
1173 return desired;
1174 });
1175
1176 return {
1177 stables: ["bucketName", "accountId"],
1178 list: () =>
1179 Effect.gen(function* () {
1180 const { accountId } = yield* yield* CloudflareEnvironment;
1181 // R2 buckets are account-scoped but partitioned by jurisdiction, so
1182 // enumerate each jurisdiction. Accounts not entitled to a given
1183 // jurisdiction (e.g. `fedramp`) reject the route — treat as empty.
1184 const jurisdictions: Bucket.Jurisdiction[] = ["default", "eu", "us", "fedramp"];
1185 const perJurisdiction = yield* Effect.forEach(
1186 jurisdictions,
1187 (jurisdiction) =>
1188 listBucketsInJurisdiction(accountId, jurisdiction).pipe(
1189 // An account not entitled to a jurisdiction rejects the list
1190 // route with `Forbidden` ("Access Denied") or `InvalidRoute`
1191 // — there are simply no buckets there, so treat as empty.
1192 Effect.catchTag(["InvalidRoute", "Forbidden"], () => Effect.succeed([])),
1193 ),
1194 { concurrency: jurisdictions.length },
1195 );
1196 const buckets = perJurisdiction.flat();
1197
1198 // Hydrate each bucket into the exact `read` Attributes shape so the
1199 // result is directly usable by `delete` (which needs `domains` to
1200 // tear down custom domains).
1201 return yield* Effect.forEach(
1202 buckets,
1203 (bucket) =>
1204 Effect.gen(function* () {
1205 // The hydration reads are independent — issue them
1206 // concurrently so each bucket costs one round-trip of wall
1207 // clock instead of four (a large leaked-bucket census can
1208 // otherwise blow the nuke scan's per-provider timeout).
1209 const [domains, lifecycleRules, cors, publicDomain] = yield* Effect.all(
1210 [
1211 listCustomDomains(bucket.name, bucket.jurisdiction, {
1212 retryMissing: false,
1213 }).pipe(Effect.map((d) => d ?? [])),
1214 r2
1215 .getBucketLifecycle({
1216 accountId,
1217 bucketName: bucket.name,
1218 jurisdiction: bucket.jurisdiction,
1219 })
1220 .pipe(
1221 Effect.map((observed) => (observed.rules ?? []).map(toLifecycleRule)),
1222 Effect.catchTag("NoSuchBucket", () =>
1223 Effect.succeed([] as Bucket.LifecycleRule[]),
1224 ),
1225 ),
1226 r2
1227 .getBucketCors({
1228 accountId,
1229 bucketName: bucket.name,
1230 jurisdiction: bucket.jurisdiction,
1231 })
1232 .pipe(
1233 Effect.map((observed) => (observed.rules ?? []).map(toCorsRule)),
1234 Effect.catchTag(["NoSuchBucket", "NoCorsConfiguration"], () =>
1235 Effect.succeed([] as Bucket.CorsRule[]),
1236 ),
1237 ),
1238 listManagedDomain(bucket.name, bucket.jurisdiction, {
1239 retryMissing: false,
1240 }),
1241 ] as const,
1242 { concurrency: 4 },
1243 );
1244 return {
1245 bucketName: bucket.name,
1246 storageClass: bucket.storageClass,
1247 jurisdiction: bucket.jurisdiction,
1248 location: bucket.location,
1249 accountId,
1250 domains,
1251 lifecycleRules,
1252 cors,
1253 locks: undefined,
1254 localUploads: undefined,
1255 publicDomain,
1256 };
1257 }).pipe(
1258 // The custom-domain endpoint intermittently 500s ("Failed to
1259 // access or modify the bucket policy"), and some buckets 500
1260 // PERSISTENTLY. The blanket Cloudflare retry policy already
1261 // retries each call's transient blips; don't stack another
1262 // retry here (the budgets multiply into minutes per bucket).
1263 // A bucket that still 500s must not abort the account-wide
1264 // enumeration (nuke would then see ZERO buckets) — degrade
1265 // it to an un-hydrated shape; delete can still tear the
1266 // bucket down.
1267 Effect.catchTag("InternalServerError", () =>
1268 Effect.succeed({
1269 bucketName: bucket.name,
1270 storageClass: bucket.storageClass,
1271 jurisdiction: bucket.jurisdiction,
1272 location: bucket.location,
1273 accountId,
1274 domains: [] as Bucket.CustomDomain[],
1275 lifecycleRules: [] as Bucket.LifecycleRule[],
1276 cors: [] as Bucket.CorsRule[],
1277 locks: undefined,
1278 localUploads: undefined,
1279 publicDomain: undefined,
1280 }),
1281 ),
1282 ),
1283 { concurrency: 10 },
1284 );
1285 }),
1286 diff: Effect.fn(function* ({ id, olds = {}, news = {}, output }) {
1287 if (!isResolved(news)) return undefined;
1288 const { accountId } = yield* yield* CloudflareEnvironment;
1289 const oldName = output?.bucketName ?? (yield* createBucketName(id, olds.name));
1290 // Auto-generated names are engine-owned: the deployed name stays
1291 // authoritative even if the generator would name this id
1292 // differently today. Only an explicit user-provided name can
1293 // force a replace.
1294 const name = news.name ?? oldName;
1295 const oldJurisdiction = output?.jurisdiction ?? olds.jurisdiction ?? "default";
1296 const oldStorageClass = output?.storageClass ?? olds.storageClass ?? "Standard";
1297 if (
1298 (output?.accountId ?? accountId) !== accountId ||
1299 oldName !== name ||
1300 oldJurisdiction !== (news.jurisdiction ?? "default") ||
1301 olds.locationHint !== news.locationHint
1302 ) {
1303 return { action: "replace" } as const;
1304 }
1305 if (oldStorageClass !== (news.storageClass ?? "Standard")) {
1306 return {
1307 action: "update",
1308 // `accountId` is always stable across an update (a name/account
1309 // change is a `replace`); keep it now that `diff.stables`
1310 // overrides `provider.stables` rather than merging with it.
1311 stables: oldName === name ? ["bucketName", "accountId"] : ["accountId"],
1312 } as const;
1313 }
1314 if (!deepEqual(olds.domains, news.domains)) {
1315 return { action: "update" } as const;
1316 }
1317 if (!deepEqual(olds.lifecycleRules, news.lifecycleRules)) {
1318 return { action: "update" } as const;
1319 }
1320 if (!deepEqual(olds.cors, news.cors)) {
1321 return { action: "update" } as const;
1322 }
1323 if (!deepEqual(olds.locks, news.locks)) {
1324 return { action: "update" } as const;
1325 }
1326 if ((olds.publicAccess ?? false) !== (news.publicAccess ?? false)) {
1327 return { action: "update" } as const;
1328 }
1329 if (olds.localUploads !== news.localUploads) {
1330 return { action: "update" } as const;
1331 }
1332 }),
1333 reconcile: Effect.fn(function* ({ id, news = {}, olds, output }) {
1334 const { accountId } = yield* yield* CloudflareEnvironment;
1335 // Prefer the deployed name: regenerating would target a different
1336 // bucket if the generator's output for this id ever drifts.
1337 const name = output?.bucketName ?? (yield* createBucketName(id, news.name));
1338 const acct = output?.accountId ?? accountId;
1339 const jurisdiction = output?.jurisdiction ?? news.jurisdiction ?? "default";
1340
1341 // Refuse before creating anything, so a rejected deploy leaves no
1342 // bucket behind.
1343 if (news.localUploads === true && jurisdiction !== "default") {
1344 return yield* new LocalUploadsUnsupported({
1345 bucketName: name,
1346 jurisdiction,
1347 message: `R2 Local Uploads is not available for jurisdiction-restricted bucket "${name}" (jurisdiction "${jurisdiction}")`,
1348 });
1349 }
1350
1351 // Observe — fetch the bucket. R2 reports a deleted bucket as
1352 // `NoSuchBucket`; tolerate that so the reconciler falls
1353 // through to the create path.
1354 let observed = yield* r2
1355 .getBucket({
1356 accountId: acct,
1357 bucketName: name,
1358 jurisdiction,
1359 })
1360 .pipe(Effect.catchTag("NoSuchBucket", () => Effect.undefined));
1361
1362 // Ensure — create if missing. R2 reports a concurrent create
1363 // (or partial state-persistence failure) as
1364 // `BucketAlreadyExists`; tolerate by re-fetching the bucket.
1365 if (!observed) {
1366 observed = yield* r2
1367 .createBucket({
1368 accountId: acct,
1369 name,
1370 storageClass: news.storageClass,
1371 jurisdiction: news.jurisdiction,
1372 locationHint: news.locationHint,
1373 })
1374 .pipe(
1375 Effect.catchTag("BucketAlreadyExists", () =>
1376 r2
1377 .getBucket({
1378 accountId: acct,
1379 bucketName: name,
1380 jurisdiction: news.jurisdiction,
1381 })
1382 .pipe(
1383 // The create lost a race, but the winning create may not
1384 // be readable yet — ride out the consistency lag.
1385 Effect.retry({
1386 while: (e) => e._tag === "NoSuchBucket",
1387 schedule: r2BucketEndpointConsistencySchedule,
1388 }),
1389 ),
1390 ),
1391 );
1392 }
1393
1394 // Sync — storage class is the only mutable bucket property
1395 // (location and jurisdiction are immutable; the diff flags those
1396 // as `replace`). PATCH carries the class in the
1397 // `cf-r2-storage-class` header. Address the bucket by the
1398 // RESOLVED name, never `observed.name` — a response missing the
1399 // name would collapse the URI to the collection path, which the
1400 // control plane rejects with `PATCH not supported for requested
1401 // URI`. Only patch when the desired class drifts from observed.
1402 const desiredStorageClass = news.storageClass ?? "Standard";
1403 const observedStorageClass = observed.storageClass ?? "Standard";
1404 if (observedStorageClass !== desiredStorageClass) {
1405 observed = yield* r2
1406 .patchBucket({
1407 accountId: acct,
1408 bucketName: name,
1409 storageClass: desiredStorageClass,
1410 jurisdiction: observed.jurisdiction ?? jurisdiction,
1411 })
1412 .pipe(
1413 // The patch endpoint can briefly 404 a freshly-created bucket
1414 // even after `getBucket` already sees it.
1415 Effect.retry({
1416 while: (e) => e._tag === "NoSuchBucket",
1417 schedule: r2BucketEndpointConsistencySchedule,
1418 }),
1419 );
1420 }
1421
1422 const attrs = {
1423 bucketName: observed.name ?? name,
1424 // Distilled widened generated string enums to open unions.
1425 storageClass: (observed.storageClass ?? "Standard") as Bucket.StorageClass,
1426 jurisdiction: (observed.jurisdiction ?? "default") as Bucket.Jurisdiction,
1427 location: normalizeLocation(observed.location),
1428 accountId: acct,
1429 };
1430
1431 const domains = yield* reconcileCustomDomains(
1432 attrs.bucketName,
1433 attrs.jurisdiction,
1434 news.domains ?? [],
1435 output?.domains ?? [],
1436 );
1437
1438 const lifecycleRules = yield* reconcileLifecycleRules(
1439 attrs.bucketName,
1440 attrs.jurisdiction,
1441 news.lifecycleRules ?? [],
1442 );
1443
1444 const cors = yield* reconcileCorsRules(
1445 attrs.bucketName,
1446 attrs.jurisdiction,
1447 news.cors ?? [],
1448 );
1449
1450 // Locks are managed only once the props name them: clearing rules
1451 // a stack never declared would drop protection someone else set.
1452 // Removing `locks` after declaring it still clears them.
1453 const locks =
1454 news.locks !== undefined || olds?.locks !== undefined
1455 ? yield* reconcileLockRules(attrs.bucketName, attrs.jurisdiction, news.locks ?? [])
1456 : undefined;
1457
1458 // Like locks, Local Uploads is managed only once the props name it.
1459 const localUploads =
1460 news.localUploads !== undefined || olds?.localUploads !== undefined
1461 ? yield* reconcileLocalUploads(
1462 attrs.bucketName,
1463 attrs.jurisdiction,
1464 news.localUploads ?? false,
1465 )
1466 : undefined;
1467
1468 const publicDomain = yield* reconcileManagedDomain(
1469 attrs.bucketName,
1470 attrs.jurisdiction,
1471 news.publicAccess ?? false,
1472 );
1473
1474 return {
1475 ...attrs,
1476 domains,
1477 lifecycleRules,
1478 cors,
1479 locks,
1480 localUploads,
1481 publicDomain,
1482 };
1483 }),
1484 delete: Effect.fn(function* ({ olds = {}, output, force }) {
1485 yield* Effect.forEach(
1486 output.domains ?? [],
1487 (domain) =>
1488 r2
1489 .deleteBucketDomainCustom({
1490 accountId: output.accountId,
1491 bucketName: output.bucketName,
1492 domain: domain.domain,
1493 jurisdiction: output.jurisdiction,
1494 })
1495 .pipe(Effect.catchTag(["DomainNotFound", "NoSuchBucket"], () => Effect.void)),
1496 { concurrency: "unbounded" },
1497 );
1498
1499 // Whether we may destroy the bucket's CONTENTS.
1500 // - `olds.forceDestroy` — the user opted in on the resource props.
1501 // - `force` — set only by `alchemy unsafe nuke`, an explicitly
1502 // operator-confirmed account teardown. Nuke enumerates buckets
1503 // straight from the cloud (its `olds` is Attributes, not Props),
1504 // so `forceDestroy` is never present there.
1505 //
1506 // Without either, the objects are left alone and R2's own refusal
1507 // to delete a non-empty bucket (`BucketNotEmpty`) stands — that
1508 // refusal is the data protection users rely on, and emptying the
1509 // bucket to get past it is how a stack teardown turns into
1510 // irreversible data loss (#1248).
1511 const destroyContents = olds.forceDestroy === true || force === true;
1512 if (destroyContents) {
1513 yield* emptyBucket(output.bucketName, output.jurisdiction);
1514 }
1515 const deleteBucket = r2
1516 .deleteBucket({
1517 accountId: output.accountId,
1518 bucketName: output.bucketName,
1519 jurisdiction: output.jurisdiction,
1520 })
1521 .pipe(Effect.catchTag("NoSuchBucket", () => Effect.void));
1522 if (!destroyContents) {
1523 return yield* deleteBucket;
1524 }
1525 // A writer that outlives the emptying pass (a Durable Object's
1526 // alarm finishing a job while the stack tears down) can land an
1527 // object between the sweep and the delete: re-empty and retry,
1528 // bounded.
1529 const deleteEmptied = deleteBucket.pipe(
1530 Effect.catchTag("BucketNotEmpty", (error) =>
1531 Effect.sleep("2 seconds").pipe(
1532 Effect.andThen(emptyBucket(output.bucketName, output.jurisdiction)),
1533 Effect.andThen(Effect.fail(error)),
1534 ),
1535 ),
1536 Effect.retry({
1537 while: (error) => error._tag === "BucketNotEmpty",
1538 times: 5,
1539 }),
1540 );
1541 yield* deleteBucket.pipe(
1542 // Incomplete multipart uploads also hold a bucket, and the
1543 // object listing doesn't show them. Only R2's S3 API can abort
1544 // them, which works when alchemy is authenticated with an API
1545 // token — try that once, best effort, then re-empty and retry.
1546 Effect.catchTag("BucketNotEmpty", () =>
1547 Effect.gen(function* () {
1548 const result = yield* abortMultipartUploads(
1549 output.accountId,
1550 output.bucketName,
1551 output.jurisdiction,
1552 );
1553 if ("aborted" in result && result.aborted > 0) {
1554 yield* Effect.logInfo(
1555 `Aborted ${result.aborted} incomplete multipart upload(s) in R2 bucket ${output.bucketName}`,
1556 );
1557 }
1558 yield* emptyBucket(output.bucketName, output.jurisdiction);
1559 yield* deleteEmptied.pipe(
1560 Effect.catchTag("BucketNotEmpty", (error) =>
1561 Effect.fail(
1562 new BucketNotEmpty({
1563 bucketName: output.bucketName,
1564 message:
1565 `${error.message} forceDestroy deleted every object, so incomplete ` +
1566 `multipart uploads are likely holding it` +
1567 ("skipped" in result
1568 ? `, and alchemy could not abort them (${result.skipped}). `
1569 : `. `) +
1570 `Only R2's S3 API can abort them: authenticate alchemy with a ` +
1571 `Cloudflare API token that has the "Workers R2 Storage Write" ` +
1572 `permission and destroy again. Or add a lifecycle rule ` +
1573 `{ abortMultipartUploadsTransition: { condition: { type: "Age", ` +
1574 `maxAge: 86400 } } } and retry once R2 has applied it; R2 aborts ` +
1575 `them on its own after 7 days.`,
1576 }),
1577 ),
1578 ),
1579 );
1580 }),
1581 ),
1582 );
1583 }),
1584 read: Effect.fn(function* ({ id, output, olds }) {
1585 const { accountId } = yield* yield* CloudflareEnvironment;
1586 const name = output?.bucketName ?? (yield* createBucketName(id, olds?.name));
1587 const acct = output?.accountId ?? accountId;
1588 return yield* r2
1589 .getBucket({
1590 accountId: acct,
1591 bucketName: name,
1592 jurisdiction: output?.jurisdiction ?? olds?.jurisdiction,
1593 })
1594 .pipe(
1595 Effect.map((bucket) => ({
1596 bucketName: bucket.name!,
1597 // Distilled widened generated string enums to open unions.
1598 storageClass: (bucket.storageClass ?? "Standard") as Bucket.StorageClass,
1599 jurisdiction: (bucket.jurisdiction ?? "default") as Bucket.Jurisdiction,
1600 location: normalizeLocation(bucket.location),
1601 accountId: acct,
1602 domains: output?.domains ?? [],
1603 lifecycleRules: output?.lifecycleRules ?? [],
1604 cors: output?.cors ?? [],
1605 locks: output?.locks,
1606 localUploads: output?.localUploads,
1607 publicDomain: output?.publicDomain,
1608 })),
1609 Effect.catchTag("NoSuchBucket", () => Effect.undefined),
1610 );
1611 }),
1612 };
1613 }),
1614 );
1615
1616 /**
1617 * Local (dev) provider — the bucket is purely virtual: a `dev:`-prefixed
1618 * bucket name keyed into the local workerd R2 simulator (data under
1619 * `.alchemy/local/r2`). `toRuntimeBinding` lowers an `r2_bucket` binding
1620 * whose bucket name is `dev:`-prefixed onto the local R2 service. R2 has no
1621 * opaque id — the name IS the identity — so the `dev:` marker rides on the
1622 * name (a `:` can never appear in a real R2 bucket name).
1623 *
1624 * Custom domains, lifecycle rules, CORS, lock rules, and the managed r2.dev
1625 * domain are deploy-side concerns with no local behavior; the local
1626 * attributes report them empty.
1627 */
1628 export const ProviderLocal = () =>
1629 Provider.succeed(Bucket, {
1630 stables: ["accountId"],
1631 diff: Effect.fn(function* ({ news = {}, output }) {
1632 const accountId = yield* localAccountId;
1633 if (!output?.bucketName) return { action: "update" } as const;
1634 if (!isResolved(news)) return undefined;
1635 if (output.accountId !== accountId) {
1636 return { action: "replace" } as const;
1637 }
1638 // Fall through to the engine's default prop diff.
1639 }),
1640 read: Effect.fn(function* ({ output }) {
1641 // Purely virtual — the persisted state row is the source of truth.
1642 return output ?? undefined;
1643 }),
1644 reconcile: Effect.fn(function* ({ news = {}, output }) {
1645 const accountId = yield* localAccountId;
1646 return {
1647 bucketName: output?.bucketName ?? generateLocalId(),
1648 storageClass: (news.storageClass ?? "Standard") as Bucket.StorageClass,
1649 jurisdiction: (news.jurisdiction ?? "default") as Bucket.Jurisdiction,
1650 location: undefined,
1651 accountId: output?.accountId ?? accountId,
1652 domains: [],
1653 lifecycleRules: [],
1654 cors: [],
1655 locks: undefined,
1656 localUploads: undefined,
1657 publicDomain: undefined,
1658 };
1659 }),
1660 delete: Effect.fn(function* () {
1661 // The simulator's on-disk data is keyed by the dev name; dropping the
1662 // state row is enough — orphaned blobs are reclaimed with `.alchemy`.
1663 }),
1664 });
1665
1666 export const BucketProvider = () =>
1667 ProviderLayer.dual(Bucket, {
1668 local: () => ProviderLocal(),
1669 live: () => ProviderLive(),
1670 });
1671
1672 // R2 can make a newly-created bucket visible to `getBucket` before its
1673 // sub-resource endpoints (custom domains, lifecycle) accept it. Retry only
1674 // that narrow `NoSuchBucket` lag here; not-found sub-resources are still
1675 // treated as terminal for idempotent deletes.
1676 /**
1677 * Local Uploads was requested on a jurisdiction-restricted bucket, which
1678 * Cloudflare does not support.
1679 */
1680 /**
1681 * A `forceDestroy` delete emptied the bucket, but R2 still refuses to delete
1682 * it — usually because incomplete multipart uploads hold it.
1683 */
1684 class BucketNotEmpty extends Data.TaggedError("BucketNotEmpty")<{
1685 bucketName: string;
1686 message: string;
1687 }> {}
1688
1689 export class LocalUploadsUnsupported extends Data.TaggedError("LocalUploadsUnsupported")<{
1690 bucketName: string;
1691 jurisdiction: Bucket.Jurisdiction;
1692 message: string;
1693 }> {}
1694
1695 const r2BucketEndpointConsistencySchedule = Schedule.max([
1696 Schedule.exponential(100),
1697 Schedule.recurs(5),
1698 ]);
1699
1700 // Distilled widened generated string enums to open unions (`string & {}`); the
1701 // API only ever returns the known variants, narrowed in `toCustomDomainAttributes`.
1702 type CustomDomainResponse = {
1703 domain: string;
1704 zoneId?: string | null;
1705 enabled?: boolean | null;
1706 ciphers?: string[] | null;
1707 minTLS?: string | null;
1708 status?: { ownership: string; ssl: string } | null;
1709 };
1710
1711 const toCustomDomainAttributes = (domain: CustomDomainResponse): Bucket.CustomDomain => ({
1712 domain: domain.domain,
1713 zoneId: domain.zoneId ?? undefined,
1714 enabled: domain.enabled ?? true,
1715 ciphers: domain.ciphers ?? undefined,
1716 minTLS: (domain.minTLS ?? undefined) as Bucket.CustomDomain["minTLS"],
1717 status: (domain.status ?? undefined) as Bucket.CustomDomain["status"],
1718 });
1719
1720 const sameCustomDomainConfig = (
1721 observed: Bucket.CustomDomain | undefined,
1722 desired: BucketCustomDomain,
1723 zoneId: string,
1724 ): boolean =>
1725 observed !== undefined &&
1726 observed.zoneId === zoneId &&
1727 observed.enabled === (desired.enabled ?? true) &&
1728 deepEqual(observed.ciphers, desired.ciphers) &&
1729 observed.minTLS === desired.minTLS;
1730
1731 type LifecycleRuleResponse = NonNullable<r2.GetBucketLifecycleResponse["rules"]>[number];
1732
1733 const toLifecycleRule = (rule: LifecycleRuleResponse): Bucket.LifecycleRule => ({
1734 id: rule.id,
1735 enabled: rule.enabled,
1736 prefix: rule.conditions.prefix ?? "",
1737 abortMultipartUploadsTransition: rule.abortMultipartUploadsTransition
1738 ? { condition: rule.abortMultipartUploadsTransition.condition ?? undefined }
1739 : undefined,
1740 deleteObjectsTransition: rule.deleteObjectsTransition
1741 ? { condition: rule.deleteObjectsTransition.condition ?? undefined }
1742 : undefined,
1743 storageClassTransitions: rule.storageClassTransitions ?? undefined,
1744 });
1745
1746 const normalizeLifecycleRule = (rule: BucketLifecycleRule): Bucket.LifecycleRule => ({
1747 id: rule.id,
1748 enabled: rule.enabled ?? true,
1749 prefix: rule.prefix ?? "",
1750 abortMultipartUploadsTransition: rule.abortMultipartUploadsTransition
1751 ? { condition: rule.abortMultipartUploadsTransition.condition }
1752 : undefined,
1753 deleteObjectsTransition: rule.deleteObjectsTransition
1754 ? { condition: rule.deleteObjectsTransition.condition }
1755 : undefined,
1756 storageClassTransitions: rule.storageClassTransitions,
1757 });
1758
1759 type CorsRuleResponse = NonNullable<r2.GetBucketCorsResponse["rules"]>[number];
1760
1761 const toCorsRule = (rule: CorsRuleResponse): Bucket.CorsRule => ({
1762 id: rule.id ?? undefined,
1763 // Distilled widened generated string enums to open unions.
1764 allowedMethods: rule.allowed.methods as Bucket.CorsRule["allowedMethods"],
1765 allowedOrigins: rule.allowed.origins,
1766 allowedHeaders: rule.allowed.headers ?? undefined,
1767 exposeHeaders: rule.exposeHeaders ?? undefined,
1768 maxAgeSeconds: rule.maxAgeSeconds ?? undefined,
1769 });
1770
1771 const normalizeCorsRule = (rule: BucketCorsRule): Bucket.CorsRule => ({
1772 id: rule.id,
1773 allowedMethods: rule.allowedMethods,
1774 allowedOrigins: rule.allowedOrigins,
1775 allowedHeaders: rule.allowedHeaders,
1776 exposeHeaders: rule.exposeHeaders,
1777 maxAgeSeconds: rule.maxAgeSeconds,
1778 });
1779
1780 const toCorsPutPayload = (
1781 rule: BucketCorsRule,
1782 ): NonNullable<r2.PutBucketCorsRequest["rules"]>[number] => ({
1783 id: rule.id,
1784 allowed: {
1785 methods: rule.allowedMethods,
1786 origins: rule.allowedOrigins,
1787 headers: rule.allowedHeaders,
1788 },
1789 exposeHeaders: rule.exposeHeaders,
1790 maxAgeSeconds: rule.maxAgeSeconds,
1791 });
1792
1793 const toLifecyclePutPayload = (
1794 rule: BucketLifecycleRule,
1795 ): NonNullable<r2.PutBucketLifecycleRequest["rules"]>[number] => ({
1796 id: rule.id,
1797 enabled: rule.enabled ?? true,
1798 conditions: { prefix: rule.prefix ?? "" },
1799 abortMultipartUploadsTransition: rule.abortMultipartUploadsTransition,
1800 deleteObjectsTransition: rule.deleteObjectsTransition,
1801 storageClassTransitions: rule.storageClassTransitions,
1802 });
1803
1804 type LockRuleResponse = NonNullable<r2.GetBucketLockResponse["rules"]>[number];
1805
1806 const sortLockRules = (rules: Bucket.LockRule[]): Bucket.LockRule[] =>
1807 [...rules].sort((a, b) => (a.id < b.id ? -1 : a.id > b.id ? 1 : 0));
1808
1809 // The condition decodes as an unchecked union; copy only the known fields so
1810 // the drift comparison against the desired rules is exact.
1811 const toLockRule = (rule: LockRuleResponse): Bucket.LockRule => {
1812 const condition = rule.condition;
1813 return {
1814 id: rule.id,
1815 enabled: rule.enabled,
1816 prefix: rule.prefix ?? "",
1817 condition:
1818 condition.type === "Age"
1819 ? { type: "Age", maxAgeSeconds: condition.maxAgeSeconds }
1820 : condition.type === "Date"
1821 ? { type: "Date", date: condition.date }
1822 : { type: "Indefinite" },
1823 };
1824 };
1825
1826 // Cloudflare keys a custom domain to a single bucket at the zone level. After a
1827 // domain is deleted, re-attaching the same hostname can transiently 409 with
1828 // "Domain already in use" (typed as `CustomDomainInUse`) until the prior
1829 // association is fully released. Treat that narrow conflict as eventual
1830 // consistency and retry it on create. Releasing a custom domain after delete
1831 // can lag a few seconds, so give the conflict a longer, bounded budget than
1832 // the bucket-endpoint lag above.
1833 const r2CustomDomainConflictSchedule = Schedule.max([
1834 Schedule.spaced("2 seconds"),
1835 Schedule.recurs(8),
1836 ]);