@syncular/server 0.32.0 → 0.33.0

package/dist/s3-blob-store.js

@@ -1,104 +1,28 @@
-import { EMPTY_PAYLOAD_SHA256, presignUrl, sha256Hex, signRequest, } from './sigv4.js';
-const BLOB_ID_PATTERN = /^sha256:[0-9a-f]{64}$/;
-const BLOB_META_HEADER = 'x-amz-meta-syncular-blob';
-/**
- * Stats accumulator (mirrors `S3SegmentStore`): a small counter object under
- * a fixed key, updated read-modify-write on `put` under an ETag
- * compare-and-swap. A LIST-free point-lookup store cannot count objects on
- * demand cheaply, so `stats()` reads the accumulator. The counters are
- * APPROXIMATE — a crash between the blob PUT and the accumulator CAS, or a
- * sweep DELETE the accumulator does not decrement, drifts them — so the
- * admin surface labels S3 blob stats `approximate: true`. A health gauge,
- * not an invoice.
- */
-const STATS_KEY_SUFFIX = 'stats/blobs.json';
-const STATS_CAS_ATTEMPTS = 16;
-function emptyStats() {
-    return { count: 0, bytes: 0 };
-}
-function parseStatsJson(json) {
-    const parsed = JSON.parse(json);
-    return {
-        count: Number(parsed.count ?? 0),
-        bytes: Number(parsed.bytes ?? 0),
-    };
-}
-// Runtime-neutral base64url: `Buffer` is not present on
-// Cloudflare Workers without `nodejs_compat`, so the metadata header is
-// (de)coded with `btoa`/`atob`, available in every runtime.
-function utf8ToBase64url(text) {
-    let binary = '';
-    for (const byte of new TextEncoder().encode(text)) {
-        binary += String.fromCharCode(byte);
-    }
-    return btoa(binary)
-        .replaceAll('+', '-')
-        .replaceAll('/', '_')
-        .replace(/=+$/, '');
-}
-function base64urlToUtf8(value) {
-    const binary = atob(value.replaceAll('-', '+').replaceAll('_', '/'));
-    const bytes = new Uint8Array(binary.length);
-    for (let i = 0; i < binary.length; i++)
-        bytes[i] = binary.charCodeAt(i);
-    return new TextDecoder().decode(bytes);
-}
-function metaToJson(meta) {
-    return JSON.stringify(meta);
-}
-function parseMetaJson(json, source) {
-    let parsed;
-    try {
-        parsed = JSON.parse(json);
-    }
-    catch {
-        throw new Error(`S3BlobStore: corrupt blob metadata in ${source}`);
-    }
-    if (typeof parsed !== 'object' || parsed === null) {
-        throw new Error(`S3BlobStore: corrupt blob metadata in ${source}`);
-    }
-    const r = parsed;
-    if (typeof r.byteLength !== 'number' || typeof r.createdAtMs !== 'number') {
-        throw new Error(`S3BlobStore: bad blob metadata in ${source}`);
-    }
-    return {
-        byteLength: r.byteLength,
-        ...(typeof r.mediaType === 'string' ? { mediaType: r.mediaType } : {}),
-        createdAtMs: r.createdAtMs,
-    };
-}
 /**
- * Extract `<Key>` values (and the `<NextContinuationToken>`, if the listing
- * is truncated) from a `ListObjectsV2` XML body. A tiny regex reader — the
- * only XML the store ever parses, and only on the GC path. `ListObjectsV2`
- * returns keys XML-escaped for `& < >`; we unescape those three.
+ * S3-compatible blob store (SPEC.md §5.9.2 durable objects, §5.9.5 delegated
+ * presign) — AWS S3, Cloudflare R2's S3 endpoint, MinIO. The blob twin of
+ * `s3-segment-store.ts`.
+ *
+ * The store logic (content-addressed key layout, idempotent re-put, orphan
+ * sweep, CAS stats accumulator) is `BucketBlobStore`, shared with
+ * `R2BlobStore` in `@syncular/server-workers`; this class adds the S3 REST
+ * transport (`S3ObjectBucket`) and the SigV4 presign methods, which a bucket
+ * binding cannot mint.
  */
