@thailandhosting/object-storage 0.0.0-stage → 1.1.0

package/dist/client.js

@@ -0,0 +1,711 @@
+import { createHash } from 'node:crypto';
+import { open, mkdir, rename, rm, stat } from 'node:fs/promises';
+import { dirname, extname } from 'node:path';
+import { Readable } from 'node:stream';
+import { IntegrityError, NotFoundError, NotModifiedError, ObjectStorageError, PreconditionFailedError, TokenError } from "./errors.js";
+import { contentDigest, sha256FromField, signRequest } from "./signing.js";
+export const VERSION = '1.0.0';
+const MiB = 1024 * 1024;
+const MIN_PART_SIZE = 5 * MiB;
+const MAX_PARTS = 10000;
+const RETRY_STATUSES = new Set([429, 500, 502, 503, 504]);
+const escapeKey = (key) => key.split('/').map(encodeURIComponent).join('/');
+const md5 = (data) => createHash('md5').update(data).digest('hex');
+const toBytes = (b) => (typeof b === 'string' ? Buffer.from(b) : b);
+const sleep = (ms, signal) => new Promise((resolve, reject) => {
+    if (signal?.aborted)
+        return reject(signal.reason);
+    const t = setTimeout(() => { signal?.removeEventListener('abort', onAbort); resolve(); }, ms);
+    const onAbort = () => { clearTimeout(t); reject(signal.reason); };
+    signal?.addEventListener('abort', onAbort, { once: true });
+});
+const backoff = (attempt) => {
+    const d = Math.min(200 * 2 ** Math.min(attempt, 6), 10_000);
+    return d / 2 + Math.random() * (d / 2);
+};
+/** Retry-After (seconds or an HTTP date) in ms, at most 30 s; 0 when absent. */
+function retryAfter(v) {
+    if (!v)
+        return 0;
+    const ms = /^\d+$/.test(v.trim()) ? Number(v) * 1000 : Date.parse(v) - Date.now();
+    return ms > 0 ? Math.min(ms, 30_000) : 0;
+}
+/** An If-Match / If-None-Match value: `*`, or each ETag quoted. */
+const etagList = (v) => (v.trim() === '*' ? '*' : v.split(',').map((e) => `"${e.trim().replace(/^W\//, '').replace(/"/g, '')}"`).join(', '));
+function conditionHeaders(o, h = {}) {
+    if (o.ifMatch)
+        h['If-Match'] = etagList(o.ifMatch);
+    if (o.ifNoneMatch)
+        h['If-None-Match'] = etagList(o.ifNoneMatch);
+    if (o.ifModifiedSince)
+        h['If-Modified-Since'] = o.ifModifiedSince.toUTCString();
+    if (o.ifUnmodifiedSince)
+        h['If-Unmodified-Since'] = o.ifUnmodifiedSince.toUTCString();
+    return h;
+}
+/** Calls that took a bare signal take an options object too. */
+const optionsOf = (v) => (v === undefined ? {} : v instanceof AbortSignal ? { signal: v } : v);
+/** The base64 SHA-256 a full download must have, when the service gave one for the bytes as sent. */
+function expectedDigest(h) {
+    const enc = h.get('content-encoding');
+    // fetch decodes compressed bodies, so their bytes are not the representation's.
+    if (enc && enc.toLowerCase() !== 'identity')
+        return undefined;
+    return sha256FromField(h.get('repr-digest'));
+}
+function checkDigest(want, got, key) {
+    if (want !== got)
+        throw new IntegrityError(`${key}: the downloaded data does not match the object's Repr-Digest (sha-256 ${want}, got ${got})`);
+}
+/** Passes a body through, failing it at the end if its SHA-256 is not `want`. */
+function verifying(body, want, key) {
+    const hash = createHash('sha256');
+    return body.pipeThrough(new TransformStream({
+        transform(chunk, ctrl) {
+            hash.update(chunk);
+            ctrl.enqueue(chunk);
+        },
+        flush() {
+            checkDigest(want, hash.digest('base64'), key);
+        },
+    }));
+}
+function checkETag(etag, digest, what) {
+    const e = etag.replace(/"/g, '');
+    if (e.length === 32 && !e.includes('-') && e !== digest) {
+        throw new IntegrityError(`${what}: the stored data does not match what was sent (ETag ${e}, MD5 ${digest})`);
+    }
+}
+const CONTENT_TYPES = {
+    '.txt': 'text/plain', '.html': 'text/html', '.htm': 'text/html', '.css': 'text/css', '.js': 'text/javascript', '.mjs': 'text/javascript',
+    '.json': 'application/json', '.xml': 'application/xml', '.csv': 'text/csv', '.md': 'text/markdown', '.pdf': 'application/pdf',
+    '.zip': 'application/zip', '.gz': 'application/gzip', '.tar': 'application/x-tar', '.7z': 'application/x-7z-compressed',
+    '.png': 'image/png', '.jpg': 'image/jpeg', '.jpeg': 'image/jpeg', '.gif': 'image/gif', '.webp': 'image/webp', '.svg': 'image/svg+xml',
+    '.avif': 'image/avif', '.ico': 'image/x-icon', '.mp4': 'video/mp4', '.webm': 'video/webm', '.mov': 'video/quicktime', '.mp3': 'audio/mpeg',
+    '.wav': 'audio/wav', '.ogg': 'audio/ogg', '.woff': 'font/woff', '.woff2': 'font/woff2', '.wasm': 'application/wasm',
+};
+const guessType = (name) => CONTENT_TYPES[extname(name).toLowerCase()] ?? 'application/octet-stream';
+const parseDate = (v) => (v ? new Date(v) : undefined);
+function objectFromJSON(d) {
+    return {
+        key: d.key ?? '',
+        size: Number(d.size ?? 0),
+        etag: String(d.etag ?? '').replace(/"/g, ''),
+        lastModified: parseDate(d.lastModified),
+        contentType: d.contentType || undefined,
+        metadata: d.metadata ?? {},
+    };
+}
+function objectFromHeaders(key, h) {
+    const cr = h.get('content-range');
+    const size = cr && cr.includes('/') ? Number(cr.split('/')[1]) : Number(h.get('content-length') ?? 0);
+    const metadata = {};
+    h.forEach((v, k) => { if (k.startsWith('x-meta-'))
+        metadata[k.slice(7)] = v; });
+    return {
+        key, size, etag: (h.get('etag') ?? '').replace(/"/g, ''), lastModified: parseDate(h.get('last-modified')), contentType: h.get('content-type') ?? undefined, metadata,
+        digest: h.get('repr-digest') ?? undefined,
+    };
+}
+/** The Authorization value from a token provider; its failure is a TokenError. */
+async function bearer(provider) {
+    let token;
+    try {
+        token = await provider();
+    }
+    catch (err) {
+        throw new TokenError(`tokenProvider failed: ${err instanceof Error ? err.message : err}`, err);
+    }
+    if (!token || typeof token !== 'string')
+        throw new TokenError('tokenProvider gave no token');
+    return 'Bearer ' + token;
+}
+/** Runs task(0..n-1), `workers` at a time; the first failure stops new work and is thrown. */
+async function parallel(workers, n, task) {
+    let next = 0;
+    let failed;
+    const run = async () => {
+        while (failed === undefined && next < n) {
+            const i = next++;
+            try {
+                await task(i);
+            }
+            catch (e) {
+                failed ??= e;
+            }
+        }
+    };
+    await Promise.all(Array.from({ length: Math.min(workers, n) }, run));
+    if (failed !== undefined)
+        throw failed;
+}
+/** A client of one region's Object Storage endpoint. Reuse it: it keeps connections open. */
+export class Client {
+    partSize;
+    multipartThreshold;
+    concurrency;
+    maxRetries;
+    base;
+    /** @internal */ origin;
+    keyId;
+    secret;
+    /** @internal */ tokenProvider;
+    ua;
+    fetch;
+    constructor(opts) {
+        if (!opts.endpoint || !opts.accessKeyId !== !opts.secretAccessKey) {
+            throw new Error('endpoint is required, and accessKeyId and secretAccessKey together');
+        }
+        if (opts.tokenProvider && opts.accessKeyId)
+            throw new Error('give an access key or tokenProvider, not both');
+        const u = new URL(opts.endpoint);
+        if (u.protocol !== 'https:' && u.protocol !== 'http:')
+            throw new Error(`invalid endpoint ${opts.endpoint}`);
+        const path = u.pathname.replace(/\/+$/, '').replace(/\/v1$/, '');
+        this.origin = `${u.protocol}//${u.host}${path}`;
+        this.base = `${this.origin}/v1`;
+        this.keyId = opts.accessKeyId ?? '';
+        this.secret = opts.secretAccessKey ?? '';
+        this.tokenProvider = opts.tokenProvider;
+        this.partSize = Math.max(opts.partSize ?? 16 * MiB, MIN_PART_SIZE);
+        this.multipartThreshold = opts.multipartThreshold ?? 2 * this.partSize;
+        this.concurrency = Math.max(1, opts.concurrency ?? 8);
+        this.maxRetries = Math.max(0, opts.maxRetries ?? 4);
+        this.ua = `thailandhosting-object-storage-sdk-node/${VERSION}${opts.userAgent ? ' ' + opts.userAgent : ''}`;
+        this.fetch = opts.fetch ?? globalThis.fetch.bind(globalThis);
+    }
+    /** @internal Sends a request with retries; the caller reads or cancels the body. */
+    async request(r) {
+        let url = this.base + r.path;
+        if (r.query) {
+            const q = new URLSearchParams();
+            for (const [k, v] of Object.entries(r.query))
+                if (v !== undefined && v !== '')
+                    q.set(k, String(v));
+            const s = q.toString();
+            if (s)
+                url += '?' + s;
+        }
+        const headers = { 'User-Agent': this.ua, ...r.headers };
+        // Every body carries its digest; the service checks it as the bytes arrive.
+        if (r.body)
+            headers['Content-Digest'] = contentDigest(r.body);
+        for (let attempt = 0;; attempt++) {
+            if (this.tokenProvider) {
+                // Asked for on every attempt: a retry picks up a refreshed token.
+                headers.Authorization = await bearer(this.tokenProvider);
+            }
+            else if (this.keyId) {
+                // A fresh signature each attempt: created must be close to the service's clock.
+                Object.assign(headers, signRequest({ method: r.method, url, accessKeyId: this.keyId, secretAccessKey: this.secret, contentDigest: headers['Content-Digest'] }));
+            }
+            let resp;
+            try {
+                resp = await this.fetch(url, { method: r.method, headers, body: r.body, signal: r.signal, redirect: 'manual' });
+            }
+            catch (e) {
+                if (r.signal?.aborted)
+                    throw e;
+                // The request may have reached the service; only a repeatable one is sent again.
+                if (attempt < this.maxRetries && (r.method !== 'POST' || r.retryPost)) {
+                    await sleep(backoff(attempt), r.signal);
+                    continue;
+                }
+                throw e;
+            }
+            const okStatus = r.expect ? r.expect.includes(resp.status) : resp.status >= 200 && resp.status < 300;
+            if (okStatus)
+                return resp;
+            const err = await readError(resp);
+            const retryable = RETRY_STATUSES.has(resp.status) && (r.method !== 'POST' || (!!r.retryPost && (resp.status === 429 || resp.status === 503)));
+            if (retryable && attempt < this.maxRetries) {
+                // Retry-After (sent with 503) is the least the service wants us to wait.
+                await sleep(Math.max(backoff(attempt), retryAfter(resp.headers.get('retry-after'))), r.signal);
+                continue;
+            }
+            throw err;
+        }
+    }
+    /** @internal */
+    async json(method, path, payload, opts = {}) {
+        const resp = await this.request({
+            method, path, query: opts.query, retryPost: opts.retryPost, signal: opts.signal,
+            headers: payload === undefined ? opts.headers : { ...opts.headers, 'Content-Type': 'application/json' },
+            body: payload === undefined ? undefined : Buffer.from(JSON.stringify(payload)),
+        });
+        const text = await resp.text();
+        return (text ? JSON.parse(text) : undefined);
+    }
+    /** The buckets this access key can use. */
+    async listBuckets(signal) {
+        const d = await this.json('GET', '/buckets', undefined, { signal });
+        return d.buckets.map((b) => ({ name: b.name, region: b.region, createdAt: parseDate(b.createdAt) }));
+    }
+    /** Create a bucket (3-63 characters of a-z, 0-9, dots and hyphens). */
+    async createBucket(name, signal) {
+        const b = await this.json('PUT', '/buckets/' + encodeURIComponent(name), undefined, { signal });
+        return { name: b?.name ?? name, region: b?.region ?? '', createdAt: parseDate(b?.createdAt), public: b?.public };
+    }
+    async getBucket(name, signal) {
+        const b = await this.json('GET', '/buckets/' + encodeURIComponent(name), undefined, { signal });
+        return { name: b.name, region: b.region, createdAt: parseDate(b.createdAt) };
+    }
+    /** Delete an empty bucket. */
+    async deleteBucket(name, signal) {
+        await this.json('DELETE', '/buckets/' + encodeURIComponent(name), undefined, { signal });
+    }
+    /** A handle for one bucket's objects (no request is made). */
+    bucket(name) {
+        return new Bucket(this, name);
+    }
+    /** @internal */
+    partSizeFor(size) {
+        let ps = this.partSize;
+        if (size > 0 && Math.ceil(size / ps) > MAX_PARTS)
+            ps = Math.ceil(Math.ceil(size / MAX_PARTS) / MiB) * MiB;
+        return ps;
+    }
+}
+/** An error answer as Problem Details (RFC 9457); a HEAD answer has no body, only X-Error-Code. */
+async function readError(resp) {
+    let code = resp.headers.get('x-error-code') ?? '';
+    let message = resp.statusText;
+    const problem = {};
+    try {
+        const doc = JSON.parse(await resp.text());
+        code = doc?.code || code;
+        message = doc?.title || message;
+        problem.type = doc?.type || undefined;
+        problem.instance = doc?.instance || undefined;
+    }
+    catch {
+        // no body, or not JSON
+    }
+    code ||= (resp.statusText || 'error').toLowerCase().replace(/ /g, '_');
+    if (resp.status === 404)
+        return new NotFoundError(code, message, problem);
+    if (resp.status === 412)
+        return new PreconditionFailedError(code, message, problem);
+    return new ObjectStorageError(resp.status, code, message, problem);
+}
+function putHeaders(key, o = {}) {
+    const h = { 'Content-Type': o.contentType || guessType(key) };
+    if (o.cacheControl)
+        h['Cache-Control'] = o.cacheControl;
+    if (o.contentDisposition)
+        h['Content-Disposition'] = o.contentDisposition;
+    if (o.contentEncoding)
+        h['Content-Encoding'] = o.contentEncoding;
+    for (const [k, v] of Object.entries(o.metadata ?? {}))
+        h['X-Meta-' + k] = v;
+    return conditionHeaders(writeConditions(o), h);
+}
+/** The write conditions of upload options (ifNotExists is ifNoneMatch: '*'). */
+const writeConditions = (o) => ({ ifMatch: o.ifMatch, ifNoneMatch: o.ifNotExists ? '*' : o.ifNoneMatch });
+/** The objects of one bucket. */
+export class Bucket {
+    name;
+    /** @internal */ c;
+    /** @internal */ path;
+    constructor(client, name) {
+        this.c = client;
+        this.name = name;
+        this.path = '/buckets/' + encodeURIComponent(name);
+    }
+    obj(key) {
+        return this.path + '/objects/' + escapeKey(key);
+    }
+    /** Upload a string or bytes in one request. */
+    async put(key, data, opts = {}) {
+        const bytes = toBytes(data);
+        const resp = await this.c.request({ method: 'PUT', path: this.obj(key), headers: putHeaders(key, opts), body: bytes, signal: opts.signal });
+        const info = objectFromJSON(await resp.json());
+        checkETag(info.etag, md5(bytes), key);
+        return info;
+    }
+    /** Stream an object (or a range of it). `info.size` is the whole object's size. A whole-object
+     *  download with a Repr-Digest is checked as it is read: the body fails with IntegrityError at
+     *  its end if the bytes do not match. */
+    async get(key, opts = {}) {
+        const headers = conditionHeaders(opts);
+        const ranged = !!(opts.offset || opts.length);
+        if (ranged) {
+            const start = opts.offset ?? 0;
+            headers.Range = opts.length ? `bytes=${start}-${start + opts.length - 1}` : `bytes=${start}-`;
+        }
+        const resp = await this.c.request({ method: 'GET', path: this.obj(key), headers, expect: [200, 206, 304], signal: opts.signal });
+        if (resp.status === 304) {
+            await resp.body?.cancel();
+            throw new NotModifiedError(key);
+        }
+        let body = resp.body ?? new ReadableStream({ start: (c) => c.close() });
+        const want = resp.status === 200 ? expectedDigest(resp.headers) : undefined;
+        if (want)
+            body = verifying(body, want, key);
+        return {
+            info: objectFromHeaders(key, resp.headers),
+            contentRange: resp.headers.get('content-range') ?? undefined,
+            body,
+            toNodeStream: () => Readable.fromWeb(body),
+        };
+    }
+    /** Download a whole object into memory, checked against its Repr-Digest when it has one. */
+    async getBytes(key, signal) {
+        const resp = await this.c.request({ method: 'GET', path: this.obj(key), signal });
+        const data = new Uint8Array(await resp.arrayBuffer());
+        const want = expectedDigest(resp.headers);
+        if (want)
+            checkDigest(want, createHash('sha256').update(data).digest('base64'), key);
+        return data;
+    }
+    /** Download a whole object as UTF-8 text. */
+    async getText(key, signal) {
+        return new TextDecoder().decode(await this.getBytes(key, signal));
+    }
+    /** An object's info without its data. With `ifNoneMatch` / `ifModifiedSince` it throws
+     *  NotModifiedError when the object is unchanged. */
+    async head(key, opts) {
+        const o = optionsOf(opts);
+        const resp = await this.c.request({ method: 'HEAD', path: this.obj(key), headers: conditionHeaders(o), expect: [200, 304], signal: o.signal });
+        if (resp.status === 304)
+            throw new NotModifiedError(key);
+        return objectFromHeaders(key, resp.headers);
+    }
+    async exists(key, signal) {
+        try {
+            await this.head(key, signal);
+            return true;
+        }
+        catch (e) {
+            if (e instanceof NotFoundError)
+                return false;
+            throw e;
+        }
+    }
+    /** Delete an object; deleting a missing one succeeds (unless `ifMatch` wanted one). */
+    async delete(key, opts) {
+        const o = optionsOf(opts);
+        const resp = await this.c.request({ method: 'DELETE', path: this.obj(key), headers: conditionHeaders(o), signal: o.signal });
+        await resp.body?.cancel();
+    }
+    /** Delete keys in parallel. */
+    async deleteMany(keys, signal) {
+        await parallel(this.c.concurrency, keys.length, (i) => this.delete(keys[i], signal));
+    }
+    /** Copy inside the service, without downloading. */
+    async copy(srcKey, dstKey, opts = {}) {
+        const payload = { from: { bucket: opts.sourceBucket ?? this.name, key: srcKey }, key: dstKey };
+        if (opts.metadata)
+            payload.metadata = opts.metadata;
+        return objectFromJSON(await this.c.json('POST', this.path + '/copy', payload, { retryPost: true, signal: opts.signal }));
+    }
+    /** One page of objects (and folders, with a delimiter). */
+    async list(opts = {}) {
+        const d = await this.c.json('GET', this.path + '/objects', undefined, {
+            query: { prefix: opts.prefix, delimiter: opts.delimiter, cursor: opts.cursor, limit: opts.limit }, signal: opts.signal,
+        });
+        return { objects: (d.objects ?? []).map(objectFromJSON), folders: d.folders ?? [], nextCursor: d.nextCursor || undefined };
+    }
+    /** Every object under prefix: `for await (const obj of bucket.objects('photos/'))`. */
+    async *objects(prefix = '', opts = {}) {
+        let cursor;
+        do {
+            const page = await this.list({ prefix, cursor, limit: opts.pageSize, signal: opts.signal });
+            yield* page.objects;
+            cursor = page.nextCursor;
+        } while (cursor);
+    }
+    /** A URL that downloads (or, with `upload: true`, uploads) one object without a key. Needs a client with an access key. */
+    async createLink(key, opts = {}) {
+        if (this.c.tokenProvider)
+            throw new Error("createLink needs an access key: a link is signed with the key's secret, and a service account has none");
+        const d = await this.c.json('POST', this.path + '/links', { key, expiresIn: opts.expiresIn ?? 3600, method: opts.upload ? 'PUT' : 'GET' }, { retryPost: true, signal: opts.signal });
+        return { url: d.url, method: d.method, expiresAt: parseDate(d.expiresAt) };
+    }
+    /** What anyone may read in the bucket. */
+    async publicAccess(opts = {}) {
+        const d = await this.c.json('GET', this.path + '/public', undefined, { signal: opts.signal });
+        return d.rules ?? [];
+    }
+    /**
+     * Replace what anyone may read: `[]` makes the bucket private, `[{ prefix: '' }]` opens all of it,
+     * `[{ prefix: 'images/' }]` one folder. Needs a key allowed to manage buckets; takes effect within
+     * about 15 seconds. Resolves to the rules as stored.
+     */
+    async setPublicAccess(rules, opts = {}) {
+        const payload = { rules: rules.map((r) => ({ prefix: r.prefix, list: !!r.list })) };
+        const d = await this.c.json('PUT', this.path + '/public', payload, { retryPost: true, signal: opts.signal });
+        return d.rules ?? [];
+    }
+    /** The address anyone can open `key` at once its folder (or the bucket) is public. No request is made. */
+    publicUrl(key) {
+        return `${this.c.origin}/${encodeURIComponent(this.name)}/${escapeKey(key)}`;
+    }
+    /** Start a multipart upload (uploadFile and upload do this for you). */
+    async createMultipartUpload(key, opts = {}) {
+        const payload = { key, contentType: opts.contentType || guessType(key) };
+        if (opts.metadata)
+            payload.metadata = opts.metadata;
+        const d = await this.c.json('POST', this.path + '/uploads', payload, { retryPost: true, signal: opts.signal });
+        return new MultipartUpload(this, key, d.uploadId);
+    }
+    resumeMultipartUpload(key, uploadId) {
+        return new MultipartUpload(this, key, uploadId);
+    }
+    /** Upload a local file. Large files go up as parts read from the file and
+     *  sent in parallel; a part is re-read if it must be sent again. `ifMatch` /
+     *  `ifNoneMatch` are checked when the parts are joined. */
+    async uploadFile(key, path, opts = {}) {
+        const { size } = await stat(path);
+        const options = { ...opts, contentType: opts.contentType || guessType(path) };
+        const fh = await open(path, 'r');
+        try {
+            if (size <= this.c.multipartThreshold) {
+                const buf = Buffer.allocUnsafe(size);
+                await readFully(fh, buf, 0);
+                return await this.put(key, buf, options);
+            }
+            const ps = this.c.partSizeFor(size);
+            const count = Math.ceil(size / ps);
+            const up = await this.createMultipartUpload(key, options);
+            const parts = new Array(count);
+            try {
+                await parallel(this.c.concurrency, count, async (i) => {
+                    const len = Math.min(ps, size - i * ps);
+                    const buf = Buffer.allocUnsafe(len);
+                    await readFully(fh, buf, i * ps);
+                    parts[i] = await up.uploadPart(i + 1, buf, opts.signal);
+                });
+                return await up.complete(parts, { ...writeConditions(opts), signal: opts.signal });
+            }
+            catch (e) {
+                await up.abortQuietly();
+                throw e;
+            }
+        }
+        finally {
+            await fh.close();
+        }
+    }
+    /** Upload what a stream yields (a pipe, an HTTP request, a generated
+     *  export) without knowing its size. Parts are sent in parallel, holding at
+     *  most `concurrency + 1` in memory; every part (or a small stream, sent in
+     *  one request) is buffered, so its Content-Digest is known before it is sent. */
+    async upload(key, source, opts = {}) {
+        const ps = this.c.partSize;
+        const chunks = partChunks(source, ps);
+        const first = await chunks.next();
+        if (first.done)
+            return this.put(key, new Uint8Array(0), opts);
+        const second = first.value.length < ps ? await chunks.next() : undefined;
+        if (second?.done)
+            return this.put(key, first.value, opts);
+        const up = await this.createMultipartUpload(key, opts);
+        const parts = [];
+        const inflight = new Set();
+        let failed;
+        try {
+            let n = 1;
+            const send = (data, num) => {
+                const p = up.uploadPart(num, data, opts.signal)
+                    .then((part) => { parts.push(part); }, (e) => { failed ??= e; })
+                    .finally(() => inflight.delete(p));
+                inflight.add(p);
+            };
+            send(first.value, n++);
+            if (second && !second.done)
+                send(second.value, n++);
+            for await (const data of chunks) {
+                if (failed !== undefined)
+                    break;
+                if (n > MAX_PARTS)
+                    throw new Error(`more than ${MAX_PARTS} parts of ${ps} bytes: use a larger partSize`);
+                while (inflight.size >= this.c.concurrency)
+                    await Promise.race(inflight);
+                if (failed !== undefined)
+                    break;
+                send(data, n++);
+            }
+            await Promise.all(inflight);
+            if (failed !== undefined)
+                throw failed;
+            return await up.complete(parts, { ...writeConditions(opts), signal: opts.signal });
+        }
+        catch (e) {
+            await Promise.allSettled(inflight);
+            await up.abortQuietly();
+            throw e;
+        }
+    }
+    /** Save an object to `path`. Large objects come down as parallel ranges
+     *  pinned to the object's ETag, written straight to their place in the
+     *  file; the data goes to `path + '.download'` and is renamed into place
+     *  only once it matches the object's Repr-Digest (when it has one). */
+    async downloadFile(key, path, signal) {
+        const info = await this.head(key, signal);
+        await mkdir(dirname(path), { recursive: true });
+        const tmp = path + '.download';
+        const fh = await open(tmp, 'w+'); // read back to check a ranged download's digest
+        try {
+            await fh.truncate(info.size);
+            if (info.size <= this.c.multipartThreshold) {
+                const hash = createHash('md5');
+                const dl = await this.get(key, { ifMatch: info.etag, signal });
+                let pos = 0;
+                for await (const chunk of dl.body) {
+                    hash.update(chunk);
+                    await writeFully(fh, chunk, pos);
+                    pos += chunk.length;
+                }
+                if (pos !== info.size)
+                    throw new IntegrityError(`${key}: got ${pos} of ${info.size} bytes`);
+                checkETag(info.etag, hash.digest('hex'), key);
+            }
+            else {
+                const ps = this.c.partSize;
+                await parallel(this.c.concurrency, Math.ceil(info.size / ps), (i) => this.downloadRange(key, info.etag, fh, i * ps, Math.min(ps, info.size - i * ps), signal));
+                // The ranges arrived out of order: hash the whole file once they are all in.
+                const want = sha256FromField(info.digest);
+                if (want)
+                    checkDigest(want, await hashFile(fh, info.size), key);
+            }
+            await fh.close();
+            await rename(tmp, path);
+            return info;
+        }
+        catch (e) {
+            await fh.close().catch(() => undefined);
+            await rm(tmp, { force: true });
+            throw e;
+        }
+    }
+    async downloadRange(key, etag, fh, offset, length, signal) {
+        let done = 0;
+        for (let attempt = 0; done < length; attempt++) {
+            try {
+                const dl = await this.get(key, { offset: offset + done, length: length - done, ifMatch: etag, signal });
+                for await (const chunk of dl.body) {
+                    await writeFully(fh, chunk, offset + done);
+                    done += chunk.length;
+                }
+            }
+            catch (e) {
+                if (e instanceof ObjectStorageError || e instanceof TokenError || signal?.aborted || attempt >= this.c.maxRetries)
+                    throw e;
+            }
+            if (done < length) {
+                // The connection broke mid-range: carry on from where it stopped.
+                if (attempt >= this.c.maxRetries)
+                    throw new IntegrityError(`${key}: got ${done} of ${length} bytes at ${offset}`);
+                await sleep(backoff(attempt), signal);
+            }
+        }
+    }
+}
+/** A large upload in progress: send parts (any order, in parallel), then complete() or abort(). */
+export class MultipartUpload {
+    bucket;
+    key;
+    uploadId;
+    constructor(bucket, key, uploadId) {
+        this.bucket = bucket;
+        this.key = key;
+        this.uploadId = uploadId;
+    }
+    get path() {
+        return this.bucket.path + '/uploads/' + this.uploadId;
+    }
+    /** Send part `n` (1-10000); every part but the last must be at least 5 MiB. */
+    async uploadPart(n, data, signal) {
+        const bytes = toBytes(data);
+        const resp = await this.bucket.c.request({
+            method: 'PUT', path: `${this.path}/parts/${n}`, headers: { 'Content-Type': 'application/octet-stream' }, body: bytes, signal,
+        });
+        const d = await resp.json();
+        checkETag(String(d.etag), md5(bytes), `part ${n}`);
+        return { number: Number(d.number), etag: String(d.etag).replace(/"/g, ''), size: bytes.length };
+    }
+    async parts(signal) {
+        const d = await this.bucket.c.json('GET', this.path, undefined, { signal });
+        return (d.parts ?? []).map((p) => ({ number: p.number, etag: p.etag, size: p.size }));
+    }
+    /** Join the parts into the object; without `parts`, every part received, in order.
+     *  `ifMatch` / `ifNoneMatch` are checked against the key atomically with the join. */
+    async complete(parts, opts) {
+        const o = optionsOf(opts);
+        const payload = parts ? { parts: [...parts].sort((a, b) => a.number - b.number).map((p) => ({ number: p.number, etag: p.etag })) } : undefined;
+        try {
+            return objectFromJSON(await this.bucket.c.json('POST', this.path + '/complete', payload, { retryPost: true, signal: o.signal, headers: conditionHeaders(o) }));
+        }
+        catch (e) {
+            // A retry after a completion whose answer was lost.
+            if (e instanceof NotFoundError)
+                return this.bucket.head(this.key, o.signal);
+            throw e;
+        }
+    }
+    async abort(signal) {
+        try {
+            await this.bucket.c.json('DELETE', this.path, undefined, { signal });
+        }
+        catch (e) {
+            if (!(e instanceof NotFoundError))
+                throw e;
+        }
+    }
+    /** @internal */
+    async abortQuietly() {
+        await this.abort().catch(() => undefined);
+    }
+}
+async function readFully(fh, buf, position) {
+    let off = 0;
+    while (off < buf.length) {
+        const { bytesRead } = await fh.read(buf, off, buf.length - off, position + off);
+        if (bytesRead === 0)
+            throw new Error('file shrank while it was being uploaded');
+        off += bytesRead;
+    }
+}
+/** The base64 SHA-256 of the first `size` bytes of a file. */
+async function hashFile(fh, size) {
+    const hash = createHash('sha256');
+    const buf = Buffer.allocUnsafe(Math.min(size, 4 * MiB));
+    for (let pos = 0; pos < size;) {
+        const { bytesRead } = await fh.read(buf, 0, Math.min(buf.length, size - pos), pos);
+        if (bytesRead === 0)
+            break;
+        hash.update(buf.subarray(0, bytesRead));
+        pos += bytesRead;
+    }
+    return hash.digest('base64');
+}
+async function writeFully(fh, data, position) {
+    let off = 0;
+    while (off < data.length) {
+        const { bytesWritten } = await fh.write(data, off, data.length - off, position + off);
+        off += bytesWritten;
+    }
+}
+/** Regroups a stream's chunks into parts of exactly `size` bytes (the last may be shorter). */
+async function* partChunks(source, size) {
+    let buf = Buffer.allocUnsafe(size);
+    let fill = 0;
+    for await (const chunk of source) {
+        let off = 0;
+        while (off < chunk.length) {
+            const n = Math.min(size - fill, chunk.length - off);
+            buf.set(chunk.subarray(off, off + n), fill);
+            fill += n;
+            off += n;
+            if (fill === size) {
+                yield buf;
+                buf = Buffer.allocUnsafe(size);
+                fill = 0;
+            }
+        }
+    }
+    if (fill > 0)
+        yield buf.subarray(0, fill);
+}
+//# sourceMappingURL=client.js.map