import * as r2 from "@distilled.cloud/cloudflare/r2";
import { deepEqual, isResolved } from "alchemy/Diff";
import * as ProviderLayer from "alchemy/Local/ProviderLayer";
import { createPhysicalName } from "alchemy/PhysicalName";
import * as Provider from "alchemy/Provider";
import { isResourceOfType, Resource } from "alchemy/Resource";
import * as Data from "effect/Data";
import * as Effect from "effect/Effect";
import * as Schedule from "effect/Schedule";
import * as Stream from "effect/Stream";
import { CloudflareEnvironment } from "../CloudflareEnvironment.ts";
import { localAccountId } from "../LocalAccount.ts";
import { generateLocalId } from "../LocalRuntime.ts";
import type * as Cloudflare from "../Providers.ts";
import * as Zone from "../Zone/index.ts";
import { abortMultipartUploads } from "./internal/MultipartUploads.ts";
export class BucketOperationFailed extends Data.TaggedError("BucketOperationFailed")<{
readonly message: string;
readonly cause?: unknown;
}> {}
export const isBucket = (value: any): value is Bucket =>
isResourceOfType(value, "Cloudflare.R2.Bucket");
export type BucketName = string;
export type BucketCustomDomainZone = Zone.Reference;
export type BucketCustomDomain = {
/**
* Custom domain name to attach to the bucket.
*/
name: string;
/**
* Zone that contains the custom domain. If omitted, the zone is inferred
* from `domain`. Pass a zone ID string, a hostname in the zone, or any object
* with a `zoneId` attribute such as `Cloudflare.Zone.Zone`.
*/
zone?: BucketCustomDomainZone;
/**
* Whether public bucket access is enabled at this custom domain.
* @default true
*/
enabled?: boolean;
/**
* Allowlist of TLS ciphers in BoringSSL format.
*/
ciphers?: string[];
/**
* Minimum TLS version accepted by the custom domain.
* @default "1.0"
*/
minTLS?: "1.0" | "1.1" | "1.2" | "1.3";
};
export type BucketLifecycleCondition =
| {
type: "Age";
/**
* Maximum age of an object, in seconds, before the rule's action applies.
*/
maxAge: number;
}
| {
type: "Date";
/**
* Absolute date (ISO 8601) at which the rule's action applies.
*/
date: string;
};
export type BucketLifecycleRule = {
/**
* Unique identifier for the rule within the bucket.
*/
id: string;
/**
* Whether the rule is enabled.
* @default true
*/
enabled?: boolean;
/**
* Object key prefix the rule applies to. Use `""` (or omit) to match all
* objects in the bucket.
* @default ""
*/
prefix?: string;
/**
* Abort incomplete multipart uploads after the configured age.
*/
abortMultipartUploadsTransition?: {
condition?: { type: "Age"; maxAge: number };
};
/**
* Delete matching objects after the configured age or on a specific date.
*/
deleteObjectsTransition?: {
condition?: BucketLifecycleCondition;
};
/**
* Transition matching objects to a different storage class. Cloudflare R2
* only supports transitioning to `InfrequentAccess` today.
*/
storageClassTransitions?: {
condition: BucketLifecycleCondition;
storageClass: "InfrequentAccess";
}[];
};
export type BucketCorsRule = {
/**
* Optional label for this rule, shown in the Cloudflare dashboard. Not
* used to correlate rules across updates — the CORS configuration is
* always replaced as a whole.
*/
id?: string;
/**
* HTTP methods browsers are allowed to use in cross-origin requests.
*/
allowedMethods: ("GET" | "PUT" | "POST" | "DELETE" | "HEAD")[];
/**
* Origins allowed to make cross-origin requests, e.g.
* `"https://example.com"`. Use `"*"` to allow any origin.
*/
allowedOrigins: string[];
/**
* Request headers browsers are allowed to send, e.g. `"range"` for
* range reads. If omitted, only simple headers are allowed.
*/
allowedHeaders?: string[];
/**
* Response headers the browser is allowed to expose to the requesting
* JavaScript, e.g. `"etag"` or `"content-range"`.
*/
exposeHeaders?: string[];
/**
* How long (in seconds) browsers may cache CORS preflight responses.
* Browsers may cap this at 2 hours or less, even if 86400 is specified.
*/
maxAgeSeconds?: number;
};
export type BucketLockCondition =
| {
/**
* Lock matching objects permanently. They can never be deleted or
* overwritten, so the bucket can never be emptied or deleted.
*/
type: "Indefinite";
}
| {
type: "Age";
/**
* Seconds after upload during which matching objects stay locked.
*/
maxAgeSeconds: number;
}
| {
type: "Date";
/**
* Absolute date (ISO 8601) until which matching objects stay locked.
*/
date: string;
};
export type BucketLockRule = {
/**
* Unique identifier for the rule within the bucket.
*/
id: string;
/**
* Whether the rule is in effect.
*/
enabled: boolean;
/**
* Object key prefix the rule applies to. Use `""` (or omit) to lock every
* object in the bucket.
* @default ""
*/
prefix?: string;
/**
* How long matching objects stay locked.
*/
condition: BucketLockCondition;
};
export type BucketProps = {
/**
* Name of the bucket. If omitted, a unique name will be generated.
* @default ${app}-${stage}-${id}
*/
name?: string;
/**
* Storage class for newly uploaded objects.
* @default "Standard"
*/
storageClass?: Bucket.StorageClass;
/**
* Jurisdiction where objects in this bucket are guaranteed to be stored:
* `"eu"` (the European Union), `"us"` (the United States), or `"fedramp"`
* (FedRAMP-compliant data centers). `"default"` places no restriction.
* Changing it replaces the bucket.
* @default "default"
*/
jurisdiction?: Bucket.Jurisdiction;
/**
* Location hint for the bucket.
*/
locationHint?: Bucket.Location;
/**
* Custom domains to attach to the bucket. Pass an empty array (or omit)
* to remove all custom domains.
*/
domains?: BucketCustomDomain[];
/**
* Whether the bucket is publicly readable at Cloudflare's managed
* `r2.dev` domain. Cloudflare's default is off; omit or pass `false`
* to disable it.
*
* Once enabled, the hostname is reported on `publicDomain`. This
* endpoint is rate-limited and intended for non-production use — use
* `domains` for production public access.
*
* @default false
*/
publicAccess?: boolean;
/**
* Object lifecycle rules applied to the bucket. Pass an empty array (or
* omit) to clear all lifecycle rules. See the Cloudflare R2 docs for
* supported transitions.
*/
lifecycleRules?: BucketLifecycleRule[];
/**
* CORS rules applied to the bucket, controlling which cross-origin
* browser requests are allowed against the bucket's public or S3 API
* endpoints. Pass an empty array (or omit) to remove the CORS
* configuration.
*/
cors?: BucketCorsRule[];
/**
* Object lock rules applied to the bucket. While a rule's condition
* holds, R2 refuses to delete or overwrite any object whose key matches
* the rule's prefix, whoever signs the request (S3 API credentials
* included). An `Indefinite` rule never lapses: matching objects are
* permanent and the bucket can never be emptied, so `forceDestroy`
* cannot delete it.
*
* A bucket that never declared `locks` keeps whatever rules it has: they
* are left unmanaged. Pass an empty array, or drop `locks` after
* declaring it, to remove every rule.
*/
locks?: BucketLockRule[];
/**
* Whether R2 Local Uploads is enabled. Uploads from clients far from the
* bucket's region are written near the client first and replicated to the
* bucket asynchronously. Toggling it updates the bucket in place.
*
* Not available for jurisdiction-restricted buckets: enabling it on a
* bucket whose `jurisdiction` is not `"default"` fails the deploy.
*
* A bucket that never declared `localUploads` keeps whatever setting it
* has. Drop `localUploads` after declaring it to disable it.
*/
localUploads?: boolean;
/**
* Allow alchemy to delete every object in the bucket when the bucket
* itself is deleted.
*
* R2 refuses to delete a bucket that still has objects in it — that
* refusal is the last line of defense for your data, so alchemy does not
* bypass it by default: destroying a non-empty bucket fails with
* `BucketNotEmpty` and both the bucket and its objects survive. Set this
* to `true` for buckets whose contents are disposable (caches, previews,
* test fixtures).
*
* Incomplete multipart uploads also hold a bucket. Only R2's S3 API can
* abort them, so alchemy aborts them only when it is authenticated with
* an API token that may write the bucket's objects (it never creates a
* token). Otherwise destroying fails with `BucketNotEmpty`: abort them,
* or add an `abortMultipartUploadsTransition` lifecycle rule, first.
*
* `alchemy unsafe nuke` empties buckets regardless, since it is an
* explicitly operator-confirmed account teardown.
*
* @default false
*/
forceDestroy?: boolean;
};
export type Bucket = Resource<
"Cloudflare.R2.Bucket",
BucketProps,
{
bucketName: BucketName;
storageClass: Bucket.StorageClass;
jurisdiction: Bucket.Jurisdiction;
location: Bucket.Location | undefined;
accountId: string;
domains: Bucket.CustomDomain[];
lifecycleRules: Bucket.LifecycleRule[];
cors: Bucket.CorsRule[];
/**
* Lock rules on the bucket. `undefined` while `locks` is unmanaged
* (omitted from the props).
*/
locks: Bucket.LockRule[] | undefined;
/**
* Whether Local Uploads is enabled. `undefined` while `localUploads` is
* unmanaged (omitted from the props).
*/
localUploads: boolean | undefined;
/**
* Hostname of the bucket's Cloudflare-managed `r2.dev` domain.
* Set only while `publicAccess` is enabled; `undefined` when
* disabled (the domain still exists but serves 401).
*/
publicDomain: string | undefined;
},
never,
Cloudflare.Providers
>;
/**
* A Cloudflare R2 object storage bucket with S3-compatible API.
*
* R2 provides zero-egress-fee object storage. Create a bucket as a resource,
* then bind it to a Worker to read and write objects at runtime.
* ### Creating a Bucket
* **Example:** Basic R2 bucket
* ```typescript
* const bucket = yield* Cloudflare.R2.Bucket("MyBucket");
* ```
*
* **Example:** Bucket with location hint
* ```typescript
* const bucket = yield* Cloudflare.R2.Bucket("MyBucket", {
* locationHint: "wnam",
* });
* ```
*
* ### Binding to a Worker
* **Example:** Reading and writing objects
* ```typescript
* const bucket = yield* Cloudflare.R2.ReadWriteBucket(MyBucket);
*
* // Write an object
* yield* bucket.put("hello.txt", "Hello, World!");
*
* // Read an object
* const object = yield* bucket.get("hello.txt");
* if (object) {
* const text = yield* object.text();
* }
* ```
*
* **Example:** Streaming upload with content length
* ```typescript
* const bucket = yield* Cloudflare.R2.ReadWriteBucket(MyBucket);
*
* yield* bucket.put("upload.bin", request.stream, {
* contentLength: Number(request.headers["content-length"] ?? 0),
* });
* ```
*
* ### Custom Domains
*
* Attach one or more custom domains to serve bucket objects from a hostname
* you control. The domain's zone must already exist in your Cloudflare
* account; the zone is inferred from the hostname when omitted, or you can
* pass a `Cloudflare.Zone.Zone` resource, a zone ID, or any hostname inside the
* zone via the `zone` field.
*
* **Example:** Single custom domain
* ```typescript
* const bucket = yield* Cloudflare.R2.Bucket("MyBucket", {
* domains: [{ name: "assets.example.com" }],
* });
* ```
*
* **Example:** Multiple custom domains
* ```typescript
* const bucket = yield* Cloudflare.R2.Bucket("MyBucket", {
* domains: [
* { name: "assets.example.com" },
* { name: "static.example.com" },
* ],
* });
* ```
*
* **Example:** Disable a custom domain without removing it
* ```typescript
* const bucket = yield* Cloudflare.R2.Bucket("MyBucket", {
* domains: [{ name: "assets.example.com", enabled: false }],
* });
* ```
*
* **Example:** Custom domain with explicit zone and TLS settings
* ```typescript
* const zone = yield* Cloudflare.Zone.Zone("ExampleZone", {
* name: "example.com",
* });
*
* const bucket = yield* Cloudflare.R2.Bucket("MyBucket", {
* domains: [
* {
* name: "assets.example.com",
* zone,
* minTLS: "1.2",
* },
* ],
* });
* ```
*
* ### Public Development URL
*
* Enable Cloudflare's managed `r2.dev` domain so objects are publicly
* readable without attaching a custom domain. The hostname is reported
* on `publicDomain`. This endpoint is rate-limited and intended for
* non-production use — use `domains` for production public access.
*
* **Example:** Enable public access at r2.dev
* ```typescript
* const bucket = yield* Cloudflare.R2.Bucket("MyBucket", {
* publicAccess: true,
* });
* // objects are at https://${bucket.publicDomain}/<key>
* ```
*
* **Example:** Disable public access
* ```typescript
* const bucket = yield* Cloudflare.R2.Bucket("MyBucket", {
* publicAccess: false,
* });
* ```
*
* ### Object Lifecycle Rules
*
* Configure lifecycle rules to automatically delete objects, abort
* incomplete multipart uploads, or transition objects to InfrequentAccess
* storage. Pass an empty array (or omit) to clear all rules. See the
* [Cloudflare R2 docs](https://developers.cloudflare.com/r2/buckets/object-lifecycles/)
* for details and limits (max 1000 rules per bucket).
*
* **Example:** Delete objects 30 days after upload
* ```typescript
* const bucket = yield* Cloudflare.R2.Bucket("MyBucket", {
* lifecycleRules: [
* {
* id: "expire-old-objects",
* deleteObjectsTransition: {
* condition: { type: "Age", maxAge: 60 * 60 * 24 * 30 },
* },
* },
* ],
* });
* ```
*
* **Example:** Transition to InfrequentAccess after 60 days, delete after 365
* ```typescript
* const bucket = yield* Cloudflare.R2.Bucket("MyBucket", {
* lifecycleRules: [
* {
* id: "archive-then-delete",
* prefix: "logs/",
* storageClassTransitions: [
* {
* condition: { type: "Age", maxAge: 60 * 60 * 24 * 60 },
* storageClass: "InfrequentAccess",
* },
* ],
* deleteObjectsTransition: {
* condition: { type: "Age", maxAge: 60 * 60 * 24 * 365 },
* },
* },
* ],
* });
* ```
*
* **Example:** Abort incomplete multipart uploads after 7 days
* ```typescript
* const bucket = yield* Cloudflare.R2.Bucket("MyBucket", {
* lifecycleRules: [
* {
* id: "abort-stale-uploads",
* abortMultipartUploadsTransition: {
* condition: { type: "Age", maxAge: 60 * 60 * 24 * 7 },
* },
* },
* ],
* });
* ```
*
* ### CORS
*
* Configure CORS rules so browsers can make cross-origin requests against
* the bucket's public (custom domain / r2.dev) or S3 API endpoints. Pass an
* empty array (or omit) to remove the CORS configuration. See the
* [Cloudflare R2 docs](https://developers.cloudflare.com/r2/buckets/cors/)
* for details.
*
* **Example:** Allow cross-origin reads from any origin
* ```typescript
* const bucket = yield* Cloudflare.R2.Bucket("MyBucket", {
* cors: [
* {
* allowedMethods: ["GET", "HEAD"],
* allowedOrigins: ["*"],
* },
* ],
* });
* ```
*
* **Example:** Browser range reads (e.g. PMTiles map tiles)
* ```typescript
* const bucket = yield* Cloudflare.R2.Bucket("MyBucket", {
* domains: [{ name: "tiles.example.com" }],
* cors: [
* {
* allowedMethods: ["GET", "HEAD"],
* allowedOrigins: ["https://map.example.com"],
* allowedHeaders: ["range", "if-match"],
* exposeHeaders: ["etag", "content-range"],
* maxAgeSeconds: 3600,
* },
* ],
* });
* ```
*
* **Example:** Allow uploads from a web app
* ```typescript
* const bucket = yield* Cloudflare.R2.Bucket("MyBucket", {
* cors: [
* {
* allowedMethods: ["GET", "PUT", "POST"],
* allowedOrigins: ["https://app.example.com"],
* allowedHeaders: ["content-type"],
* exposeHeaders: ["etag"],
* },
* ],
* });
* ```
*
* ### Bucket Locks
*
* Lock rules make objects write-once: while a rule's condition holds, R2
* refuses to delete or overwrite any object under the rule's prefix,
* whoever signs the request. `Indefinite` locks never lapse, so a bucket
* with indefinitely locked objects can never be emptied or deleted. A
* bucket that never declares `locks` keeps its rules unmanaged; pass an
* empty array (or drop `locks` after declaring it) to remove them. See the
* [Cloudflare R2 docs](https://developers.cloudflare.com/r2/buckets/bucket-locks/)
* for details.
*
* **Example:** Write-once landing zone
* ```typescript
* const lake = yield* Cloudflare.R2.Bucket("Lake", {
* locks: [
* {
* id: "raw-write-once",
* enabled: true,
* prefix: "raw/",
* condition: { type: "Indefinite" },
* },
* ],
* });
* ```
*
* **Example:** Retain logs for 90 days
* ```typescript
* const audit = yield* Cloudflare.R2.Bucket("Audit", {
* locks: [
* {
* id: "retain-logs",
* enabled: true,
* prefix: "logs/",
* condition: { type: "Age", maxAgeSeconds: 60 * 60 * 24 * 90 },
* },
* ],
* });
* ```
*
* ### Local Uploads
*
* Local Uploads writes uploaded objects near the client and replicates them
* to the bucket's region asynchronously, cutting upload latency for clients
* far from the bucket. It is not available for jurisdiction-restricted
* buckets. See the
* [Cloudflare R2 docs](https://developers.cloudflare.com/r2/buckets/local-uploads/)
* for details.
*
* **Example:** Enable Local Uploads
* ```typescript
* const uploads = yield* Cloudflare.R2.Bucket("Uploads", {
* localUploads: true,
* });
* ```
*
* ### Deleting a Bucket
*
* R2 refuses to delete a bucket that still has objects in it, and alchemy
* does not bypass that refusal: destroying a non-empty bucket fails with
* `BucketNotEmpty` and both the bucket and its objects survive. Opt into
* emptying the bucket first with `forceDestroy` for buckets whose contents
* are disposable.
*
* **Example:** Empty the bucket on destroy
* ```typescript
* const cache = yield* Cloudflare.R2.Bucket("Cache", {
* forceDestroy: true,
* });
* ```
*
* **Example:** Keep the bucket even when the stack goes away
* ```typescript
* import * as RemovalPolicy from "alchemy/RemovalPolicy";
*
* const uploads = yield* Cloudflare.R2.Bucket("Uploads").pipe(
* RemovalPolicy.retain(),
* );
* ```
*
* @resource
* @product R2
* @category Storage & Databases
*/
export const Bucket = Resource<Bucket>("Cloudflare.R2.Bucket", {
aliases: ["Cloudflare.R2Bucket"],
});
export declare namespace Bucket {
export type StorageClass = "Standard" | "InfrequentAccess";
export type Jurisdiction = "default" | "eu" | "us" | "fedramp";
export type Location = "apac" | "eeur" | "enam" | "weur" | "wnam" | "oc";
export type LifecycleRule = {
id: string;
enabled: boolean;
prefix: string;
abortMultipartUploadsTransition:
| { condition: { type: "Age"; maxAge: number } | undefined }
| undefined;
deleteObjectsTransition: { condition: BucketLifecycleCondition | undefined } | undefined;
storageClassTransitions:
| {
condition: BucketLifecycleCondition;
storageClass: "InfrequentAccess";
}[]
| undefined;
};
export type CorsRule = {
id: string | undefined;
allowedMethods: ("GET" | "PUT" | "POST" | "DELETE" | "HEAD")[];
allowedOrigins: string[];
allowedHeaders: string[] | undefined;
exposeHeaders: string[] | undefined;
maxAgeSeconds: number | undefined;
};
export type LockRule = {
id: string;
enabled: boolean;
prefix: string;
condition: BucketLockCondition;
};
export type CustomDomain = {
domain: string;
zoneId: string | undefined;
enabled: boolean;
ciphers: string[] | undefined;
minTLS: "1.0" | "1.1" | "1.2" | "1.3" | undefined;
status:
| {
ownership: "pending" | "active" | "deactivated" | "blocked" | "error" | "unknown";
ssl: "initializing" | "pending" | "active" | "deactivated" | "error" | "unknown";
}
| undefined;
};
}
export const ProviderLive = () =>
Provider.effect(
Bucket,
Effect.gen(function* () {
const emptyBucket = Effect.fn(function* (
bucketName: string,
jurisdiction: Bucket.Jurisdiction,
) {
const { accountId } = yield* yield* CloudflareEnvironment;
return yield* r2.listObjects
.items({
accountId,
bucketName,
cfR2Jurisdiction: jurisdiction,
perPage: 1000,
})
.pipe(
Stream.filter(
(o): o is typeof o & { key: string } => typeof o.key === "string" && o.key !== "",
),
Stream.map((o) => o.key),
Stream.runForEachArray((chunk) =>
r2.deleteObjects({
accountId,
bucketName,
cfR2Jurisdiction: jurisdiction,
body: [...chunk],
}),
),
Effect.catchTag("NoSuchBucket", () => Effect.void),
);
});
const createBucketName = (id: string, name: string | undefined) =>
Effect.gen(function* () {
if (name) return name;
return (yield* createPhysicalName({
id,
maxLength: 63,
})).toLowerCase();
});
const normalizeLocation = (
location: string | undefined | null,
): Bucket.Location | undefined => {
if (!location) return undefined;
return location.toLowerCase() as Bucket.Location;
};
const listCustomDomains = Effect.fn(function* (
bucketName: string,
jurisdiction: Bucket.Jurisdiction,
// `NoSuchBucket` after a *create* is endpoint-consistency lag worth
// retrying. During *enumeration* (`list`), a bucket that 404s is one a
// parallel suite just deleted — it's genuinely gone, so retrying the
// consistency schedule only burns ~3s per churned bucket and is what
// pushes an account-wide `list` past its timeout. Default to retrying
// (the reconcile path); opt out for enumeration.
options?: { retryMissing?: boolean },
) {
const { accountId } = yield* yield* CloudflareEnvironment;
const fetch = r2.listBucketDomainCustoms({
accountId,
bucketName,
jurisdiction,
});
return yield* (
options?.retryMissing === false
? fetch
: fetch.pipe(
Effect.retry({
while: (e) => e._tag === "NoSuchBucket",
schedule: r2BucketEndpointConsistencySchedule,
}),
)
).pipe(
Effect.map((response) => response.domains.map(toCustomDomainAttributes)),
Effect.catchTag("NoSuchBucket", () => Effect.undefined),
);
});
const reconcileCustomDomains = (
bucketName: string,
jurisdiction: Bucket.Jurisdiction,
desired: BucketCustomDomain[],
previous: Bucket.CustomDomain[],
) =>
Effect.gen(function* () {
const { accountId } = yield* yield* CloudflareEnvironment;
const observed = yield* listCustomDomains(bucketName, jurisdiction);
if (!observed) {
return yield* new BucketOperationFailed({
message: `Cannot reconcile custom domains for missing R2 bucket "${bucketName}"`,
});
}
const observedByDomain = new Map(observed.map((domain) => [domain.domain, domain]));
const desiredDomains = new Set(desired.map((domain) => domain.name));
// Remove domains that are no longer desired. Domains that keep the
// same hostname but move zones are intentionally skipped here and
// handled in the per-domain flow below.
yield* Effect.forEach(
previous,
(previousDomain) =>
desiredDomains.has(previousDomain.domain)
? Effect.void
: r2
.deleteBucketDomainCustom({
accountId,
bucketName,
domain: previousDomain.domain,
jurisdiction,
})
.pipe(Effect.catchTag(["DomainNotFound", "NoSuchBucket"], () => Effect.void)),
{ concurrency: "unbounded" },
);
const applied = yield* Effect.forEach(
desired,
(domain) =>
Effect.gen(function* () {
const zoneId = yield* Zone.resolveZoneId({
accountId,
zone: domain.zone,
hostname: domain.name,
});
const observedDomain = observedByDomain.get(domain.name);
if (observedDomain && sameCustomDomainConfig(observedDomain, domain, zoneId)) {
return observedDomain;
}
if (observedDomain && observedDomain.zoneId !== zoneId) {
// Cloudflare does not mutate the zone for an existing custom
// domain. This is not a duplicate of the stale-domain prune
// above: the hostname is still desired, so that prune skips it
// and this branch deletes only to recreate it in the new zone.
yield* r2
.deleteBucketDomainCustom({
accountId,
bucketName,
domain: domain.name,
jurisdiction,
})
.pipe(Effect.catchTag(["DomainNotFound", "NoSuchBucket"], () => Effect.void));
}
if (!observedDomain || observedDomain.zoneId !== zoneId) {
const created = yield* r2
.createBucketDomainCustom({
accountId,
bucketName,
jurisdiction,
domain: domain.name,
enabled: domain.enabled ?? true,
zoneId,
ciphers: domain.ciphers,
minTLS: domain.minTLS,
})
.pipe(
Effect.retry({
while: (e) => e._tag === "NoSuchBucket",
schedule: r2BucketEndpointConsistencySchedule,
}),
Effect.retry({
while: (e) => e._tag === "CustomDomainInUse",
schedule: r2CustomDomainConflictSchedule,
}),
);
return toCustomDomainAttributes({ ...created, zoneId });
}
const updated = yield* r2
.updateBucketDomainCustom({
accountId,
bucketName,
domain: domain.name,
jurisdiction,
enabled: domain.enabled ?? true,
ciphers: domain.ciphers,
minTLS: domain.minTLS,
})
.pipe(
Effect.retry({
while: (e) => e._tag === "NoSuchBucket",
schedule: r2BucketEndpointConsistencySchedule,
}),
);
return toCustomDomainAttributes({
...updated,
enabled: updated.enabled ?? domain.enabled ?? true,
zoneId,
});
}),
{ concurrency: "unbounded" },
);
return applied.sort((a, b) => a.domain.localeCompare(b.domain));
});
const listManagedDomain = Effect.fn(function* (
bucketName: string,
jurisdiction: Bucket.Jurisdiction,
options?: { retryMissing?: boolean },
) {
const { accountId } = yield* yield* CloudflareEnvironment;
const fetch = r2.listBucketDomainManageds({
accountId,
bucketName,
jurisdiction,
});
return yield* (
options?.retryMissing === false
? fetch
: fetch.pipe(
Effect.retry({
while: (e) => e._tag === "NoSuchBucket",
schedule: r2BucketEndpointConsistencySchedule,
}),
)
).pipe(
// The hostname exists whether or not public access is on; a
// disabled domain serves 401, so only report it while enabled.
Effect.map((response) => (response.enabled ? response.domain : undefined)),
Effect.catchTag("NoSuchBucket", () => Effect.undefined),
);
});
const reconcileManagedDomain = (
bucketName: string,
jurisdiction: Bucket.Jurisdiction,
desired: boolean,
) =>
Effect.gen(function* () {
const { accountId } = yield* yield* CloudflareEnvironment;
const observed = yield* r2
.listBucketDomainManageds({
accountId,
bucketName,
jurisdiction,
})
.pipe(
Effect.retry({
while: (e) => e._tag === "NoSuchBucket",
schedule: r2BucketEndpointConsistencySchedule,
}),
);
if (observed.enabled === desired) {
return desired ? observed.domain : undefined;
}
const updated = yield* r2
.putBucketDomainManaged({
accountId,
bucketName,
enabled: desired,
jurisdiction,
})
.pipe(
Effect.retry({
while: (e) => e._tag === "NoSuchBucket",
schedule: r2BucketEndpointConsistencySchedule,
}),
);
return updated.enabled ? updated.domain : undefined;
});
// R2's `listBuckets` is not modelled as paginated by distilled and its
// response omits a continuation cursor, so paginate exhaustively with the
// `startAfter` query param: keep fetching full pages (capped at 1000)
// until a short page signals the end.
const listBucketsInJurisdiction = (accountId: string, jurisdiction: Bucket.Jurisdiction) =>
Effect.gen(function* () {
const all: {
name: string;
jurisdiction: Bucket.Jurisdiction;
storageClass: Bucket.StorageClass;
location: Bucket.Location | undefined;
}[] = [];
let startAfter: string | undefined = undefined;
const perPage = 1000;
for (;;) {
const response: r2.ListBucketsResponse = yield* r2.listBuckets({
accountId,
jurisdiction,
perPage,
startAfter,
});
const raw = response.buckets ?? [];
const page = raw.filter(
(b): b is typeof b & { name: string } => typeof b.name === "string" && b.name !== "",
);
for (const b of page) {
all.push({
name: b.name,
jurisdiction: (b.jurisdiction ?? jurisdiction) as Bucket.Jurisdiction,
storageClass: (b.storageClass ?? "Standard") as Bucket.StorageClass,
location: normalizeLocation(b.location),
});
}
// Terminate on the RAW page length — the filtered length can be
// shorter on a full page (nameless entries), which would end the
// walk early and silently drop the remaining buckets.
if (raw.length < perPage || page.length === 0) break;
startAfter = page[page.length - 1].name;
}
return all;
});
const reconcileLifecycleRules = (
bucketName: string,
jurisdiction: Bucket.Jurisdiction,
desired: BucketLifecycleRule[],
) =>
Effect.gen(function* () {
const { accountId } = yield* yield* CloudflareEnvironment;
const observed = yield* r2
.getBucketLifecycle({
accountId,
bucketName,
jurisdiction,
})
.pipe(
Effect.retry({
while: (e) => e._tag === "NoSuchBucket",
schedule: r2BucketEndpointConsistencySchedule,
}),
);
const observedRules = (observed.rules ?? []).map(toLifecycleRule);
const desiredRules = desired.map(normalizeLifecycleRule);
if (deepEqual(observedRules, desiredRules)) {
return desiredRules;
}
yield* r2
.putBucketLifecycle({
accountId,
bucketName,
jurisdiction,
rules: desired.map(toLifecyclePutPayload),
})
.pipe(
Effect.retry({
while: (e) => e._tag === "NoSuchBucket",
schedule: r2BucketEndpointConsistencySchedule,
}),
);
return desiredRules;
});
const reconcileCorsRules = (
bucketName: string,
jurisdiction: Bucket.Jurisdiction,
desired: BucketCorsRule[],
) =>
Effect.gen(function* () {
const { accountId } = yield* yield* CloudflareEnvironment;
const observed = yield* r2
.getBucketCors({
accountId,
bucketName,
jurisdiction,
})
.pipe(
Effect.map((response) => (response.rules ?? []).map(toCorsRule)),
// A bucket with no CORS configuration is a typed error, not an
// empty rule list — normalize it to [] for the diff below.
Effect.catchTag("NoCorsConfiguration", () => Effect.succeed([] as Bucket.CorsRule[])),
Effect.retry({
while: (e) => e._tag === "NoSuchBucket",
schedule: r2BucketEndpointConsistencySchedule,
}),
);
const desiredRules = desired.map(normalizeCorsRule);
if (deepEqual(observed, desiredRules)) {
return desiredRules;
}
if (desiredRules.length === 0) {
yield* r2
.deleteBucketCors({
accountId,
bucketName,
jurisdiction,
})
.pipe(
Effect.retry({
while: (e) => e._tag === "NoSuchBucket",
schedule: r2BucketEndpointConsistencySchedule,
}),
);
return desiredRules;
}
yield* r2
.putBucketCors({
accountId,
bucketName,
jurisdiction,
rules: desired.map(toCorsPutPayload),
})
.pipe(
Effect.retry({
while: (e) => e._tag === "NoSuchBucket",
schedule: r2BucketEndpointConsistencySchedule,
}),
);
return desiredRules;
});
// PUT replaces the bucket's whole rule set, so `[]` clears it.
const reconcileLockRules = (
bucketName: string,
jurisdiction: Bucket.Jurisdiction,
desired: BucketLockRule[],
) =>
Effect.gen(function* () {
const { accountId } = yield* yield* CloudflareEnvironment;
const observed = yield* r2
.getBucketLock({
accountId,
bucketName,
jurisdiction,
})
.pipe(
Effect.map((response) => sortLockRules((response.rules ?? []).map(toLockRule))),
Effect.retry({
while: (e) => e._tag === "NoSuchBucket",
schedule: r2BucketEndpointConsistencySchedule,
}),
);
// R2 returns rules sorted by id, not in the order they were PUT,
// so compare (and report) both sides in id order.
const desiredRules = sortLockRules(
desired.map((rule): Bucket.LockRule => ({
...rule,
prefix: rule.prefix ?? "",
})),
);
if (deepEqual(observed, desiredRules)) {
return desiredRules;
}
yield* r2
.putBucketLock({
accountId,
bucketName,
jurisdiction,
rules: desiredRules,
})
.pipe(
Effect.retry({
while: (e) => e._tag === "NoSuchBucket",
schedule: r2BucketEndpointConsistencySchedule,
}),
);
return desiredRules;
});
const reconcileLocalUploads = Effect.fn(function* (
bucketName: string,
jurisdiction: Bucket.Jurisdiction,
desired: boolean,
) {
// Local Uploads has no jurisdiction-scoped endpoint: Cloudflare does
// not offer it on jurisdiction-restricted buckets, so such a bucket
// is always disabled (reconcile refuses `true` up front).
if (jurisdiction !== "default") return false;
const { accountId } = yield* yield* CloudflareEnvironment;
const observed = yield* r2.getBucketLocalUploads({ accountId, bucketName }).pipe(
Effect.retry({
while: (e) => e._tag === "NoSuchBucket",
schedule: r2BucketEndpointConsistencySchedule,
}),
);
if (observed.enabled === desired) return desired;
// The PUT response omits `enabled`; a successful PUT applied `desired`.
yield* r2.putBucketLocalUploads({ accountId, bucketName, enabled: desired }).pipe(
Effect.retry({
while: (e) => e._tag === "NoSuchBucket",
schedule: r2BucketEndpointConsistencySchedule,
}),
);
return desired;
});
return {
stables: ["bucketName", "accountId"],
list: () =>
Effect.gen(function* () {
const { accountId } = yield* yield* CloudflareEnvironment;
// R2 buckets are account-scoped but partitioned by jurisdiction, so
// enumerate each jurisdiction. Accounts not entitled to a given
// jurisdiction (e.g. `fedramp`) reject the route — treat as empty.
const jurisdictions: Bucket.Jurisdiction[] = ["default", "eu", "us", "fedramp"];
const perJurisdiction = yield* Effect.forEach(
jurisdictions,
(jurisdiction) =>
listBucketsInJurisdiction(accountId, jurisdiction).pipe(
// An account not entitled to a jurisdiction rejects the list
// route with `Forbidden` ("Access Denied") or `InvalidRoute`
// — there are simply no buckets there, so treat as empty.
Effect.catchTag(["InvalidRoute", "Forbidden"], () => Effect.succeed([])),
),
{ concurrency: jurisdictions.length },
);
const buckets = perJurisdiction.flat();
// Hydrate each bucket into the exact `read` Attributes shape so the
// result is directly usable by `delete` (which needs `domains` to
// tear down custom domains).
return yield* Effect.forEach(
buckets,
(bucket) =>
Effect.gen(function* () {
// The hydration reads are independent — issue them
// concurrently so each bucket costs one round-trip of wall
// clock instead of four (a large leaked-bucket census can
// otherwise blow the nuke scan's per-provider timeout).
const [domains, lifecycleRules, cors, publicDomain] = yield* Effect.all(
[
listCustomDomains(bucket.name, bucket.jurisdiction, {
retryMissing: false,
}).pipe(Effect.map((d) => d ?? [])),
r2
.getBucketLifecycle({
accountId,
bucketName: bucket.name,
jurisdiction: bucket.jurisdiction,
})
.pipe(
Effect.map((observed) => (observed.rules ?? []).map(toLifecycleRule)),
Effect.catchTag("NoSuchBucket", () =>
Effect.succeed([] as Bucket.LifecycleRule[]),
),
),
r2
.getBucketCors({
accountId,
bucketName: bucket.name,
jurisdiction: bucket.jurisdiction,
})
.pipe(
Effect.map((observed) => (observed.rules ?? []).map(toCorsRule)),
Effect.catchTag(["NoSuchBucket", "NoCorsConfiguration"], () =>
Effect.succeed([] as Bucket.CorsRule[]),
),
),
listManagedDomain(bucket.name, bucket.jurisdiction, {
retryMissing: false,
}),
] as const,
{ concurrency: 4 },
);
return {
bucketName: bucket.name,
storageClass: bucket.storageClass,
jurisdiction: bucket.jurisdiction,
location: bucket.location,
accountId,
domains,
lifecycleRules,
cors,
locks: undefined,
localUploads: undefined,
publicDomain,
};
}).pipe(
// The custom-domain endpoint intermittently 500s ("Failed to
// access or modify the bucket policy"), and some buckets 500
// PERSISTENTLY. The blanket Cloudflare retry policy already
// retries each call's transient blips; don't stack another
// retry here (the budgets multiply into minutes per bucket).
// A bucket that still 500s must not abort the account-wide
// enumeration (nuke would then see ZERO buckets) — degrade
// it to an un-hydrated shape; delete can still tear the
// bucket down.
Effect.catchTag("InternalServerError", () =>
Effect.succeed({
bucketName: bucket.name,
storageClass: bucket.storageClass,
jurisdiction: bucket.jurisdiction,
location: bucket.location,
accountId,
domains: [] as Bucket.CustomDomain[],
lifecycleRules: [] as Bucket.LifecycleRule[],
cors: [] as Bucket.CorsRule[],
locks: undefined,
localUploads: undefined,
publicDomain: undefined,
}),
),
),
{ concurrency: 10 },
);
}),
diff: Effect.fn(function* ({ id, olds = {}, news = {}, output }) {
if (!isResolved(news)) return undefined;
const { accountId } = yield* yield* CloudflareEnvironment;
const oldName = output?.bucketName ?? (yield* createBucketName(id, olds.name));
// Auto-generated names are engine-owned: the deployed name stays
// authoritative even if the generator would name this id
// differently today. Only an explicit user-provided name can
// force a replace.
const name = news.name ?? oldName;
const oldJurisdiction = output?.jurisdiction ?? olds.jurisdiction ?? "default";
const oldStorageClass = output?.storageClass ?? olds.storageClass ?? "Standard";
if (
(output?.accountId ?? accountId) !== accountId ||
oldName !== name ||
oldJurisdiction !== (news.jurisdiction ?? "default") ||
olds.locationHint !== news.locationHint
) {
return { action: "replace" } as const;
}
if (oldStorageClass !== (news.storageClass ?? "Standard")) {
return {
action: "update",
// `accountId` is always stable across an update (a name/account
// change is a `replace`); keep it now that `diff.stables`
// overrides `provider.stables` rather than merging with it.
stables: oldName === name ? ["bucketName", "accountId"] : ["accountId"],
} as const;
}
if (!deepEqual(olds.domains, news.domains)) {
return { action: "update" } as const;
}
if (!deepEqual(olds.lifecycleRules, news.lifecycleRules)) {
return { action: "update" } as const;
}
if (!deepEqual(olds.cors, news.cors)) {
return { action: "update" } as const;
}
if (!deepEqual(olds.locks, news.locks)) {
return { action: "update" } as const;
}
if ((olds.publicAccess ?? false) !== (news.publicAccess ?? false)) {
return { action: "update" } as const;
}
if (olds.localUploads !== news.localUploads) {
return { action: "update" } as const;
}
}),
reconcile: Effect.fn(function* ({ id, news = {}, olds, output }) {
const { accountId } = yield* yield* CloudflareEnvironment;
// Prefer the deployed name: regenerating would target a different
// bucket if the generator's output for this id ever drifts.
const name = output?.bucketName ?? (yield* createBucketName(id, news.name));
const acct = output?.accountId ?? accountId;
const jurisdiction = output?.jurisdiction ?? news.jurisdiction ?? "default";
// Refuse before creating anything, so a rejected deploy leaves no
// bucket behind.
if (news.localUploads === true && jurisdiction !== "default") {
return yield* new LocalUploadsUnsupported({
bucketName: name,
jurisdiction,
message: `R2 Local Uploads is not available for jurisdiction-restricted bucket "${name}" (jurisdiction "${jurisdiction}")`,
});
}
// Observe — fetch the bucket. R2 reports a deleted bucket as
// `NoSuchBucket`; tolerate that so the reconciler falls
// through to the create path.
let observed = yield* r2
.getBucket({
accountId: acct,
bucketName: name,
jurisdiction,
})
.pipe(Effect.catchTag("NoSuchBucket", () => Effect.undefined));
// Ensure — create if missing. R2 reports a concurrent create
// (or partial state-persistence failure) as
// `BucketAlreadyExists`; tolerate by re-fetching the bucket.
if (!observed) {
observed = yield* r2
.createBucket({
accountId: acct,
name,
storageClass: news.storageClass,
jurisdiction: news.jurisdiction,
locationHint: news.locationHint,
})
.pipe(
Effect.catchTag("BucketAlreadyExists", () =>
r2
.getBucket({
accountId: acct,
bucketName: name,
jurisdiction: news.jurisdiction,
})
.pipe(
// The create lost a race, but the winning create may not
// be readable yet — ride out the consistency lag.
Effect.retry({
while: (e) => e._tag === "NoSuchBucket",
schedule: r2BucketEndpointConsistencySchedule,
}),
),
),
);
}
// Sync — storage class is the only mutable bucket property
// (location and jurisdiction are immutable; the diff flags those
// as `replace`). PATCH carries the class in the
// `cf-r2-storage-class` header. Address the bucket by the
// RESOLVED name, never `observed.name` — a response missing the
// name would collapse the URI to the collection path, which the
// control plane rejects with `PATCH not supported for requested
// URI`. Only patch when the desired class drifts from observed.
const desiredStorageClass = news.storageClass ?? "Standard";
const observedStorageClass = observed.storageClass ?? "Standard";
if (observedStorageClass !== desiredStorageClass) {
observed = yield* r2
.patchBucket({
accountId: acct,
bucketName: name,
storageClass: desiredStorageClass,
jurisdiction: observed.jurisdiction ?? jurisdiction,
})
.pipe(
// The patch endpoint can briefly 404 a freshly-created bucket
// even after `getBucket` already sees it.
Effect.retry({
while: (e) => e._tag === "NoSuchBucket",
schedule: r2BucketEndpointConsistencySchedule,
}),
);
}
const attrs = {
bucketName: observed.name ?? name,
// Distilled widened generated string enums to open unions.
storageClass: (observed.storageClass ?? "Standard") as Bucket.StorageClass,
jurisdiction: (observed.jurisdiction ?? "default") as Bucket.Jurisdiction,
location: normalizeLocation(observed.location),
accountId: acct,
};
const domains = yield* reconcileCustomDomains(
attrs.bucketName,
attrs.jurisdiction,
news.domains ?? [],
output?.domains ?? [],
);
const lifecycleRules = yield* reconcileLifecycleRules(
attrs.bucketName,
attrs.jurisdiction,
news.lifecycleRules ?? [],
);
const cors = yield* reconcileCorsRules(
attrs.bucketName,
attrs.jurisdiction,
news.cors ?? [],
);
// Locks are managed only once the props name them: clearing rules
// a stack never declared would drop protection someone else set.
// Removing `locks` after declaring it still clears them.
const locks =
news.locks !== undefined || olds?.locks !== undefined
? yield* reconcileLockRules(attrs.bucketName, attrs.jurisdiction, news.locks ?? [])
: undefined;
// Like locks, Local Uploads is managed only once the props name it.
const localUploads =
news.localUploads !== undefined || olds?.localUploads !== undefined
? yield* reconcileLocalUploads(
attrs.bucketName,
attrs.jurisdiction,
news.localUploads ?? false,
)
: undefined;
const publicDomain = yield* reconcileManagedDomain(
attrs.bucketName,
attrs.jurisdiction,
news.publicAccess ?? false,
);
return {
...attrs,
domains,
lifecycleRules,
cors,
locks,
localUploads,
publicDomain,
};
}),
delete: Effect.fn(function* ({ olds = {}, output, force }) {
yield* Effect.forEach(
output.domains ?? [],
(domain) =>
r2
.deleteBucketDomainCustom({
accountId: output.accountId,
bucketName: output.bucketName,
domain: domain.domain,
jurisdiction: output.jurisdiction,
})
.pipe(Effect.catchTag(["DomainNotFound", "NoSuchBucket"], () => Effect.void)),
{ concurrency: "unbounded" },
);
// Whether we may destroy the bucket's CONTENTS.
// - `olds.forceDestroy` — the user opted in on the resource props.
// - `force` — set only by `alchemy unsafe nuke`, an explicitly
// operator-confirmed account teardown. Nuke enumerates buckets
// straight from the cloud (its `olds` is Attributes, not Props),
// so `forceDestroy` is never present there.
//
// Without either, the objects are left alone and R2's own refusal
// to delete a non-empty bucket (`BucketNotEmpty`) stands — that
// refusal is the data protection users rely on, and emptying the
// bucket to get past it is how a stack teardown turns into
// irreversible data loss (#1248).
const destroyContents = olds.forceDestroy === true || force === true;
if (destroyContents) {
yield* emptyBucket(output.bucketName, output.jurisdiction);
}
const deleteBucket = r2
.deleteBucket({
accountId: output.accountId,
bucketName: output.bucketName,
jurisdiction: output.jurisdiction,
})
.pipe(Effect.catchTag("NoSuchBucket", () => Effect.void));
if (!destroyContents) {
return yield* deleteBucket;
}
// A writer that outlives the emptying pass (a Durable Object's
// alarm finishing a job while the stack tears down) can land an
// object between the sweep and the delete: re-empty and retry,
// bounded.
const deleteEmptied = deleteBucket.pipe(
Effect.catchTag("BucketNotEmpty", (error) =>
Effect.sleep("2 seconds").pipe(
Effect.andThen(emptyBucket(output.bucketName, output.jurisdiction)),
Effect.andThen(Effect.fail(error)),
),
),
Effect.retry({
while: (error) => error._tag === "BucketNotEmpty",
times: 5,
}),
);
yield* deleteBucket.pipe(
// Incomplete multipart uploads also hold a bucket, and the
// object listing doesn't show them. Only R2's S3 API can abort
// them, which works when alchemy is authenticated with an API
// token — try that once, best effort, then re-empty and retry.
Effect.catchTag("BucketNotEmpty", () =>
Effect.gen(function* () {
const result = yield* abortMultipartUploads(
output.accountId,
output.bucketName,
output.jurisdiction,
);
if ("aborted" in result && result.aborted > 0) {
yield* Effect.logInfo(
`Aborted ${result.aborted} incomplete multipart upload(s) in R2 bucket ${output.bucketName}`,
);
}
yield* emptyBucket(output.bucketName, output.jurisdiction);
yield* deleteEmptied.pipe(
Effect.catchTag("BucketNotEmpty", (error) =>
Effect.fail(
new BucketNotEmpty({
bucketName: output.bucketName,
message:
`${error.message} forceDestroy deleted every object, so incomplete ` +
`multipart uploads are likely holding it` +
("skipped" in result
? `, and alchemy could not abort them (${result.skipped}). `
: `. `) +
`Only R2's S3 API can abort them: authenticate alchemy with a ` +
`Cloudflare API token that has the "Workers R2 Storage Write" ` +
`permission and destroy again. Or add a lifecycle rule ` +
`{ abortMultipartUploadsTransition: { condition: { type: "Age", ` +
`maxAge: 86400 } } } and retry once R2 has applied it; R2 aborts ` +
`them on its own after 7 days.`,
}),
),
),
);
}),
),
);
}),
read: Effect.fn(function* ({ id, output, olds }) {
const { accountId } = yield* yield* CloudflareEnvironment;
const name = output?.bucketName ?? (yield* createBucketName(id, olds?.name));
const acct = output?.accountId ?? accountId;
return yield* r2
.getBucket({
accountId: acct,
bucketName: name,
jurisdiction: output?.jurisdiction ?? olds?.jurisdiction,
})
.pipe(
Effect.map((bucket) => ({
bucketName: bucket.name!,
// Distilled widened generated string enums to open unions.
storageClass: (bucket.storageClass ?? "Standard") as Bucket.StorageClass,
jurisdiction: (bucket.jurisdiction ?? "default") as Bucket.Jurisdiction,
location: normalizeLocation(bucket.location),
accountId: acct,
domains: output?.domains ?? [],
lifecycleRules: output?.lifecycleRules ?? [],
cors: output?.cors ?? [],
locks: output?.locks,
localUploads: output?.localUploads,
publicDomain: output?.publicDomain,
})),
Effect.catchTag("NoSuchBucket", () => Effect.undefined),
);
}),
};
}),
);
/**
* Local (dev) provider — the bucket is purely virtual: a `dev:`-prefixed
* bucket name keyed into the local workerd R2 simulator (data under
* `.alchemy/local/r2`). `toRuntimeBinding` lowers an `r2_bucket` binding
* whose bucket name is `dev:`-prefixed onto the local R2 service. R2 has no
* opaque id — the name IS the identity — so the `dev:` marker rides on the
* name (a `:` can never appear in a real R2 bucket name).
*
* Custom domains, lifecycle rules, CORS, lock rules, and the managed r2.dev
* domain are deploy-side concerns with no local behavior; the local
* attributes report them empty.
*/
export const ProviderLocal = () =>
Provider.succeed(Bucket, {
stables: ["accountId"],
diff: Effect.fn(function* ({ news = {}, output }) {
const accountId = yield* localAccountId;
if (!output?.bucketName) return { action: "update" } as const;
if (!isResolved(news)) return undefined;
if (output.accountId !== accountId) {
return { action: "replace" } as const;
}
// Fall through to the engine's default prop diff.
}),
read: Effect.fn(function* ({ output }) {
// Purely virtual — the persisted state row is the source of truth.
return output ?? undefined;
}),
reconcile: Effect.fn(function* ({ news = {}, output }) {
const accountId = yield* localAccountId;
return {
bucketName: output?.bucketName ?? generateLocalId(),
storageClass: (news.storageClass ?? "Standard") as Bucket.StorageClass,
jurisdiction: (news.jurisdiction ?? "default") as Bucket.Jurisdiction,
location: undefined,
accountId: output?.accountId ?? accountId,
domains: [],
lifecycleRules: [],
cors: [],
locks: undefined,
localUploads: undefined,
publicDomain: undefined,
};
}),
delete: Effect.fn(function* () {
// The simulator's on-disk data is keyed by the dev name; dropping the
// state row is enough — orphaned blobs are reclaimed with `.alchemy`.
}),
});
export const BucketProvider = () =>
ProviderLayer.dual(Bucket, {
local: () => ProviderLocal(),
live: () => ProviderLive(),
});
// R2 can make a newly-created bucket visible to `getBucket` before its
// sub-resource endpoints (custom domains, lifecycle) accept it. Retry only
// that narrow `NoSuchBucket` lag here; not-found sub-resources are still
// treated as terminal for idempotent deletes.
/**
* Local Uploads was requested on a jurisdiction-restricted bucket, which
* Cloudflare does not support.
*/
/**
* A `forceDestroy` delete emptied the bucket, but R2 still refuses to delete
* it — usually because incomplete multipart uploads hold it.
*/
class BucketNotEmpty extends Data.TaggedError("BucketNotEmpty")<{
bucketName: string;
message: string;
}> {}
export class LocalUploadsUnsupported extends Data.TaggedError("LocalUploadsUnsupported")<{
bucketName: string;
jurisdiction: Bucket.Jurisdiction;
message: string;
}> {}
const r2BucketEndpointConsistencySchedule = Schedule.max([
Schedule.exponential(100),
Schedule.recurs(5),
]);
// Distilled widened generated string enums to open unions (`string & {}`); the
// API only ever returns the known variants, narrowed in `toCustomDomainAttributes`.
type CustomDomainResponse = {
domain: string;
zoneId?: string | null;
enabled?: boolean | null;
ciphers?: string[] | null;
minTLS?: string | null;
status?: { ownership: string; ssl: string } | null;
};
const toCustomDomainAttributes = (domain: CustomDomainResponse): Bucket.CustomDomain => ({
domain: domain.domain,
zoneId: domain.zoneId ?? undefined,
enabled: domain.enabled ?? true,
ciphers: domain.ciphers ?? undefined,
minTLS: (domain.minTLS ?? undefined) as Bucket.CustomDomain["minTLS"],
status: (domain.status ?? undefined) as Bucket.CustomDomain["status"],
});
const sameCustomDomainConfig = (
observed: Bucket.CustomDomain | undefined,
desired: BucketCustomDomain,
zoneId: string,
): boolean =>
observed !== undefined &&
observed.zoneId === zoneId &&
observed.enabled === (desired.enabled ?? true) &&
deepEqual(observed.ciphers, desired.ciphers) &&
observed.minTLS === desired.minTLS;
type LifecycleRuleResponse = NonNullable<r2.GetBucketLifecycleResponse["rules"]>[number];
const toLifecycleRule = (rule: LifecycleRuleResponse): Bucket.LifecycleRule => ({
id: rule.id,
enabled: rule.enabled,
prefix: rule.conditions.prefix ?? "",
abortMultipartUploadsTransition: rule.abortMultipartUploadsTransition
? { condition: rule.abortMultipartUploadsTransition.condition ?? undefined }
: undefined,
deleteObjectsTransition: rule.deleteObjectsTransition
? { condition: rule.deleteObjectsTransition.condition ?? undefined }
: undefined,
storageClassTransitions: rule.storageClassTransitions ?? undefined,
});
const normalizeLifecycleRule = (rule: BucketLifecycleRule): Bucket.LifecycleRule => ({
id: rule.id,
enabled: rule.enabled ?? true,
prefix: rule.prefix ?? "",
abortMultipartUploadsTransition: rule.abortMultipartUploadsTransition
? { condition: rule.abortMultipartUploadsTransition.condition }
: undefined,
deleteObjectsTransition: rule.deleteObjectsTransition
? { condition: rule.deleteObjectsTransition.condition }
: undefined,
storageClassTransitions: rule.storageClassTransitions,
});
type CorsRuleResponse = NonNullable<r2.GetBucketCorsResponse["rules"]>[number];
const toCorsRule = (rule: CorsRuleResponse): Bucket.CorsRule => ({
id: rule.id ?? undefined,
// Distilled widened generated string enums to open unions.
allowedMethods: rule.allowed.methods as Bucket.CorsRule["allowedMethods"],
allowedOrigins: rule.allowed.origins,
allowedHeaders: rule.allowed.headers ?? undefined,
exposeHeaders: rule.exposeHeaders ?? undefined,
maxAgeSeconds: rule.maxAgeSeconds ?? undefined,
});
const normalizeCorsRule = (rule: BucketCorsRule): Bucket.CorsRule => ({
id: rule.id,
allowedMethods: rule.allowedMethods,
allowedOrigins: rule.allowedOrigins,
allowedHeaders: rule.allowedHeaders,
exposeHeaders: rule.exposeHeaders,
maxAgeSeconds: rule.maxAgeSeconds,
});
const toCorsPutPayload = (
rule: BucketCorsRule,
): NonNullable<r2.PutBucketCorsRequest["rules"]>[number] => ({
id: rule.id,
allowed: {
methods: rule.allowedMethods,
origins: rule.allowedOrigins,
headers: rule.allowedHeaders,
},
exposeHeaders: rule.exposeHeaders,
maxAgeSeconds: rule.maxAgeSeconds,
});