-function parseListObjectsV2(xml) {
-    const objects = [];
-    for (const m of xml.matchAll(/<Key>([\s\S]*?)<\/Key>/g)) {
-        objects.push({ key: unescapeXml(m[1] ?? '') });
-    }
-    const truncated = /<IsTruncated>\s*true\s*<\/IsTruncated>/i.test(xml);
-    const tokenMatch = /<NextContinuationToken>([\s\S]*?)<\/NextContinuationToken>/.exec(xml);
-    const nextToken = truncated && tokenMatch !== null
-        ? unescapeXml(tokenMatch[1] ?? '')
-        : undefined;
-    return { objects, nextToken };
-}
-function unescapeXml(value) {
-    return value
-        .replaceAll('&lt;', '<')
-        .replaceAll('&gt;', '>')
-        .replaceAll('&quot;', '"')
-        .replaceAll('&apos;', "'")
-        .replaceAll('&amp;', '&');
-}
-export class S3BlobStore {
-    #config;
+import { BucketBlobStore, } from './bucket-blob-store.js';
+import { S3ObjectBucket } from './s3-object-bucket.js';
+import { presignUrl } from './sigv4.js';
+const BLOB_ID_PATTERN = /^sha256:[0-9a-f]{64}$/;
+export class S3BlobStore extends BucketBlobStore {
+    #bucket;
+    #region;
     #credentials;
-    #prefix;
     constructor(config) {
-        this.#config = config;
+        const options = { keyPrefix: config.keyPrefix };
+        const bucket = new S3ObjectBucket(config);
+        super(bucket, options);
+        this.#bucket = bucket;
+        this.#region = config.region;
         this.#credentials = {
             accessKeyId: config.accessKeyId,
             secretAccessKey: config.secretAccessKey,
@@ -106,264 +30,6 @@ export class S3BlobStore {
                 ? { sessionToken: config.sessionToken }
                 : {}),
         };
-        this.#prefix = config.keyPrefix ?? '';
-    }
-    /**
-     * `{keyPrefix}blob/{partition}/sha256/{hex}` — the §5.9.5 "signed key embeds
-     * the blobId". Blobs are content-addressed, but download authorization and
-     * the reference index are per-partition, so the same bytes uploaded under
-     * two partitions are two objects (a partition MUST NOT read another's
-     * attachment by guessing a content address). The partition is folded into
-     * the key as a path segment.
-     */
-    objectKeyFor(partition, blobId) {
-        return `${this.#prefix}blob/${partition}/${blobId.replace(':', '/')}`;
-    }
-    #statsKey() {
-        return `${this.#prefix}${STATS_KEY_SUFFIX}`;
-    }
-    #urlFor(key) {
-        const endpoint = this.#config.endpoint.replace(/\/+$/, '');
-        return new URL(`${endpoint}/${this.#config.bucket}/${key}`);
-    }
-    async #request(method, key, options) {
-        const url = this.#urlFor(key);
-        if (options?.query !== undefined) {
-            for (const [name, value] of options.query) {
-                url.searchParams.set(name, value);
-            }
-        }
-        const body = options?.body;
-        const headers = await signRequest({
-            method,
-            url,
-            region: this.#config.region,
-            credentials: this.#credentials,
-            nowMs: Date.now(),
-            payloadHash: body === undefined ? EMPTY_PAYLOAD_SHA256 : await sha256Hex(body),
-            ...(options?.headers !== undefined ? { headers: options.headers } : {}),
-        });
-        const response = await fetch(url, {
-            method,
-            headers,
-            ...(body !== undefined ? { body: body } : {}),
-        });
-        if (response.status === 404) {
-            await response.arrayBuffer();
-            return undefined;
-        }
-        if (!response.ok) {
-            const detail = (await response.text()).slice(0, 300);
-            throw new Error(`S3BlobStore: ${method} ${key} failed with ${response.status}: ${detail}`);
-        }
-        return response;
-    }
-    async #readStats() {
-        const response = await this.#request('GET', this.#statsKey());
-        if (response === undefined) {
-            return { stats: emptyStats(), etag: undefined };
-        }
-        const etag = response.headers.get('etag') ?? undefined;
-        const stats = parseStatsJson(await response.text());
-        return { stats, etag };
-    }
-    async #writeStatsCas(stats, etag) {
-        const url = this.#urlFor(this.#statsKey());
-        const body = new TextEncoder().encode(JSON.stringify(stats));
-        const conditional = etag === undefined ? { 'if-none-match': '*' } : { 'if-match': etag };
-        const headers = await signRequest({
-            method: 'PUT',
-            url,
-            region: this.#config.region,
-            credentials: this.#credentials,
-            nowMs: Date.now(),
-            payloadHash: await sha256Hex(body),
-            headers: { 'content-type': 'application/json', ...conditional },
-        });
-        const response = await fetch(url, {
-            method: 'PUT',
-            headers,
-            body: body,
-        });
-        if (response.status === 412) {
-            await response.arrayBuffer();
-            return false;
-        }
-        if (!response.ok) {
-            const detail = (await response.text()).slice(0, 300);
-            throw new Error(`S3BlobStore: stats PUT failed with ${response.status}: ${detail}`);
-        }
-        await response.arrayBuffer();
-        return true;
-    }
-    /**
-     * Fold `delta` into the stats accumulator under an ETag CAS retry loop.
-     * Best-effort: exhausting the budget leaves the counters drifted (they are
-     * documented APPROXIMATE) rather than failing an op that already touched
-     * the bytes.
-     */
-    async #bumpStats(delta) {
-        for (let attempt = 0; attempt < STATS_CAS_ATTEMPTS; attempt++) {
-            const { stats, etag } = await this.#readStats();
-            const next = {
-                count: stats.count + delta.count,
-                bytes: stats.bytes + delta.bytes,
-            };
-            if (await this.#writeStatsCas(next, etag))
-                return;
-        }
-        // Lost the CAS race `STATS_CAS_ATTEMPTS` times — leave counters as-is;
-        // `stats()` stays APPROXIMATE by contract.
-    }
-    async put(partition, blobId, bytes, nowMs, mediaType) {
-        const record = {
-            blobId,
-            partition,
-            byteLength: bytes.length,
-            ...(mediaType !== undefined ? { mediaType } : {}),
-            createdAtMs: nowMs,
-        };
-        const objectKey = this.objectKeyFor(partition, blobId);
-        // Idempotent re-put (same content-address ⇒ same key): count each distinct
-        // blob once, and preserve the FIRST createdAtMs so the sweep's grace clock
-        // is not reset by a re-upload (§5.9.2 upload age).
-        const preexisting = await this.#request('HEAD', objectKey);
-        if (preexisting !== undefined) {
-            const meta = preexisting.headers.get(BLOB_META_HEADER);
-            await preexisting.arrayBuffer();
-            if (meta !== null) {
-                const existing = parseMetaJson(base64urlToUtf8(meta), blobId);
-                return {
-                    blobId,
-                    partition,
-                    byteLength: existing.byteLength,
-                    ...(existing.mediaType !== undefined
-                        ? { mediaType: existing.mediaType }
-                        : {}),
-                    createdAtMs: existing.createdAtMs,
-                };
-            }
-        }
-        const meta = {
-            byteLength: bytes.length,
-            ...(mediaType !== undefined ? { mediaType } : {}),
-            createdAtMs: nowMs,
-        };
-        const response = await this.#request('PUT', objectKey, {
-            body: bytes,
-            headers: {
-                'content-type': mediaType ?? 'application/octet-stream',
-                [BLOB_META_HEADER]: utf8ToBase64url(metaToJson(meta)),
-            },
-        });
-        await response?.arrayBuffer();
-        await this.#bumpStats({ count: 1, bytes: bytes.length });
-        return record;
-    }
-    async has(partition, blobId) {
-        if (!BLOB_ID_PATTERN.test(blobId))
-            return false;
-        const response = await this.#request('HEAD', this.objectKeyFor(partition, blobId));
-        if (response === undefined)
-            return false;
-        await response.arrayBuffer();
-        return true;
-    }
-    async get(partition, blobId) {
-        if (!BLOB_ID_PATTERN.test(blobId))
-            return undefined;
-        const response = await this.#request('GET', this.objectKeyFor(partition, blobId));
-        if (response === undefined)
-            return undefined;
-        const bytes = new Uint8Array(await response.arrayBuffer());
-        const rawMeta = response.headers.get(BLOB_META_HEADER);
-        const meta = rawMeta !== null
-            ? parseMetaJson(base64urlToUtf8(rawMeta), blobId)
-            : { byteLength: bytes.length, createdAtMs: 0 };
-        return {
-            record: {
-                blobId,
-                partition,
-                byteLength: meta.byteLength,
-                ...(meta.mediaType !== undefined ? { mediaType: meta.mediaType } : {}),
-                createdAtMs: meta.createdAtMs,
-            },
-            bytes,
-        };
-    }
-    /**
-     * §5.9.2 orphan sweep — the ONLY LISTing operation. Page `ListObjectsV2`
-     * over `{prefix}blob/{partition}/`, HEAD each object for its `createdAtMs`,
-     * and DELETE the ones both older than `olderThanMs` AND absent from
-     * `referencedBlobIds`. Returns the deleted blobIds. Never deletes a
-     * referenced blob (§5.9.2). Off the hot path — a host-scheduled GC job.
-     */
-    async sweepOrphans(partition, olderThanMs, referencedBlobIds) {
-        const listPrefix = `${this.#prefix}blob/${partition}/`;
-        const swept = [];
-        let deletedBytes = 0;
-        let continuationToken;
-        do {
-            const query = [
-                ['list-type', '2'],
-                ['prefix', listPrefix],
-            ];
-            if (continuationToken !== undefined) {
-                query.push(['continuation-token', continuationToken]);
-            }
-            // ListObjectsV2 is a bucket-level GET (`GET /{bucket}?list-type=2`).
-            const response = await this.#request('GET', '', { query });
-            if (response === undefined)
-                break;
-            const { objects, nextToken } = parseListObjectsV2(await response.text());
-            continuationToken = nextToken;
-            for (const { key } of objects) {
-                // `{listPrefix}sha256/{hex}` → `sha256:{hex}`.
-                const rest = key.slice(listPrefix.length);
-                if (!rest.startsWith('sha256/'))
-                    continue;
-                const blobId = `sha256:${rest.slice('sha256/'.length)}`;
-                if (!BLOB_ID_PATTERN.test(blobId))
-                    continue;
-                if (referencedBlobIds.has(blobId))
-                    continue;
-                const head = await this.#request('HEAD', key);
-                if (head === undefined)
-                    continue;
-                const rawMeta = head.headers.get(BLOB_META_HEADER);
-                const lengthHeader = head.headers.get('content-length');
-                await head.arrayBuffer();
-                const meta = rawMeta !== null
-                    ? parseMetaJson(base64urlToUtf8(rawMeta), blobId)
-                    : {
-                        byteLength: Number(lengthHeader ?? 0),
-                        createdAtMs: 0,
-                    };
-                if (meta.createdAtMs >= olderThanMs)
-                    continue;
-                const del = await this.#request('DELETE', key);
-                await del?.arrayBuffer();
-                swept.push(blobId);
-                deletedBytes += meta.byteLength;
-            }
-        } while (continuationToken !== undefined);
-        if (swept.length > 0) {
-            await this.#bumpStats({ count: -swept.length, bytes: -deletedBytes });
-        }
-        return swept;
-    }
-    /**
-     * Store-wide counters from the pointer-object accumulator (never a LIST on
-     * the read path). `approximate: true` for the same reasons `S3SegmentStore`
-     * documents: best-effort ETag-CAS maintenance and sweep deletes that may
-     * miss the decrement. Exact within a single writer; a health gauge under
-     * concurrency. Note this is store-WIDE, not partition-scoped, so a shared
-     * bucket reports the whole bucket — the parameter is accepted for interface
-     * parity but the accumulator is one object per store.
-     */
-    async stats(_partition) {
-        const { stats } = await this.#readStats();
-        return { count: stats.count, bytes: stats.bytes, approximate: true };
     }
     /**
      * SigV4 presigned GET for a blob object (§5.9.5 delegated presign). The
@@ -381,8 +47,8 @@ export class S3BlobStore {
         const ttlSeconds = options?.ttlSeconds ?? 900;
         const nowMs = options?.nowMs ?? Date.now();
         const url = await presignUrl({
-            url: this.#urlFor(this.objectKeyFor(partition, blobId)),
-            region: this.#config.region,
+            url: this.#bucket.urlFor(this.objectKeyFor(partition, blobId)),
+            region: this.#region,
             credentials: this.#credentials,
             nowMs,
             expiresSeconds: ttlSeconds,
@@ -412,8 +78,8 @@ export class S3BlobStore {
         const nowMs = options?.nowMs ?? Date.now();
         const url = await presignUrl({
             method: 'PUT',
-            url: this.#urlFor(this.objectKeyFor(partition, blobId)),
-            region: this.#config.region,
+            url: this.#bucket.urlFor(this.objectKeyFor(partition, blobId)),
+            region: this.#region,
             credentials: this.#credentials,
             nowMs,
             expiresSeconds: ttlSeconds,

package/dist/s3-object-bucket.d.ts

@@ -0,0 +1,39 @@
+/**
+ * `ObjectBucket` over the S3 REST API: hand-rolled SigV4 over `fetch`
+ * (sigv4.ts), zero dependencies, path-style requests
+ * (`{endpoint}/{bucket}/{key}`) that AWS S3, Cloudflare R2's S3 endpoint, and
+ * MinIO all accept.
+ *
+ * This module owns the transport only. The segment and blob store logic lives
+ * in `bucket-segment-store.ts` / `bucket-blob-store.ts` and runs over any
+ * `ObjectBucket`, so the same objects are reachable through an R2 binding
+ * (`R2SegmentStore` in `@syncular/server-workers`) with no copy between them.
+ */
+import type { BucketListPage, BucketObject, BucketObjectHead, BucketWriteOptions, ObjectBucket } from './object-bucket.js';
+export interface S3ObjectBucketConfig {
+    /**
+     * Endpoint origin, no bucket, no trailing slash:
+     * AWS `https://s3.<region>.amazonaws.com`,
+     * R2 `https://<account-id>.r2.cloudflarestorage.com`,
+     * MinIO `http://127.0.0.1:9000`.
+     */
+    readonly endpoint: string;
+    /** AWS region; R2 uses `auto`. */
+    readonly region: string;
+    readonly bucket: string;
+    readonly accessKeyId: string;
+    readonly secretAccessKey: string;
+    /** Optional STS session token. */
+    readonly sessionToken?: string;
+}
+export declare class S3ObjectBucket implements ObjectBucket {
+    #private;
+    constructor(config: S3ObjectBucketConfig);
+    /** The object URL the presign helpers sign (`{endpoint}/{bucket}/{key}`). */
+    urlFor(key: string): URL;
+    get(key: string): Promise<BucketObject | undefined>;
+    head(key: string): Promise<BucketObjectHead | undefined>;
+    put(key: string, options: BucketWriteOptions): Promise<boolean>;
+    delete(key: string): Promise<void>;
+    list(prefix: string, cursor?: string): Promise<BucketListPage>;
+}

