@volter/twin-cloudflare 0.1.0

package/dist/r2/src/semantics/buckets.js

@@ -0,0 +1,145 @@
+import { r2CustomDomains, removeR2CustomDomain } from "../../../src/cloudflare-r2.js";
+import { corsXml, doc, endpointOf, hostOf, lifecycleXml, locationConstraintOf, parseCors, parseLifecycle, x, xmlAnswer } from "../wire.js";
+export const accountOf = (ctx) => endpointOf(hostOf(ctx.call.request)).account;
+export const jurisdictionOf = (ctx) => endpointOf(hostOf(ctx.call.request)).jurisdiction;
+export const bucketId = (ctx, name) => `${accountOf(ctx)}:${name}`;
+/** A bucket as this endpoint reaches it: "When using a jurisdiction endpoint, you will not be able to access R2 resources
+ *  outside of that jurisdiction" (Data location), and a bucket in a jurisdiction is reached only through its endpoint. */
+export const bucketOf = (ctx, name) => {
+    const b = ctx.row('Bucket', bucketId(ctx, name));
+    return b && String(b.jurisdiction ?? 'default') === jurisdictionOf(ctx) ? b : undefined;
+};
+export const objectsIn = (ctx, name) => ctx.rowsRaw('Object').filter((o) => o.bucket_id === bucketId(ctx, name));
+// https://developers.cloudflare.com/r2/api/error-codes/: "10006 NoSuchBucket 404 The specified bucket does not exist."
+export const noSuchBucket = (ctx) => ctx.refuse({ status: 404, code: 'NoSuchBucket', message: 'The specified bucket does not exist.' });
+// Object lifecycles: "Buckets have a default lifecycle rule to expire multipart uploads seven days after initiation."
+// Where the documentation stops: the rule's ID is the twin's.
+export const DEFAULT_LIFECYCLE = [{ id: 'Default Multipart Abort Rule', enabled: true, prefix: '', abortMultipartDays: 7 }];
+// error-codes: "Bucket names must be 3-63 chars, lowercase alphanumeric and hyphens, start/end with alphanumeric."
+const BUCKET_NAME = /^[a-z0-9][a-z0-9-]{1,61}[a-z0-9]$/;
+// S3 API compatibility: "the region for an R2 bucket is auto. ... an empty value and us-east-1 will alias to the auto
+// region. This also applies to the LocationConstraint for the CreateBucket API."
+const REGIONS = new Set(['auto', '', 'us-east-1']);
+// Data location: "You can set the Location Hint via the LocationConstraint parameter using the S3 API", one of the hints
+// its table lists (wnam, enam, weur, eeur, apac, oc); the page's own example sends "WNAM"
+export const LOCATION_HINTS = new Set(['wnam', 'enam', 'weur', 'eeur', 'apac', 'oc']);
+// R2's aws-sdk-js-v3 page prints a ListBuckets answer with its Buckets and an Owner (`Owner: { DisplayName: '...', ID: '...' }`,
+// https://developers.cloudflare.com/r2/examples/aws/aws-sdk-js-v3/). Where the documentation stops: the page redacts the
+// owner's values, and the twin answers the account's id for both.
+async function listBuckets(ctx) {
+    const account = accountOf(ctx);
+    // an endpoint reaches the buckets of its own jurisdiction only (Data location); that it lists only those is the twin's reading
+    const mine = ctx.rowsRaw('Bucket').filter((b) => b.account_id === account && String(b.jurisdiction ?? 'default') === jurisdictionOf(ctx)).sort((a, b) => String(a.name).localeCompare(String(b.name)));
+    return xmlAnswer(doc('ListAllMyBucketsResult', [x('Buckets', mine.map((b) => x('Bucket', [x('Name', String(b.name)), x('CreationDate', String(b.creation_date))]))), x('Owner', [x('DisplayName', account), x('ID', account)])]));
+}
+async function headBucket(ctx) {
+    return bucketOf(ctx, String(ctx.call.params.Bucket)) ? ctx.raw(null) : ctx.raw(null, { status: 404 });
+}
+// S3 API compatibility: "the region for an R2 bucket is auto"
+async function getBucketLocation(ctx) {
+    if (!bucketOf(ctx, String(ctx.call.params.Bucket)))
+        return noSuchBucket(ctx);
+    return xmlAnswer('<?xml version="1.0" encoding="UTF-8"?><LocationConstraint xmlns="http://s3.amazonaws.com/doc/2006-03-01/">auto</LocationConstraint>');
+}
+// Data security: "All objects stored in R2, including their metadata, are encrypted at rest ... Objects are encrypted
+// using AES-256"; nothing configures it (PutBucketEncryption is unimplemented)
+async function getBucketEncryption(ctx) {
+    return (bucketOf(ctx, String(ctx.call.params.Bucket))
+        ? xmlAnswer(doc('ServerSideEncryptionConfiguration', [x('Rule', [x('ApplyServerSideEncryptionByDefault', [x('SSEAlgorithm', 'AES256')])])]))
+        : noSuchBucket(ctx));
+}
+async function getBucketCors(ctx) {
+    const b = bucketOf(ctx, String(ctx.call.params.Bucket));
+    if (!b)
+        return noSuchBucket(ctx);
+    const rules = (b.cors ?? []);
+    // Where R2's documentation stops: a bucket with no policy answers S3's code for it
+    return rules.length ? xmlAnswer(corsXml(rules)) : ctx.refuse({ status: 404, code: 'NoSuchCORSConfiguration', message: 'The CORS configuration does not exist' });
+}
+async function deleteBucketCors(ctx) {
+    const name = String(ctx.call.params.Bucket);
+    if (!bucketOf(ctx, name))
+        return noSuchBucket(ctx);
+    await ctx.write('Bucket', bucketId(ctx, name), { cors: [] }, 'DeleteBucketCors');
+    return ctx.raw(null, { status: 204 });
+}
+async function getBucketLifecycleConfiguration(ctx) {
+    const b = bucketOf(ctx, String(ctx.call.params.Bucket));
+    if (!b)
+        return noSuchBucket(ctx);
+    return xmlAnswer(lifecycleXml((b.lifecycle ?? DEFAULT_LIFECYCLE)));
+}
+/** A bucket as CreateBucket makes it, in the endpoint's jurisdiction ("Once an R2 bucket is created, the jurisdiction cannot
+ *  be changed", Data location), with its location hint when one was given, and R2's default lifecycle rule. */
+export async function createBucketRow(ctx, name, hint) {
+    await ctx.write('Bucket', bucketId(ctx, name), {
+        account_id: accountOf(ctx), name, creation_date: ctx.occurredAt, location: hint ?? null, storage_class: 'Standard', jurisdiction: jurisdictionOf(ctx), lifecycle: DEFAULT_LIFECYCLE, deleted: false,
+    }, 'CreateBucket');
+}
+export function bucketSemantics() {
+    return {
+        CreateBucket: async (ctx) => {
+            const name = String(ctx.call.params.Bucket);
+            if (!BUCKET_NAME.test(name))
+                return ctx.refuse({ status: 400, code: 'InvalidBucketName', message: 'Bucket name does not meet naming requirements.' });
+            const location = locationConstraintOf(ctx.text);
+            const hint = location !== undefined && LOCATION_HINTS.has(location.toLowerCase()) ? location.toLowerCase() : undefined;
+            // Where R2's documentation stops: a location that is neither auto nor a hint is refused with S3's code for it
+            if (location !== undefined && !REGIONS.has(location) && !hint)
+                return ctx.refuse({ status: 400, code: 'InvalidLocationConstraint', message: 'The specified location-constraint is not valid.' });
+            // error-codes: "10073 BucketConflict 409 Bucket name already exists." (a name is one per account, whatever its jurisdiction)
+            if (ctx.row('Bucket', bucketId(ctx, name)))
+                return ctx.refuse({ status: 409, code: 'BucketConflict', message: 'Bucket name already exists.' });
+            await createBucketRow(ctx, name, hint);
+            return ctx.raw(null, { headers: { location: `/${name}` } });
+        },
+        HeadBucket: headBucket,
+        ListBuckets: listBuckets,
+        DeleteBucket: async (ctx) => {
+            const name = String(ctx.call.params.Bucket);
+            if (!bucketOf(ctx, name))
+                return noSuchBucket(ctx);
+            // error-codes: "10008 BucketNotEmpty 409 Cannot delete bucket that contains objects."
+            if (objectsIn(ctx, name).length)
+                return ctx.refuse({ status: 409, code: 'BucketNotEmpty', message: 'Cannot delete bucket that contains objects.' });
+            await ctx.write('Bucket', bucketId(ctx, name), { deleted: true }, 'DeleteBucket');
+            // public buckets: a custom domain stays connected "until you remove it or delete the bucket"
+            for (const d of r2CustomDomains(ctx.root).filter((x) => x.account_id === accountOf(ctx) && x.bucket === name))
+                await removeR2CustomDomain(d.id, ctx.root, ctx.occurredAt);
+            return ctx.raw(null, { status: 204 });
+        },
+        GetBucketLocation: getBucketLocation,
+        GetBucketEncryption: getBucketEncryption,
+        PutBucketCors: async (ctx) => {
+            const name = String(ctx.call.params.Bucket);
+            if (!bucketOf(ctx, name))
+                return noSuchBucket(ctx);
+            const rules = parseCors(ctx.text);
+            if (!rules.length || rules.some((r) => !r.allowedOrigins.length || !r.allowedMethods.length))
+                return ctx.refuse({ status: 400, code: 'MalformedXML', message: 'The XML you provided was not well-formed or did not validate against our published schema.' });
+            await ctx.write('Bucket', bucketId(ctx, name), { cors: rules }, 'PutBucketCors');
+            return ctx.raw(null);
+        },
+        GetBucketCors: getBucketCors,
+        DeleteBucketCors: deleteBucketCors,
+        // PutBucketLifecycleConfiguration replaces the bucket's configuration with the one it sends; its rules are applied as
+        // the World clock moves (../fetch.ts, expireObjects)
+        PutBucketLifecycleConfiguration: async (ctx) => {
+            const name = String(ctx.call.params.Bucket);
+            if (!bucketOf(ctx, name))
+                return noSuchBucket(ctx);
+            const rules = parseLifecycle(ctx.text);
+            const badDate = (d) => d !== undefined && Number.isNaN(Date.parse(d));
+            if (!rules.length || rules.some((r) => (r.expireDays !== undefined && !(r.expireDays > 0)) || badDate(r.expireDate) || (r.transitions ?? []).some((tr) => badDate(tr.date) || (tr.date === undefined && !((tr.days ?? 0) > 0)))))
+                return ctx.refuse({ status: 400, code: 'MalformedXML', message: 'The XML you provided was not well-formed or did not validate against our published schema.' });
+            // R2 has two storage classes (its compatibility table: "✅ Storage Class: ✅ x-amz-storage-class ✅ STANDARD ✅
+            // STANDARD_IA"). A transition to another is refused with S3's code for it: that code, and the refusal, are the twin's
+            // choice where R2's documentation stops.
+            if (rules.some((r) => (r.transitions ?? []).some((tr) => tr.storageClass !== 'STANDARD_IA')))
+                return ctx.refuse({ status: 400, code: 'InvalidStorageClass', message: 'The storage class you specified is not valid' });
+            await ctx.write('Bucket', bucketId(ctx, name), { lifecycle: rules }, 'PutBucketLifecycleConfiguration');
+            return ctx.raw(null);
+        },
+        GetBucketLifecycleConfiguration: getBucketLifecycleConfiguration,
+    };
+}

