@filelayer/core 0.3.0

package/dist/storage.js

@@ -0,0 +1,700 @@
+/**
+ * STORAGE ADAPTERS
+ *
+ * P2 (no ambient authority) is why this interface is deliberately dumb: it
+ * takes an opaque key and moves bytes. It has no idea what an org is, cannot
+ * be asked "who may read this", and is never consulted during an authorization
+ * decision. If the adapter could answer access questions there would be two
+ * authorization paths, and the second one is always the one that leaks.
+ *
+ * Corollary: object keys are NOT secrets and are not treated as such anywhere.
+ *
+ * -----------------------------------------------------------------------------
+ * WHAT CHANGED, AND WHY
+ * -----------------------------------------------------------------------------
+ *
+ * 1. `provider` is now part of the interface.
+ *
+ *    `file.storage_provider` was written as the literal `'memory'` in
+ *    `Filelayer.upload()`, regardless of which adapter was configured. Against
+ *    `CREATE UNIQUE INDEX file_storage_key_idx ON file (storage_provider,
+ *    storage_key)` that means a production database records every object as
+ *    living in an in-memory store, and the one column that says WHERE the bytes
+ *    are is wrong for every row. An adapter must therefore be able to name
+ *    itself, and the name must come from the adapter rather than from the call
+ *    site.
+ *
+ * 2. Everything is streaming-capable.
+ *
+ *    `put()` took a `Uint8Array` and delivery returned one. That is a permanent
+ *    tax on the heap: a 2 GB upload was 2 GB of resident memory in the API
+ *    process, twice (once in the adapter, once in the response). `put()` now
+ *    accepts a `ReadableStream` and uses S3 multipart above a part threshold;
+ *    `stream()` returns a byte stream plus the metadata a correct HTTP response
+ *    needs, and supports ranged reads.
+ *
+ * 3. `head()` exists.
+ *
+ *    A `stat()` that has to download the object to learn its size is not a
+ *    stat.
+ *
+ * 4. `presignGet()` is OPTIONAL, and its optionality is the point.
+ *
+ *    It is the only capability the redirect delivery mode needs, and an adapter
+ *    that cannot mint a presigned URL simply does not offer redirect delivery
+ *    (`MemoryStorage` does not). Nothing else in the system may call it:
+ *    a presigned URL is authority that outlives the decision that produced it,
+ *    which is exactly the property P4 exists to deny, so it is reachable only
+ *    through the explicitly-acknowledged redirect mode in `delivery.ts`.
+ *
+ * 5. `list()` is OPTIONAL and exists for exactly one caller: orphan collection.
+ *
+ *    The storage write is not transactional (see `db.ts`). Bytes are written
+ *    before the metadata transaction commits, so a crash in between leaves an
+ *    object with no `file` row. That is a garbage-collection problem, not a
+ *    correctness one -- an orphan is unreachable, because every read path starts
+ *    from a `file` row -- but it is still our problem. `list()` is what makes it
+ *    collectable.
+ */
+import { createHash, createHmac } from 'node:crypto';
+/** Narrowing helpers, so callers do not hand-roll `typeof x.presignGet`. */
+export function canPresign(s) {
+    return typeof s.presignGet === 'function';
+}
+export function canList(s) {
+    return typeof s.list === 'function';
+}
+// -----------------------------------------------------------------------------
+// Stream helpers
+// -----------------------------------------------------------------------------
+/** Collect a byte stream, refusing to exceed `limit`. */
+export async function collectStream(stream, limit = 512 * 1024 * 1024) {
+    const reader = stream.getReader();
+    const chunks = [];
+    let total = 0;
+    try {
+        for (;;) {
+            const { done, value } = await reader.read();
+            if (done)
+                break;
+            if (!value)
+                continue;
+            total += value.byteLength;
+            if (total > limit) {
+                await reader.cancel('limit exceeded').catch(() => { });
+                throw new Error(`object exceeds the ${limit}-byte buffered read limit; use stream()`);
+            }
+            chunks.push(value);
+        }
+    }
+    finally {
+        reader.releaseLock();
+    }
+    const out = new Uint8Array(total);
+    let at = 0;
+    for (const c of chunks) {
+        out.set(c, at);
+        at += c.byteLength;
+    }
+    return out;
+}
+export function bytesToStream(body) {
+    return new ReadableStream({
+        start(controller) {
+            controller.enqueue(body);
+            controller.close();
+        },
+    });
+}
+// -----------------------------------------------------------------------------
+// In-memory adapter (tests, local dev)
+// -----------------------------------------------------------------------------
+export class MemoryStorage {
+    provider = 'memory';
+    objects = new Map();
+    async put(key, body, contentType) {
+        const bytes = body instanceof Uint8Array ? body : await collectStream(body);
+        const etag = `"${createHash('md5').update(bytes).digest('hex')}"`;
+        this.objects.set(key, { body: bytes, contentType, etag, lastModified: new Date() });
+        return { bytes: bytes.byteLength, etag };
+    }
+    async get(key) {
+        return this.objects.get(key)?.body ?? null;
+    }
+    async head(key) {
+        const o = this.objects.get(key);
+        if (!o)
+            return null;
+        return {
+            size: o.body.byteLength,
+            contentType: o.contentType,
+            etag: o.etag,
+            lastModified: o.lastModified,
+        };
+    }
+    async delete(key) {
+        this.objects.delete(key);
+    }
+    async stream(key, opts = {}) {
+        const o = this.objects.get(key);
+        if (!o)
+            return null;
+        const total = o.body.byteLength;
+        if (opts.range) {
+            const start = Math.max(0, opts.range.start);
+            const end = Math.min(opts.range.end ?? total - 1, total - 1);
+            if (start > end)
+                return null;
+            const slice = o.body.subarray(start, end + 1);
+            return {
+                body: bytesToStream(slice),
+                size: slice.byteLength,
+                contentType: o.contentType,
+                etag: o.etag,
+                range: { start, end, total },
+            };
+        }
+        return { body: bytesToStream(o.body), size: total, contentType: o.contentType, etag: o.etag };
+    }
+    async list(prefix, opts = {}) {
+        const limit = Math.max(1, Math.min(opts.limit ?? 1000, 1000));
+        const after = opts.cursor ?? '';
+        const all = [...this.objects.entries()]
+            .filter(([k]) => k.startsWith(prefix) && k > after)
+            .sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0));
+        const page = all.slice(0, limit);
+        return {
+            entries: page.map(([k, v]) => ({
+                key: k,
+                size: v.body.byteLength,
+                lastModified: v.lastModified,
+            })),
+            cursor: all.length > limit ? (page[page.length - 1]?.[0] ?? null) : null,
+        };
+    }
+    /**
+     * DELIBERATELY ABSENT: `presignGet`.
+     *
+     * There is no URL that reaches an in-process Map, so redirect delivery is
+     * structurally unavailable here rather than fake. A test that wants to
+     * exercise redirect delivery must run against something that can actually
+     * mint one -- which is the point.
+     */
+    /** Test-only: lets a test assert that delete really removed the bytes. */
+    keys() {
+        return [...this.objects.keys()];
+    }
+}
+const MIN_PART_SIZE = 5 * 1024 * 1024;
+const DEFAULT_PART_SIZE = 8 * 1024 * 1024;
+export class S3Storage {
+    provider;
+    cfg;
+    constructor(cfg) {
+        for (const k of ['endpoint', 'bucket', 'region', 'accessKeyId', 'secretAccessKey']) {
+            if (typeof cfg[k] !== 'string' || cfg[k].length === 0) {
+                throw new Error(`S3Storage: missing required config '${k}'`);
+            }
+        }
+        const endpoint = cfg.endpoint.replace(/\/+$/, '');
+        this.provider =
+            cfg.provider ?? (/\.r2\.cloudflarestorage\.com$/i.test(new URL(endpoint).hostname) ? 'r2' : 's3');
+        if (!/^[a-z0-9_-]{1,32}$/.test(this.provider)) {
+            throw new Error(`S3Storage: implausible provider name ${JSON.stringify(this.provider)}`);
+        }
+        this.cfg = {
+            endpoint,
+            bucket: cfg.bucket,
+            region: cfg.region,
+            accessKeyId: cfg.accessKeyId,
+            secretAccessKey: cfg.secretAccessKey,
+            pathStyle: cfg.pathStyle ?? true,
+            partSizeBytes: Math.max(MIN_PART_SIZE, cfg.partSizeBytes ?? DEFAULT_PART_SIZE),
+            maxPresignSeconds: Math.max(1, Math.min(cfg.maxPresignSeconds ?? 3600, 7 * 24 * 3600)),
+            ...(cfg.sessionToken !== undefined ? { sessionToken: cfg.sessionToken } : {}),
+        };
+    }
+    // --- writes ---------------------------------------------------------------
+    async put(key, body, contentType, opts = {}) {
+        if (body instanceof Uint8Array)
+            return this.putBuffer(key, body, contentType);
+        return this.putStream(key, body, contentType, opts);
+    }
+    async putBuffer(key, body, contentType) {
+        const res = await this.signedFetch({
+            method: 'PUT',
+            key,
+            body,
+            headers: { 'content-type': contentType },
+        });
+        if (!res.ok)
+            throw await s3Error('put', res);
+        await res.arrayBuffer(); // drain; undici leaks the connection otherwise
+        return { bytes: body.byteLength, etag: res.headers.get('etag') };
+    }
+    /**
+     * Streaming upload.
+     *
+     * The first `partSizeBytes` are buffered because we cannot know until we have
+     * them whether this is a one-shot PUT or a multipart upload, and a one-shot
+     * PUT needs `content-length` (and a payload hash) up front. Everything beyond
+     * that is uploaded part by part and never all resident at once, so peak
+     * memory is bounded by ONE part regardless of object size. That bound is the
+     * entire point of this method.
+     */
+    async putStream(key, body, contentType, opts) {
+        const partSize = this.cfg.partSizeBytes;
+        const reader = body.getReader();
+        const first = await readAtLeast(reader, partSize);
+        if (first.done) {
+            // Whole object fits in one part.
+            reader.releaseLock();
+            return this.putBuffer(key, first.chunk, contentType);
+        }
+        if (opts.contentLength !== undefined && opts.contentLength <= partSize) {
+            // Caller lied about the length; trust the bytes, not the claim.
+        }
+        const uploadId = await this.createMultipartUpload(key, contentType);
+        const parts = [];
+        let total = 0;
+        let partNumber = 0;
+        let pending = first.chunk;
+        try {
+            for (;;) {
+                partNumber += 1;
+                parts.push({ partNumber, etag: await this.uploadPart(key, uploadId, partNumber, pending) });
+                total += pending.byteLength;
+                const next = await readAtLeast(reader, partSize);
+                if (next.chunk.byteLength === 0 && next.done)
+                    break;
+                pending = next.chunk;
+                if (next.done) {
+                    partNumber += 1;
+                    parts.push({
+                        partNumber,
+                        etag: await this.uploadPart(key, uploadId, partNumber, pending),
+                    });
+                    total += pending.byteLength;
+                    break;
+                }
+            }
+            const etag = await this.completeMultipartUpload(key, uploadId, parts);
+            return { bytes: total, etag };
+        }
+        catch (err) {
+            // An abandoned multipart upload is billable storage that no `file` row
+            // points at -- the orphan problem, in its most expensive form. Abort is
+            // best-effort because the original error is the one worth reporting.
+            await this.abortMultipartUpload(key, uploadId).catch(() => { });
+            throw err;
+        }
+        finally {
+            reader.releaseLock();
+        }
+    }
+    async createMultipartUpload(key, contentType) {
+        const res = await this.signedFetch({
+            method: 'POST',
+            key,
+            query: { uploads: '' },
+            body: new Uint8Array(),
+            headers: { 'content-type': contentType },
+        });
+        if (!res.ok)
+            throw await s3Error('createMultipartUpload', res);
+        const xml = await res.text();
+        const uploadId = xmlTag(xml, 'UploadId');
+        if (!uploadId)
+            throw new Error('storage createMultipartUpload: no UploadId in response');
+        return uploadId;
+    }
+    async uploadPart(key, uploadId, partNumber, body) {
+        const res = await this.signedFetch({
+            method: 'PUT',
+            key,
+            query: { partNumber: String(partNumber), uploadId },
+            body,
+        });
+        if (!res.ok)
+            throw await s3Error('uploadPart', res);
+        await res.arrayBuffer();
+        const etag = res.headers.get('etag');
+        if (!etag)
+            throw new Error('storage uploadPart: no ETag in response');
+        return etag;
+    }
+    async completeMultipartUpload(key, uploadId, parts) {
+        const xml = '<CompleteMultipartUpload>' +
+            parts
+                .map((p) => `<Part><PartNumber>${p.partNumber}</PartNumber><ETag>${escapeXml(p.etag)}</ETag></Part>`)
+                .join('') +
+            '</CompleteMultipartUpload>';
+        const res = await this.signedFetch({
+            method: 'POST',
+            key,
+            query: { uploadId },
+            body: new TextEncoder().encode(xml),
+            headers: { 'content-type': 'application/xml' },
+        });
+        if (!res.ok)
+            throw await s3Error('completeMultipartUpload', res);
+        const text = await res.text();
+        // S3 can return 200 with an <Error> body on this call specifically. Treating
+        // that as success would report a successful upload of a broken object.
+        if (/<Error>/.test(text)) {
+            throw new Error(`storage completeMultipartUpload failed with 200 + Error body: ${xmlTag(text, 'Code') ?? text.slice(0, 200)}`);
+        }
+        return xmlTag(text, 'ETag');
+    }
+    async abortMultipartUpload(key, uploadId) {
+        const res = await this.signedFetch({ method: 'DELETE', key, query: { uploadId } });
+        await res.arrayBuffer().catch(() => { });
+    }
+    // --- reads ----------------------------------------------------------------
+    async get(key) {
+        const res = await this.signedFetch({ method: 'GET', key });
+        if (res.status === 404) {
+            await res.arrayBuffer().catch(() => { });
+            return null;
+        }
+        if (!res.ok)
+            throw await s3Error('get', res);
+        return new Uint8Array(await res.arrayBuffer());
+    }
+    async head(key) {
+        const res = await this.signedFetch({ method: 'HEAD', key });
+        // A HEAD has no body to read, but undici still wants the (empty) body
+        // consumed before the socket goes back to the pool.
+        await res.arrayBuffer().catch(() => { });
+        if (res.status === 404)
+            return null;
+        if (!res.ok)
+            throw new Error(`storage head failed: ${res.status}`);
+        const len = res.headers.get('content-length');
+        const lm = res.headers.get('last-modified');
+        return {
+            size: len === null ? 0 : Number(len),
+            contentType: res.headers.get('content-type'),
+            etag: res.headers.get('etag'),
+            lastModified: lm ? new Date(lm) : null,
+        };
+    }
+    async stream(key, opts = {}) {
+        const headers = {};
+        if (opts.range) {
+            headers['range'] =
+                opts.range.end === undefined
+                    ? `bytes=${opts.range.start}-`
+                    : `bytes=${opts.range.start}-${opts.range.end}`;
+        }
+        const res = await this.signedFetch({ method: 'GET', key, headers });
+        if (res.status === 404) {
+            await res.arrayBuffer().catch(() => { });
+            return null;
+        }
+        // 416 is "the range you asked for does not exist", which for our purposes is
+        // the same answer as "no such bytes" rather than a 500.
+        if (res.status === 416) {
+            await res.arrayBuffer().catch(() => { });
+            return null;
+        }
+        if (!res.ok)
+            throw await s3Error('stream', res);
+        if (!res.body)
+            throw new Error('storage stream: response had no body');
+        const len = res.headers.get('content-length');
+        const out = {
+            body: res.body,
+            size: len === null ? null : Number(len),
+            contentType: res.headers.get('content-type'),
+            etag: res.headers.get('etag'),
+        };
+        const cr = res.headers.get('content-range');
+        const m = cr && /^bytes (\d+)-(\d+)\/(\d+)$/.exec(cr);
+        if (m)
+            out.range = { start: Number(m[1]), end: Number(m[2]), total: Number(m[3]) };
+        return out;
+    }
+    async delete(key) {
+        const res = await this.signedFetch({ method: 'DELETE', key });
+        await res.arrayBuffer().catch(() => { });
+        // S3 returns 204 for a delete of a key that never existed. 404 is here for
+        // S3-compatible stores that disagree; either way "it is gone" is success.
+        if (!res.ok && res.status !== 404)
+            throw new Error(`storage delete failed: ${res.status}`);
+    }
+    async list(prefix, opts = {}) {
+        const query = {
+            'list-type': '2',
+            prefix,
+            'max-keys': String(Math.max(1, Math.min(opts.limit ?? 1000, 1000))),
+        };
+        if (opts.cursor)
+            query['continuation-token'] = opts.cursor;
+        const res = await this.signedFetch({ method: 'GET', key: '', query });
+        if (!res.ok)
+            throw await s3Error('list', res);
+        const xml = await res.text();
+        const entries = [];
+        for (const c of xml.match(/<Contents>[\s\S]*?<\/Contents>/g) ?? []) {
+            const key = xmlTag(c, 'Key');
+            if (key === null)
+                continue;
+            const lm = xmlTag(c, 'LastModified');
+            entries.push({
+                key: unescapeXml(key),
+                size: Number(xmlTag(c, 'Size') ?? 0),
+                lastModified: lm ? new Date(lm) : null,
+            });
+        }
+        const truncated = xmlTag(xml, 'IsTruncated') === 'true';
+        return { entries, cursor: truncated ? xmlTag(xml, 'NextContinuationToken') : null };
+    }
+    // --- presigning -----------------------------------------------------------
+    /**
+     * A query-string-signed GET URL.
+     *
+     * READ THE WARNING IN `delivery.ts` BEFORE CALLING THIS. The URL is bearer
+     * authority that the object store will honour until it expires, and the
+     * object store has never heard of a grant, a revocation or an org. That is
+     * why it is not reachable from any ordinary delivery path.
+     *
+     * `response-content-type` and `response-content-disposition` are signed into
+     * the URL, so the object store -- not the client -- decides what the bytes are
+     * served as. Without them a redirect would drop the `nosniff`/`attachment`
+     * protections that `deliveryHeaders()` exists to guarantee.
+     */
+    async presignGet(key, opts) {
+        const expires = Math.max(1, Math.min(Math.floor(opts.expiresInSeconds), this.cfg.maxPresignSeconds));
+        const now = new Date();
+        const amzDate = amzDateOf(now);
+        const dateStamp = amzDate.slice(0, 8);
+        const scope = `${dateStamp}/${this.cfg.region}/s3/aws4_request`;
+        const { url, canonicalUri } = this.objectUrl(key);
+        const query = {
+            'X-Amz-Algorithm': 'AWS4-HMAC-SHA256',
+            'X-Amz-Credential': `${this.cfg.accessKeyId}/${scope}`,
+            'X-Amz-Date': amzDate,
+            'X-Amz-Expires': String(expires),
+            'X-Amz-SignedHeaders': 'host',
+        };
+        if (this.cfg.sessionToken)
+            query['X-Amz-Security-Token'] = this.cfg.sessionToken;
+        if (opts.responseContentType)
+            query['response-content-type'] = opts.responseContentType;
+        if (opts.responseContentDisposition) {
+            query['response-content-disposition'] = opts.responseContentDisposition;
+        }
+        const canonicalRequest = [
+            'GET',
+            canonicalUri,
+            canonicalQueryString(query),
+            `host:${url.host}\n`,
+            'host',
+            'UNSIGNED-PAYLOAD',
+        ].join('\n');
+        const signature = this.sign(dateStamp, amzDate, scope, canonicalRequest);
+        query['X-Amz-Signature'] = signature;
+        return `${url.origin}${canonicalUri}?${canonicalQueryString(query)}`;
+    }
+    // --- signing --------------------------------------------------------------
+    /**
+     * Path-style: `https://host/<bucket>/<key>`. Virtual-hosted:
+     * `https://<bucket>.host/<key>`.
+     *
+     * The canonical URI is built by RFC-3986-encoding each SEGMENT and is carried
+     * separately from `URL.pathname`, because `new URL()` normalises `.`/`..`
+     * segments and re-encodes some characters. Signing one string and sending
+     * another is the classic SigV4 bug and produces a 403 that looks like a
+     * credentials problem.
+     */
+    objectUrl(key) {
+        const base = new URL(this.cfg.endpoint);
+        const segments = key === '' ? [] : key.split('/');
+        let host = base.host;
+        let path;
+        if (this.cfg.pathStyle) {
+            path = '/' + [this.cfg.bucket, ...segments].map(rfc3986).join('/');
+        }
+        else {
+            host = `${this.cfg.bucket}.${base.host}`;
+            path = '/' + segments.map(rfc3986).join('/');
+        }
+        const url = new URL(`${base.protocol}//${host}${path}`);
+        return { url, canonicalUri: path };
+    }
+    sign(dateStamp, _amzDate, scope, canonicalRequest) {
+        const stringToSign = [
+            'AWS4-HMAC-SHA256',
+            _amzDate,
+            scope,
+            sha256Hex(Buffer.from(canonicalRequest, 'utf8')),
+        ].join('\n');
+        let k = Buffer.from(`AWS4${this.cfg.secretAccessKey}`, 'utf8');
+        for (const part of [dateStamp, this.cfg.region, 's3', 'aws4_request']) {
+            k = createHmac('sha256', k).update(part, 'utf8').digest();
+        }
+        return createHmac('sha256', k).update(stringToSign, 'utf8').digest('hex');
+    }
+    async signedFetch(req) {
+        const { url, canonicalUri } = this.objectUrl(req.key);
+        const query = req.query ?? {};
+        const cqs = canonicalQueryString(query);
+        const now = new Date();
+        const amzDate = amzDateOf(now);
+        const dateStamp = amzDate.slice(0, 8);
+        const payloadHash = sha256Hex(req.body ?? new Uint8Array());
+        const headers = {
+            host: url.host,
+            'x-amz-content-sha256': payloadHash,
+            'x-amz-date': amzDate,
+        };
+        if (this.cfg.sessionToken)
+            headers['x-amz-security-token'] = this.cfg.sessionToken;
+        // Lowercase every supplied header name: SigV4 canonicalises on the lowercase
+        // name and sorts on it, so a `Content-Type` from a caller would sort into a
+        // different position than the `content-type` actually sent.
+        for (const [k, v] of Object.entries(req.headers ?? {}))
+            headers[k.toLowerCase()] = v;
+        const names = Object.keys(headers).sort();
+        const signedHeaders = names.join(';');
+        // Header values are trimmed AND internal whitespace runs collapsed, per the
+        // SigV4 spec. Skipping the collapse silently breaks any value with a double
+        // space in it -- e.g. a content-disposition filename.
+        const canonicalHeaders = names.map((h) => `${h}:${canonicalHeaderValue(headers[h])}\n`).join('');
+        const canonicalRequest = [
+            req.method,
+            canonicalUri,
+            cqs,
+            canonicalHeaders,
+            signedHeaders,
+            payloadHash,
+        ].join('\n');
+        const scope = `${dateStamp}/${this.cfg.region}/s3/aws4_request`;
+        const signature = this.sign(dateStamp, amzDate, scope, canonicalRequest);
+        headers['authorization'] =
+            `AWS4-HMAC-SHA256 Credential=${this.cfg.accessKeyId}/${scope}, ` +
+                `SignedHeaders=${signedHeaders}, Signature=${signature}`;
+        const target = cqs === '' ? `${url.origin}${canonicalUri}` : `${url.origin}${canonicalUri}?${cqs}`;
+        // `host` is set by the HTTP client from the URL and cannot be overridden in
+        // undici; it is in `headers` only so that it is signed. Sending it too is
+        // harmless where allowed and rejected where not, so it is dropped here and
+        // the signature is still computed over the value the client will send.
+        const { host: _host, ...wire } = headers;
+        return fetch(target, {
+            method: req.method,
+            headers: wire,
+            ...(req.body !== undefined && req.method !== 'GET' && req.method !== 'HEAD'
+                ? { body: req.body }
+                : {}),
+        });
+    }
+}
+// -----------------------------------------------------------------------------
+// SigV4 primitives
+// -----------------------------------------------------------------------------
+function sha256Hex(data) {
+    return createHash('sha256').update(data).digest('hex');
+}
+function amzDateOf(d) {
+    return d.toISOString().replace(/[:-]|\.\d{3}/g, '');
+}
+/**
+ * RFC 3986 unreserved-set encoding.
+ *
+ * `encodeURIComponent` leaves `!'()*` alone and `encodeURI` additionally leaves
+ * `#?&=+,:;@$` alone. The previous implementation used `encodeURI` on the whole
+ * key, which meant a key containing `#` truncated the URL at the fragment, a key
+ * containing `?` started a query string, and a key containing `+` signed one
+ * byte sequence and sent another. Keys are constructed by us today, but "the
+ * caller never puts a `#` in a key" is not a property the type system carries.
+ */
+export function rfc3986(s) {
+    return encodeURIComponent(s).replace(/[!'()*]/g, (c) => '%' + c.charCodeAt(0).toString(16).toUpperCase());
+}
+/** Sorted by encoded key, then encoded value. Empty values keep their `=`. */
+export function canonicalQueryString(query) {
+    return Object.entries(query)
+        .map(([k, v]) => [rfc3986(k), rfc3986(v)])
+        .sort((a, b) => (a[0] < b[0] ? -1 : a[0] > b[0] ? 1 : a[1] < b[1] ? -1 : a[1] > b[1] ? 1 : 0))
+        .map(([k, v]) => `${k}=${v}`)
+        .join('&');
+}
+function canonicalHeaderValue(v) {
+    return v.trim().replace(/\s+/g, ' ');
+}
+// -----------------------------------------------------------------------------
+// Small helpers
+// -----------------------------------------------------------------------------
+/**
+ * Read until `n` bytes are available or the stream ends.
+ *
+ * `done` means "the stream is finished AND this is everything that was left",
+ * which is what lets `putStream` decide between a one-shot PUT and multipart
+ * without a second read.
+ */
+async function readAtLeast(reader, n) {
+    const chunks = [];
+    let total = 0;
+    while (total < n) {
+        const { done, value } = await reader.read();
+        if (done)
+            return { chunk: concat(chunks, total), done: true };
+        if (!value || value.byteLength === 0)
+            continue;
+        chunks.push(value);
+        total += value.byteLength;
+    }
+    return { chunk: concat(chunks, total), done: false };
+}
+function concat(chunks, total) {
+    if (chunks.length === 1 && chunks[0].byteLength === total)
+        return chunks[0];
+    const out = new Uint8Array(total);
+    let at = 0;
+    for (const c of chunks) {
+        out.set(c, at);
+        at += c.byteLength;
+    }
+    return out;
+}
+function xmlTag(xml, tag) {
+    const m = new RegExp(`<${tag}>([\\s\\S]*?)</${tag}>`).exec(xml);
+    return m ? (m[1] ?? null) : null;
+}
+function escapeXml(s) {
+    return s.replace(/[<>&'"]/g, (c) => c === '<' ? '&lt;' : c === '>' ? '&gt;' : c === '&' ? '&amp;' : c === "'" ? '&apos;' : '&quot;');
+}
+function unescapeXml(s) {
+    return s
+        .replace(/&lt;/g, '<')
+        .replace(/&gt;/g, '>')
+        .replace(/&quot;/g, '"')
+        .replace(/&apos;/g, "'")
+        .replace(/&amp;/g, '&');
+}
+/**
+ * Turn an S3 error response into an Error carrying the store's own error code.
+ *
+ * The status alone is not enough to act on: `AccessDenied`, `SignatureDoesNotMatch`
+ * and `InvalidAccessKeyId` are all 403 and mean three completely different
+ * operational problems (permissions / our bug / rotated key). Throwing the raw
+ * status is how a signing bug spends a week being investigated as an IAM policy.
+ */
+async function s3Error(op, res) {
+    let code = null;
+    let message = null;
+    try {
+        const text = await res.text();
+        code = xmlTag(text, 'Code');
+        message = xmlTag(text, 'Message');
+    }
+    catch {
+        /* body already consumed or not XML */
+    }
+    const err = new Error(`storage ${op} failed: ${res.status}${code ? ` ${code}` : ''}${message ? ` -- ${message}` : ''}`);
+    err.s3Code = code;
+    err.status = res.status;
+    return err;
+}
+//# sourceMappingURL=storage.js.map