package/dist/s3-object-bucket.js

@@ -0,0 +1,164 @@
+import { EMPTY_PAYLOAD_SHA256, sha256Hex, signRequest, } from './sigv4.js';
+const META_HEADER_PREFIX = 'x-amz-meta-';
+/** User metadata carried as `x-amz-meta-*` headers (lowercased by `Headers`). */
+function metadataOf(headers) {
+    const metadata = {};
+    for (const [name, value] of headers) {
+        if (name.startsWith(META_HEADER_PREFIX)) {
+            metadata[name.slice(META_HEADER_PREFIX.length)] = value;
+        }
+    }
+    return metadata;
+}
+function sizeOf(headers) {
+    const value = headers.get('content-length');
+    if (value === null)
+        return undefined;
+    const size = Number(value);
+    return Number.isFinite(size) ? size : undefined;
+}
+/**
+ * Extract `<Key>` values (and the `<NextContinuationToken>`, if the listing
+ * is truncated) from a `ListObjectsV2` XML body. A tiny regex reader; the
+ * only XML the stores ever parse, and only on the GC path. `ListObjectsV2`
+ * returns keys XML-escaped for `& < >`; we unescape those.
+ */
+function parseListObjectsV2(xml) {
+    const objects = [];
+    for (const m of xml.matchAll(/<Key>([\s\S]*?)<\/Key>/g)) {
+        objects.push({ key: unescapeXml(m[1] ?? '') });
+    }
+    const truncated = /<IsTruncated>\s*true\s*<\/IsTruncated>/i.test(xml);
+    const tokenMatch = /<NextContinuationToken>([\s\S]*?)<\/NextContinuationToken>/.exec(xml);
+    const nextToken = truncated && tokenMatch !== null
+        ? unescapeXml(tokenMatch[1] ?? '')
+        : undefined;
+    return { objects, nextToken };
+}
+function unescapeXml(value) {
+    return value
+        .replaceAll('&lt;', '<')
+        .replaceAll('&gt;', '>')
+        .replaceAll('&quot;', '"')
+        .replaceAll('&apos;', "'")
+        .replaceAll('&amp;', '&');
+}
+export class S3ObjectBucket {
+    #config;
+    #credentials;
+    constructor(config) {
+        this.#config = config;
+        this.#credentials = {
+            accessKeyId: config.accessKeyId,
+            secretAccessKey: config.secretAccessKey,
+            ...(config.sessionToken !== undefined
+                ? { sessionToken: config.sessionToken }
+                : {}),
+        };
+    }
+    /** The object URL the presign helpers sign (`{endpoint}/{bucket}/{key}`). */
+    urlFor(key) {
+        const endpoint = this.#config.endpoint.replace(/\/+$/, '');
+        return new URL(`${endpoint}/${this.#config.bucket}/${key}`);
+    }
+    async #request(method, key, options) {
+        const url = this.urlFor(key);
+        if (options?.query !== undefined) {
+            for (const [name, value] of options.query) {
+                url.searchParams.set(name, value);
+            }
+        }
+        const body = options?.body;
+        const headers = await signRequest({
+            method,
+            url,
+            region: this.#config.region,
+            credentials: this.#credentials,
+            nowMs: Date.now(),
+            payloadHash: body === undefined ? EMPTY_PAYLOAD_SHA256 : await sha256Hex(body),
+            ...(options?.headers !== undefined ? { headers: options.headers } : {}),
+        });
+        const response = await fetch(url, {
+            method,
+            headers,
+            ...(body !== undefined ? { body: body } : {}),
+        });
+        if (response.status === 404) {
+            await response.arrayBuffer();
+            return undefined;
+        }
+        if (options?.allow412 === true && response.status === 412)
+            return response;
+        if (!response.ok) {
+            const detail = (await response.text()).slice(0, 300);
+            throw new Error(`S3ObjectBucket: ${method} ${key} failed with ${response.status}: ${detail}`);
+        }
+        return response;
+    }
+    async get(key) {
+        const response = await this.#request('GET', key);
+        if (response === undefined)
+            return undefined;
+        return {
+            body: response.body,
+            etag: response.headers.get('etag') ?? undefined,
+            size: sizeOf(response.headers),
+            metadata: metadataOf(response.headers),
+            arrayBuffer: () => response.arrayBuffer(),
+            text: () => response.text(),
+        };
+    }
+    async head(key) {
+        const response = await this.#request('HEAD', key);
+        if (response === undefined)
+            return undefined;
+        await response.arrayBuffer();
+        return {
+            etag: response.headers.get('etag') ?? undefined,
+            size: sizeOf(response.headers),
+            metadata: metadataOf(response.headers),
+        };
+    }
+    async put(key, options) {
+        const headers = {
+            'content-type': options.contentType,
+        };
+        if (options.createOnly === true)
+            headers['if-none-match'] = '*';
+        if (options.ifMatch !== undefined)
+            headers['if-match'] = options.ifMatch;
+        for (const [name, value] of Object.entries(options.metadata ?? {})) {
+            headers[`${META_HEADER_PREFIX}${name}`] = value;
+        }
+        const response = await this.#request('PUT', key, {
+            body: options.body,
+            headers,
+            allow412: true,
+        });
+        if (response === undefined) {
+            throw new Error(`S3ObjectBucket: PUT ${key} failed with 404`);
+        }
+        await response.arrayBuffer();
+        // A failed `If-Match` / `If-None-Match: *` is a `412`: the caller's CAS
+        // read superseded, so it re-reads instead of overwriting.
+        return response.status !== 412;
+    }
+    async delete(key) {
+        const response = await this.#request('DELETE', key);
+        await response?.arrayBuffer();
+    }
+    async list(prefix, cursor) {
+        const query = [
+            ['list-type', '2'],
+            ['prefix', prefix],
+        ];
+        if (cursor !== undefined)
+            query.push(['continuation-token', cursor]);
+        // ListObjectsV2 is a bucket-level GET (`GET /{bucket}?list-type=2`).
+        const response = await this.#request('GET', '', { query });
+        if (response === undefined)
+            return { keys: [], cursor: undefined };
+        const { objects, nextToken } = parseListObjectsV2(await response.text());
+        return { keys: objects.map((object) => object.key), cursor: nextToken };
+    }
+}