package/dist/r2/src/semantics/objects.d.ts

@@ -0,0 +1,8 @@
+import { type Semantics } from '@volter/world-core';
+type Row = Record<string, unknown>;
+export declare const objectId: (account: string, bucket: string, key: string) => string;
+export declare function objectBytes(o: Row, root?: string): Promise<Uint8Array<ArrayBuffer>>;
+/** The headers an object's GET and HEAD answer carry: what was stored, as it was sent. */
+export declare function objectHeaders(o: Row): Record<string, string>;
+export declare function objectSemantics(): Record<string, Semantics>;
+export {};

package/dist/r2/src/semantics/objects.js

@@ -0,0 +1,252 @@
+// R2's objects through the S3 API. An object is a `r2_object` row (`<account>:<bucket>/<key>`) holding what R2 keeps of
+// it: its system metadata, which R2 implements on PutObject ("System Metadata: Content-Type, Cache-Control,
+// Content-Disposition, Content-Encoding, Content-Language, Expires, Content-MD5", S3 API compatibility), its custom
+// metadata, its ETag, and a reference to its bytes, which are kept in the World's blob store (state beside the tree).
+import { join } from 'node:path';
+import { blobDigest, getActiveBlobStore, readResourceBlob, worldPaths } from '@volter/world-core';
+import { bytesOf, doc, esc, md5Etag, parseDelete, x, xmlAnswer } from "../wire.js";
+import { accountOf, bucketId, bucketOf, createBucketRow, noSuchBucket, objectsIn } from "./buckets.js";
+const SERVICE = 'cloudflare';
+export const objectId = (account, bucket, key) => `${account}:${bucket}/${key}`;
+const blobPath = (sha) => join('r2-blobs', 'sha256', sha.slice(0, 2), sha);
+/** Bytes land in the blob store before the row that references them. */
+async function putBytes(bytes, root) {
+    const sha = blobDigest(bytes);
+    const key = join(worldPaths(SERVICE, root).resources, blobPath(sha));
+    const store = getActiveBlobStore();
+    if (!await store.exists(key))
+        await store.put(key, bytes);
+    return sha;
+}
+export async function objectBytes(o, root) {
+    const bytes = await readResourceBlob(SERVICE, blobPath(String(o.blob_sha256)), root);
+    if (!bytes || blobDigest(bytes) !== o.blob_sha256)
+        throw new Error(`R2 object ${String(o.key)}: its bytes are missing or corrupt`);
+    return new Uint8Array(bytes);
+}
+// the system metadata R2 keeps, by header
+const SYSTEM = [
+    ['content-type', 'content_type'], ['cache-control', 'cache_control'], ['content-disposition', 'content_disposition'],
+    ['content-encoding', 'content_encoding'], ['content-language', 'content_language'], ['expires', 'expires'],
+];
+function metadataOf(request) {
+    const system = {};
+    for (const [h, f] of SYSTEM) {
+        const v = request.headers.get(h);
+        if (v !== null)
+            system[f] = v;
+    }
+    const custom = {};
+    request.headers.forEach((v, k) => { if (k.toLowerCase().startsWith('x-amz-meta-'))
+        custom[k.toLowerCase().slice('x-amz-meta-'.length)] = v; });
+    return { system, custom };
+}
+/** The headers an object's GET and HEAD answer carry: what was stored, as it was sent. */
+export function objectHeaders(o) {
+    const out = {
+        etag: String(o.etag), 'last-modified': new Date(String(o.last_modified)).toUTCString(), 'content-length': String(o.size),
+        'content-type': String(o.content_type ?? 'application/octet-stream'), 'accept-ranges': 'bytes',
+    };
+    for (const [h, f] of SYSTEM)
+        if (h !== 'content-type' && typeof o[f] === 'string')
+            out[h] = String(o[f]);
+    for (const [k, v] of Object.entries((o.metadata ?? {})))
+        out[`x-amz-meta-${k}`] = v;
+    return out;
+}
+// error-codes: "10007 NoSuchKey 404 The specified object key does not exist."; the page's XML example carries "The
+// specified key does not exist."
+const noSuchKey = (ctx) => ctx.refuse({ status: 404, code: 'NoSuchKey', message: 'The specified key does not exist.' });
+const target = (ctx) => {
+    const bucket = String(ctx.call.params.Bucket);
+    const key = String(ctx.call.params.Key);
+    return { bucket, key, id: objectId(accountOf(ctx), bucket, key) };
+};
+/** The one Range form clients send for a part of an object (`bytes=a-b`, `bytes=a-`, `bytes=-n`), or undefined. */
+function rangeOf(header, size) {
+    const m = header ? /^bytes=(\d*)-(\d*)$/.exec(header.trim()) : null;
+    return !m || (m[1] === '' && m[2] === '') ? undefined : byteRange(m[1], m[2], size);
+}
+function byteRange(from, to, size) {
+    const start = from === '' ? Math.max(0, size - Number(to)) : Number(from);
+    const end = from === '' || to === '' ? size - 1 : Math.min(Number(to), size - 1);
+    return start > end || start >= size ? 'unsatisfiable' : { start, end };
+}
+async function read(ctx, head) {
+    const { bucket, id } = target(ctx);
+    if (!bucketOf(ctx, bucket))
+        return head ? ctx.raw(null, { status: 404 }) : noSuchBucket(ctx);
+    const o = ctx.row('Object', id);
+    if (!o)
+        return head ? ctx.raw(null, { status: 404 }) : noSuchKey(ctx);
+    const headers = objectHeaders(o);
+    // conditional reads (R2 implements If-Match, If-None-Match, If-Modified-Since, If-Unmodified-Since)
+    const ifNone = ctx.call.request.headers.get('if-none-match');
+    if (ifNone && (ifNone === '*' || ifNone.split(',').map((s) => s.trim()).includes(String(o.etag))))
+        return ctx.raw(null, { status: 304, headers: { etag: String(o.etag) } });
+    const ifMatch = ctx.call.request.headers.get('if-match');
+    // error-codes: "10031 PreconditionFailed 412 Conditional headers (If-Match, If-Unmodified-Since, etc.) were not satisfied."
+    if (ifMatch && ifMatch !== '*' && !ifMatch.split(',').map((s) => s.trim()).includes(String(o.etag)))
+        return head ? ctx.raw(null, { status: 412 }) : ctx.refuse({ status: 412, code: 'PreconditionFailed', message: 'At least one of the pre-conditions you specified did not hold' });
+    if (head)
+        return ctx.raw(null, { headers });
+    const bytes = await objectBytes(o, ctx.root);
+    const range = rangeOf(ctx.call.request.headers.get('range'), bytes.length);
+    // error-codes: "10039 InvalidRange 416 Requested byte range is not satisfiable."
+    if (range === 'unsatisfiable')
+        return ctx.refuse({ status: 416, code: 'InvalidRange', message: 'The requested range is not satisfiable' });
+    if (range)
+        return ctx.raw(bytes.slice(range.start, range.end + 1), { status: 206, headers: { ...headers, 'content-length': String(range.end - range.start + 1), 'content-range': `bytes ${range.start}-${range.end}/${bytes.length}` } });
+    return ctx.raw(bytes, { headers });
+}
+function listed(ctx, bucket, prefix, delimiter, after, max) {
+    const keys = objectsIn(ctx, bucket).filter((o) => String(o.key).startsWith(prefix) && String(o.key) > after).sort((a, b) => (String(a.key) < String(b.key) ? -1 : 1));
+    const contents = [];
+    const prefixes = [];
+    let last;
+    for (const o of keys) {
+        const key = String(o.key);
+        const cut = delimiter ? key.indexOf(delimiter, prefix.length) : -1;
+        const common = cut >= 0 ? key.slice(0, cut + delimiter.length) : undefined;
+        if (common && prefixes.includes(common))
+            continue;
+        if (contents.length + prefixes.length === max)
+            return { contents, prefixes, truncated: true, ...(last ? { last } : {}) };
+        if (common)
+            prefixes.push(common);
+        else
+            contents.push(o);
+        last = common ?? key;
+    }
+    return { contents, prefixes, truncated: false, ...(last ? { last } : {}) };
+}
+/** A listed object. ListObjects (v1) lists each with its Owner, as S3's response syntax does and R2's aws-sdk-js page prints
+ *  (`Owner: [Object]`, https://developers.cloudflare.com/r2/examples/aws/aws-sdk-js/); ListObjectsV2 leaves it out, as its
+ *  aws-sdk-js-v3 page prints (`Owner: undefined`). Where the documentation stops: the owner's values are the account's id,
+ *  the twin's choice (R2's aws-cli page prints a ListBuckets owner whose DisplayName and ID are one 32-hex id). */
+const entry = (o, owner) => x('Contents', [x('Key', String(o.key)), x('LastModified', String(o.last_modified)), x('ETag', String(o.etag)), x('Size', Number(o.size)), x('StorageClass', String(o.storage_class ?? 'STANDARD')), ...(owner ? [x('Owner', [x('DisplayName', owner), x('ID', owner)])] : [])]);
+const maxKeysOf = (q) => Math.min(1000, Math.max(0, Number(q.get('max-keys') ?? 1000) || 0));
+async function listObjects(ctx) {
+    const bucket = String(ctx.call.params.Bucket);
+    if (!bucketOf(ctx, bucket))
+        return noSuchBucket(ctx);
+    const q = new URL(ctx.call.request.url).searchParams;
+    const prefix = q.get('prefix') ?? '';
+    const delimiter = q.get('delimiter') ?? '';
+    const marker = q.get('marker') ?? '';
+    const max = maxKeysOf(q);
+    const page = listed(ctx, bucket, prefix, delimiter, marker, max);
+    return xmlAnswer(doc('ListBucketResult', [
+        x('Name', bucket), x('Prefix', prefix), x('Marker', marker), ...(delimiter ? [x('Delimiter', delimiter)] : []), x('MaxKeys', max),
+        x('IsTruncated', page.truncated ? 'true' : 'false'), ...(page.truncated && delimiter && page.last ? [x('NextMarker', page.last)] : []),
+        ...page.contents.map((o) => entry(o, accountOf(ctx))), ...page.prefixes.map((p) => x('CommonPrefixes', [x('Prefix', p)])),
+    ]));
+}
+// CopyObject: the source names `<bucket>/<key>` in x-amz-copy-source (URL-encoded, a leading slash allowed); R2
+// implements x-amz-metadata-directive, so REPLACE takes the request's metadata and COPY (the default) the source's
+async function copyObject(ctx) {
+    const { bucket, key, id } = target(ctx);
+    if (!bucketOf(ctx, bucket))
+        return noSuchBucket(ctx);
+    const raw = decodeURIComponent(String(ctx.call.request.headers.get('x-amz-copy-source') ?? '')).replace(/^\//, '').split('?')[0];
+    const cut = raw.indexOf('/');
+    const from = cut > 0 ? ctx.row('Object', objectId(accountOf(ctx), raw.slice(0, cut), raw.slice(cut + 1))) : undefined;
+    if (!from)
+        return noSuchKey(ctx);
+    const directive = (ctx.call.request.headers.get('x-amz-metadata-directive') ?? 'COPY').toUpperCase();
+    const replace = directive === 'REPLACE';
+    const { system, custom } = metadataOf(ctx.call.request);
+    const kept = {};
+    for (const [, f] of SYSTEM)
+        if (from[f] !== undefined)
+            kept[f] = from[f];
+    // R2's MERGE (S3 extensions: "MERGE is a combination of COPY and REPLACE, which will COPY any metadata keys from the
+    // source object and REPLACE those that are specified in the request with the new value")
+    if (directive === 'MERGE') {
+        Object.assign(kept, system);
+        Object.assign(custom, { ...(from.metadata ?? {}), ...custom });
+    }
+    await ctx.write('Object', id, {
+        bucket_id: `${accountOf(ctx)}:${bucket}`, bucket, key, size: from.size, etag: from.etag, ...(replace ? system : kept), metadata: replace || directive === 'MERGE' ? custom : (from.metadata ?? {}),
+        storage_class: ctx.call.request.headers.get('x-amz-storage-class') ?? from.storage_class ?? 'STANDARD', last_modified: ctx.occurredAt, blob_sha256: from.blob_sha256, deleted: false,
+    }, 'CopyObject');
+    return xmlAnswer(`<?xml version="1.0" encoding="UTF-8"?><CopyObjectResult><LastModified>${esc(ctx.occurredAt)}</LastModified><ETag>${esc(String(from.etag))}</ETag></CopyObjectResult>`);
+}
+export function objectSemantics() {
+    return {
+        PutObject: async (ctx) => {
+            const { bucket, key, id } = target(ctx);
+            if (!bucketOf(ctx, bucket)) {
+                // S3 extensions: "Add a cf-create-bucket-if-missing header with the value true to implicitly create the bucket if
+                // it does not exist yet", as a CreateBucket with LocationConstraint auto would
+                if (ctx.call.request.headers.get('cf-create-bucket-if-missing') !== 'true' || ctx.row('Bucket', bucketId(ctx, bucket)))
+                    return noSuchBucket(ctx);
+                await createBucketRow(ctx, bucket);
+            }
+            // a conditional write: R2 implements PutObject's "✅ Conditional Operations: ✅ If-Match ✅ If-Modified-Since ✅
+            // If-None-Match ✅ If-Unmodified-Since" (S3 API compatibility); error-codes: "10031 PreconditionFailed 412"
+            const current = ctx.row('Object', id);
+            const ifMatch = ctx.call.request.headers.get('if-match');
+            const ifNone = ctx.call.request.headers.get('if-none-match');
+            if ((ifMatch && (!current || (ifMatch !== '*' && !ifMatch.split(',').map((s) => s.trim()).includes(String(current.etag))))) || (ifNone && current && (ifNone === '*' || ifNone.split(',').map((s) => s.trim()).includes(String(current.etag))))) {
+                return ctx.refuse({ status: 412, code: 'PreconditionFailed', message: 'At least one of the pre-conditions you specified did not hold' });
+            }
+            // error-codes: "10020 InvalidObjectName 400 ... Maximum key length is 1024 bytes."
+            if (new TextEncoder().encode(key).length > 1024)
+                return ctx.refuse({ status: 400, code: 'InvalidObjectName', message: 'Object key contains invalid characters or is too long.' });
+            const bytes = bytesOf(ctx.call.request);
+            const sha = await putBytes(bytes, ctx.root);
+            const { system, custom } = metadataOf(ctx.call.request);
+            const etag = md5Etag(bytes);
+            const storage = ctx.call.request.headers.get('x-amz-storage-class') ?? 'STANDARD';
+            await ctx.write('Object', id, { bucket_id: `${accountOf(ctx)}:${bucket}`, bucket, key, size: bytes.length, etag, ...system, metadata: custom, storage_class: storage, last_modified: ctx.occurredAt, blob_sha256: sha, deleted: false }, 'PutObject');
+            return ctx.raw(null, { headers: { etag } });
+        },
+        GetObject: (ctx) => read(ctx, false),
+        HeadObject: (ctx) => read(ctx, true),
+        // S3's DeleteObject answers 204 whether or not the key existed
+        DeleteObject: async (ctx) => {
+            const { bucket, id } = target(ctx);
+            if (!bucketOf(ctx, bucket))
+                return noSuchBucket(ctx);
+            if (ctx.row('Object', id))
+                await ctx.write('Object', id, { deleted: true }, 'DeleteObject');
+            return ctx.raw(null, { status: 204 });
+        },
+        DeleteObjects: async (ctx) => {
+            const bucket = String(ctx.call.params.Bucket);
+            if (!bucketOf(ctx, bucket))
+                return noSuchBucket(ctx);
+            const { keys, quiet } = parseDelete(ctx.text);
+            if (!keys.length || keys.length > 1000)
+                return ctx.refuse({ status: 400, code: 'MalformedXML', message: 'The XML you provided was not well-formed or did not validate against our published schema.' });
+            for (const key of keys) {
+                const id = objectId(accountOf(ctx), bucket, key);
+                if (ctx.row('Object', id))
+                    await ctx.write('Object', id, { deleted: true }, 'DeleteObjects');
+            }
+            return xmlAnswer(doc('DeleteResult', quiet ? [] : keys.map((k) => x('Deleted', [x('Key', k)]))));
+        },
+        ListObjectsV2: async (ctx) => {
+            const bucket = String(ctx.call.params.Bucket);
+            if (!bucketOf(ctx, bucket))
+                return noSuchBucket(ctx);
+            const q = new URL(ctx.call.request.url).searchParams;
+            const prefix = q.get('prefix') ?? '';
+            const delimiter = q.get('delimiter') ?? '';
+            const token = q.get('continuation-token');
+            const startAfter = q.get('start-after') ?? '';
+            const after = token ? Buffer.from(token, 'base64url').toString('utf8') : startAfter;
+            const max = maxKeysOf(q);
+            const page = listed(ctx, bucket, prefix, delimiter, after, max);
+            return xmlAnswer(doc('ListBucketResult', [
+                x('Name', bucket), x('Prefix', prefix), ...(delimiter ? [x('Delimiter', delimiter)] : []), x('MaxKeys', max), x('KeyCount', page.contents.length + page.prefixes.length),
+                x('IsTruncated', page.truncated ? 'true' : 'false'), ...(token ? [x('ContinuationToken', token)] : []), ...(startAfter ? [x('StartAfter', startAfter)] : []),
+                ...(page.truncated && page.last ? [x('NextContinuationToken', Buffer.from(page.last).toString('base64url'))] : []),
+                ...page.contents.map((o) => entry(o)), ...page.prefixes.map((p) => x('CommonPrefixes', [x('Prefix', p)])),
+            ]));
+        },
+        ListObjects: listObjects,
+        CopyObject: copyObject,
+    };
+}

package/dist/r2/src/wire.d.ts

@@ -0,0 +1,54 @@
+export { endpointOf, JURISDICTIONS } from './endpoint.js';
+/** The host a request came to: the vendor host the World's injector names, else its Host, else its URL's. */
+export declare function hostOf(request: Request): string;
+export declare function esc(s: string | number): string;
+/** An element and its children or text. */
+export declare const x: (tag: string, inner: string | number | string[]) => string;
+export declare const doc: (root: string, inner: string[]) => string;
+export declare const xmlAnswer: (body: string, status?: number, headers?: Record<string, string>) => Response;
+export declare function unesc(s: string): string;
+export type CorsRule = {
+    id?: string;
+    allowedOrigins: string[];
+    allowedMethods: string[];
+    allowedHeaders: string[];
+    exposeHeaders: string[];
+    maxAgeSeconds?: number;
+};
+export declare function parseCors(xml: string): CorsRule[];
+export declare function corsXml(rules: CorsRule[]): string;
+/** The first rule that allows the origin, the method and the headers a preflight asks for. */
+export declare function corsRuleFor(rules: CorsRule[], origin: string, method: string, requested: string[]): CorsRule | undefined;
+/** The Access-Control-* headers a matching rule gives an answer ("AllowedOrigins: Specifies the value for the
+ *  Access-Control-Allow-Origin header", and likewise for the methods, headers, exposed headers and max age). */
+export declare function corsHeaders(rule: CorsRule, origin: string, requested: string[], preflight: boolean): Record<string, string>;
+export declare const requestedHeaders: (request: Request) => string[];
+/** A rule's prefix is sent in its Filter or, in S3's older form, on the rule itself, or not at all (R2's lifecycle page
+ *  sends a transition rule with neither, for the whole bucket); it is answered as it was sent. A
+ *  transition moves an object to Infrequent Access (Object lifecycles: "transition objects to Infrequent Access storage
+ *  after 30 days", its example `Transitions: [{ Days: 30, StorageClass: "STANDARD_IA" }]`). */
+export type LifecycleRule = {
+    id: string;
+    enabled: boolean;
+    prefix: string;
+    prefixOnRule?: boolean;
+    noPrefix?: boolean;
+    expireDays?: number;
+    expireDate?: string;
+    abortMultipartDays?: number;
+    transitions?: Array<{
+        days?: number;
+        date?: string;
+        storageClass: string;
+    }>;
+};
+export declare function parseLifecycle(xml: string): LifecycleRule[];
+export declare function lifecycleXml(rules: LifecycleRule[]): string;
+export declare function parseDelete(xml: string): {
+    keys: string[];
+    quiet: boolean;
+};
+export declare const locationConstraintOf: (xml: string) => string | undefined;
+export declare const md5Etag: (bytes: Uint8Array) => string;
+export declare function withBytes(request: Request): Promise<Request>;
+export declare const bytesOf: (request: Request) => Uint8Array;

package/dist/r2/src/wire.js

@@ -0,0 +1,120 @@
+// The S3 wire as R2 speaks it: where a request's account and bucket are, the XML bodies R2 answers and reads, and a
+// bucket's CORS rules applied to browsers. Ported from the aws pack's S3 twin (aws-s3-xml.ts, aws-s3-cors.ts), which a
+// pack may not import (architecture B4), cut to what R2 implements.
+import { createHash } from 'node:crypto';
+export { endpointOf, JURISDICTIONS } from "./endpoint.js";
+// ── addressing ───────────────────────────────────────────────────────────────────────────────
+/** The host a request came to: the vendor host the World's injector names, else its Host, else its URL's. */
+export function hostOf(request) {
+    return (request.headers.get('x-volter-twin-original-host') ?? request.headers.get('host') ?? new URL(request.url).host).split(':')[0].toLowerCase();
+}
+// ── XML ──────────────────────────────────────────────────────────────────────────────────────
+const DECL = '<?xml version="1.0" encoding="UTF-8"?>';
+const NS = 'http://s3.amazonaws.com/doc/2006-03-01/';
+export function esc(s) {
+    return String(s).replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;').replace(/"/g, '&quot;').replace(/'/g, '&apos;');
+}
+/** An element and its children or text. */
+export const x = (tag, inner) => `<${tag}>${Array.isArray(inner) ? inner.join('') : esc(inner)}</${tag}>`;
+export const doc = (root, inner) => `${DECL}<${root} xmlns="${NS}">${inner.join('')}</${root}>`;
+export const xmlAnswer = (body, status = 200, headers = {}) => new Response(body, { status, headers: { 'content-type': 'application/xml', ...headers } });
+export function unesc(s) {
+    return s.replace(/&(?:lt|gt|quot|apos|amp|#\d+|#x[0-9a-fA-F]+);/g, decodeEntity);
+}
+/** One XML entity, named or numeric, as its character. */
+function decodeEntity(m) {
+    const named = { '&lt;': '<', '&gt;': '>', '&quot;': '"', '&apos;': "'", '&amp;': '&' };
+    if (named[m])
+        return named[m];
+    const body = m.slice(2, -1);
+    const code = body[0] === 'x' ? Number.parseInt(body.slice(1), 16) : Number(body);
+    return Number.isInteger(code) && code >= 0 && code <= 0x10ffff ? String.fromCodePoint(code) : m;
+}
+const allOf = (xml, tag) => [...xml.matchAll(new RegExp(`<${tag}>([\\s\\S]*?)<\\/${tag}>`, 'g'))].map((m) => unesc(m[1].trim()));
+const oneOf = (xml, tag) => allOf(xml, tag)[0];
+export function parseCors(xml) {
+    return [...xml.matchAll(/<CORSRule>([\s\S]*?)<\/CORSRule>/g)].map((m) => {
+        const b = m[1];
+        const id = oneOf(b, 'ID');
+        const age = oneOf(b, 'MaxAgeSeconds');
+        return { ...(id ? { id } : {}), allowedOrigins: allOf(b, 'AllowedOrigin'), allowedMethods: allOf(b, 'AllowedMethod'), allowedHeaders: allOf(b, 'AllowedHeader'), exposeHeaders: allOf(b, 'ExposeHeader'), ...(age ? { maxAgeSeconds: Number(age) } : {}) };
+    });
+}
+export function corsXml(rules) {
+    return doc('CORSConfiguration', rules.map((r) => x('CORSRule', [
+        ...(r.id ? [x('ID', r.id)] : []), ...r.allowedOrigins.map((o) => x('AllowedOrigin', o)), ...r.allowedMethods.map((m) => x('AllowedMethod', m)),
+        ...r.allowedHeaders.map((h) => x('AllowedHeader', h)), ...r.exposeHeaders.map((h) => x('ExposeHeader', h)), ...(r.maxAgeSeconds !== undefined ? [x('MaxAgeSeconds', r.maxAgeSeconds)] : []),
+    ])));
+}
+function wildMatch(pattern, value, fold) {
+    const p = fold ? pattern.toLowerCase() : pattern;
+    const v = fold ? value.toLowerCase() : value;
+    const star = p.indexOf('*');
+    if (star < 0)
+        return p === v;
+    return v.length >= p.length - 1 && v.startsWith(p.slice(0, star)) && v.endsWith(p.slice(star + 1));
+}
+/** The first rule that allows the origin, the method and the headers a preflight asks for. */
+export function corsRuleFor(rules, origin, method, requested) {
+    return rules.find((r) => r.allowedOrigins.some((o) => wildMatch(o, origin, false))
+        && r.allowedMethods.some((m) => m === '*' || m.toUpperCase() === method.toUpperCase())
+        && requested.every((h) => r.allowedHeaders.some((a) => wildMatch(a, h, true))));
+}
+/** The Access-Control-* headers a matching rule gives an answer ("AllowedOrigins: Specifies the value for the
+ *  Access-Control-Allow-Origin header", and likewise for the methods, headers, exposed headers and max age). */
+export function corsHeaders(rule, origin, requested, preflight) {
+    return {
+        'access-control-allow-origin': origin,
+        'access-control-allow-methods': rule.allowedMethods.join(', '),
+        vary: 'Origin, Access-Control-Request-Headers, Access-Control-Request-Method',
+        ...(preflight && requested.length ? { 'access-control-allow-headers': requested.join(', ') } : {}),
+        ...(preflight && rule.maxAgeSeconds !== undefined ? { 'access-control-max-age': String(rule.maxAgeSeconds) } : {}),
+        ...(rule.exposeHeaders.length ? { 'access-control-expose-headers': rule.exposeHeaders.join(', ') } : {}),
+    };
+}
+export const requestedHeaders = (request) => (request.headers.get('access-control-request-headers') ?? '').split(',').map((h) => h.trim()).filter(Boolean);
+export function parseLifecycle(xml) {
+    return [...xml.matchAll(/<Rule>([\s\S]*?)<\/Rule>/g)].map((m) => {
+        const b = m[1];
+        const expiration = /<Expiration>([\s\S]*?)<\/Expiration>/.exec(b)?.[1];
+        const abort = /<AbortIncompleteMultipartUpload>([\s\S]*?)<\/AbortIncompleteMultipartUpload>/.exec(b)?.[1];
+        const days = expiration ? oneOf(expiration, 'Days') : undefined;
+        const date = expiration ? oneOf(expiration, 'Date') : undefined;
+        const after = abort ? oneOf(abort, 'DaysAfterInitiation') : undefined;
+        const transitions = [...b.matchAll(/<Transition>([\s\S]*?)<\/Transition>/g)].map((x) => {
+            const d = oneOf(x[1], 'Days');
+            const on = oneOf(x[1], 'Date');
+            return { ...(d !== undefined ? { days: Number(d) } : {}), ...(on !== undefined ? { date: on } : {}), storageClass: oneOf(x[1], 'StorageClass') ?? '' };
+        });
+        return {
+            id: oneOf(b, 'ID') ?? '', enabled: (oneOf(b, 'Status') ?? 'Enabled') === 'Enabled', prefix: oneOf(b, 'Prefix') ?? '', ...(/<Filter>/.test(b) ? {} : /<Prefix>/.test(b) ? { prefixOnRule: true } : { noPrefix: true }),
+            ...(days ? { expireDays: Number(days) } : {}), ...(date ? { expireDate: date } : {}), ...(after ? { abortMultipartDays: Number(after) } : {}), ...(transitions.length ? { transitions } : {}),
+        };
+    });
+}
+export function lifecycleXml(rules) {
+    return doc('LifecycleConfiguration', rules.map((r) => x('Rule', [
+        x('ID', r.id), ...(r.noPrefix ? [] : [r.prefixOnRule ? x('Prefix', r.prefix) : x('Filter', [x('Prefix', r.prefix)])]), x('Status', r.enabled ? 'Enabled' : 'Disabled'),
+        ...(r.transitions ?? []).map((tr) => x('Transition', [...(tr.date !== undefined ? [x('Date', tr.date)] : [x('Days', tr.days ?? 0)]), x('StorageClass', tr.storageClass)])),
+        ...(r.expireDays !== undefined ? [x('Expiration', [x('Days', r.expireDays)])] : r.expireDate !== undefined ? [x('Expiration', [x('Date', r.expireDate)])] : []),
+        ...(r.abortMultipartDays !== undefined ? [x('AbortIncompleteMultipartUpload', [x('DaysAfterInitiation', r.abortMultipartDays)])] : []),
+    ])));
+}
+// ── bodies ───────────────────────────────────────────────────────────────────────────────────
+export function parseDelete(xml) {
+    return { keys: [...xml.matchAll(/<Object>([\s\S]*?)<\/Object>/g)].map((m) => oneOf(m[1], 'Key') ?? ''), quiet: /<Quiet>\s*true\s*<\/Quiet>/i.test(xml) };
+}
+export const locationConstraintOf = (xml) => oneOf(xml, 'LocationConstraint');
+export const md5Etag = (bytes) => `"${createHash('md5').update(bytes).digest('hex')}"`;
+/** A request's body as the bytes it carried. The derived dispatch reads a body as text to find its parameters, which no
+ *  binary object survives, so the lane's fetch reads the bytes first and keeps them here for the handler. */
+const BODIES = new WeakMap();
+export async function withBytes(request) {
+    if (request.method === 'GET' || request.method === 'HEAD' || request.method === 'OPTIONS')
+        return request;
+    const bytes = new Uint8Array(await request.arrayBuffer());
+    const kept = new Request(request.url, { method: request.method, headers: request.headers, body: bytes });
+    BODIES.set(kept, bytes);
+    return kept;
+}
+export const bytesOf = (request) => BODIES.get(request) ?? new Uint8Array(0);

package/dist/src/cli.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/src/cli.js

@@ -0,0 +1,26 @@
+#!/usr/bin/env node
+import { keepProcessAlive } from '@volter/world-core/lifecycle';
+// world-cloudflare CLI: serve the KERNEL-BACKED Cloudflare API twin, or run conformance. State
+// lives in the @volter/world-core action log (no in-memory side-store). Conformance is dev-only +
+// lazy-imported so the bin runs without @volter/world-tooling (E2).
+import { hasFlag, optionValue } from '@volter/world-core/args';
+import { createCloudflareTwinServer } from "./cloudflare-server.js";
+const [cmd, ...rest] = process.argv.slice(2);
+const port = Number(optionValue(rest, '--port', String(process.env.PORT ?? '0'))) || undefined;
+const root = optionValue(rest, '--root') || undefined;
+const readOnly = hasFlag(rest, '--read-only'); // a twin accepts writes unless started read-only
+if (cmd === 'serve' || cmd === undefined) {
+    const s = await createCloudflareTwinServer({ readOnly, ...(root ? { root } : {}), ...(port ? { port } : {}) });
+    process.stdout.write(`cloudflare twin (accounts, zones, Cloudflare Tunnels, DNS records, Workers, R2, Hyperdrive, Queues)${readOnly ? ' [read-only]' : ''} at ${s.url}\n`);
+    await keepProcessAlive();
+}
+else if (cmd === 'conformance') {
+    const { checkCloudflareConformance } = await import("./cloudflare-conformance.js");
+    const report = await checkCloudflareConformance();
+    process.stdout.write(`${JSON.stringify(report, null, 2)}\n`);
+    if (!report.ok)
+        process.exitCode = 1;
+}
+else {
+    process.stdout.write('Usage: world-cloudflare serve|conformance [--port N] [--root DIR] [--read-only]\n');
+}