@teepin/sdk 0.2.0 → 0.3.0-rc.1

package/dist/esm/direct/large.js

@@ -0,0 +1,816 @@
+// Copyright 2026 TEEPIN Project
+// Licensed under the Apache License, Version 2.0
+// Large objects, uploaded directly in parts (TEEPIN-STORAGE-DESIGN.md sections 21.1 D1, 21.2 and 22.4), a port of
+// teepin-python's _large.py with the same rules.
+//
+// One TWS1 stream per object, cut into parts at segment boundaries. The control plane starts the storage network's
+// upload, signs each part (its first sign pins the part's MD5 and SHA-256), and completes it with the wrapped data key.
+//
+// An upload goes through these states, each journaled before its action:
+//
+//     new → sending → completing → completed
+//
+// - new: its idempotency key is journaled, so a lost create answer gets the same upload again.
+// - sending: the upload exists, and its data key (E3: a file of its own, 0600, in the run's directory), stream header
+//   and wrap are journaled, so a crash resumes the remaining parts.
+// - Each part's plaintext SHA-256 is journaled before its first byte leaves (D1 condition a): all of them at create,
+//   taken in the same pass as the whole object's. A part sealed again is read and hashed again first (condition b): a
+//   changed file fails the upload, never mixes two versions.
+// - completing: every part is sent. Complete is idempotent, so a lost answer is asked for again.
+//
+// An upload the storage network or control plane ended (expired, mismatched) starts again under a new create with a
+// fresh key. A final failure cancels it, so its parts aren't kept (and billed, D5) for nothing.
+//
+// A stream whose size isn't known (section 22.1, E2 b) is created without its size and SHA-256, read one part ahead
+// (TWS1's last flag needs to know which part is last), its last part declared at its sign, and the size and SHA-256
+// brought by complete. Nothing can read it again, so it isn't journaled: any failure cancels it, and the caller uploads
+// it again. Memory: each part in flight holds only its ciphertext, and the reader holds the part it hands over, the
+// next, and one more while it seals a part: at most (concurrency + 3) parts.
+import { APIError, DataIntegrityError, FileChangedError, ForbiddenError, PaymentRequiredError, StorageUnavailableError, TeepinError, TooLargeError, UnauthorizedError, } from '../errors.js';
+import { concat, fromBase64 } from './bytes.js';
+import { abortable, joinCapped, linked, objectFrom, Slots, toBase64, uuid7 } from './common.js';
+import { MAX_REBUILDS, storageOutcome, tooSlow } from './engine.js';
+import * as tws1 from './tws1.js';
+const str = (v) => (v === undefined || v === null ? '' : String(v));
+const int = (v) => Math.trunc(Number(v || 0)) || 0;
+const uploadsPath = (bucket) => `/v1/storage/buckets/${encodeURIComponent(bucket)}/uploads`;
+const message = (err) => (err instanceof Error ? err.message : String(err));
+const EMPTY = new Uint8Array(0);
+/** The upload can't go on: start again under a new create, with a fresh key. */
+export class Restart extends Error {
+    constructor(why) {
+        super(why);
+        this.name = 'Restart';
+    }
+}
+/** Errors after which an upload is kept, journaled, for resumeUploads. */
+function keep(err) {
+    return err instanceof StorageUnavailableError || err instanceof UnauthorizedError || err instanceof ForbiddenError || err instanceof PaymentRequiredError;
+}
+/** One large upload's state, journaled when it has a store. The methods tests replace are save and savePart. */
+export class Large {
+    bucket;
+    key;
+    size;
+    sha256;
+    readAt;
+    id = uuid7();
+    idem = uuid7();
+    uploadId = '';
+    state = 'new';
+    dek;
+    header = EMPTY;
+    stream;
+    wrapped = '';
+    keyVersion = 0;
+    /** Part number → its plaintext's SHA-256 (D1 a), taken in the same pass as the whole object's. */
+    plain;
+    resumed = false;
+    restarts = 0;
+    waited = 0;
+    throttled = false;
+    lastError = '';
+    contentType;
+    metadata;
+    ifNoneMatch;
+    ifMatch;
+    partSize;
+    partCount;
+    store;
+    fileId;
+    path;
+    /** Whether the data key's file is written (and so must be deleted). */
+    keyOnDisk = false;
+    constructor(bucket, key, size, sha256, readAt, opts) {
+        this.bucket = bucket;
+        this.key = key;
+        this.size = size;
+        this.sha256 = sha256;
+        this.readAt = readAt;
+        this.contentType = opts.contentType || '';
+        this.metadata = { ...(opts.metadata ?? {}) };
+        this.ifNoneMatch = Boolean(opts.ifNoneMatch);
+        this.ifMatch = opts.ifMatch || '';
+        this.partSize = opts.partSize;
+        this.partCount = tws1.partCount(size, opts.partSize);
+        this.store = opts.store;
+        this.fileId = opts.fileId;
+        this.path = opts.path;
+        this.plain = new Map(opts.partHashes ?? []);
+    }
+    /** Whether its journal survives the process (a resumable upload). */
+    get durable() {
+        return Boolean(this.store?.journal.durable);
+    }
+    row() {
+        return {
+            table: 'uploads',
+            id: this.id,
+            row: {
+                _id: this.id,
+                file_id: this.fileId ?? null,
+                bucket: this.bucket,
+                key: this.key,
+                idempotency_key: this.idem,
+                upload_id: this.uploadId,
+                state: this.state,
+                size: this.size,
+                part_size: this.partSize,
+                sha256: this.sha256,
+                header: toBase64(this.header),
+                wrapped_key: this.wrapped,
+                key_version: this.keyVersion,
+                last_error: this.lastError,
+                updated: Date.now(),
+            },
+        };
+    }
+    partRow(number, plain, md5, sha256, state) {
+        const id = `${this.id}:${number}`;
+        return { table: 'parts', id, row: { _id: id, upload: this.id, number, plain_sha256: plain, md5, sha256, state } };
+    }
+    /** The upload's state, journaled (with its data key first, on disk, while it has one). */
+    async save() {
+        if (!this.store)
+            return;
+        await this.saveKey();
+        await this.store.journal.write([this.row()]);
+    }
+    async savePart(number, plain, md5 = '', sha256 = '', state = 'hashed') {
+        if (!this.store)
+            return;
+        await this.store.journal.write([this.partRow(number, plain, md5, sha256, state)]);
+    }
+    /** D1 (a): every part's hash before any byte leaves; then the data key, header and wrap, before any part is signed. */
+    async saveCreated() {
+        if (!this.store)
+            return;
+        await this.saveKey();
+        const entries = [...this.plain.entries()].sort(([a], [b]) => a - b).map(([n, h]) => this.partRow(n, h, '', '', 'hashed'));
+        await this.store.journal.write([...entries, this.row()]);
+    }
+    async saveKey() {
+        const place = this.store?.place;
+        if (!place || !this.dek || this.keyOnDisk)
+            return;
+        await place.writeKey(this.id, this.dek);
+        this.keyOnDisk = true;
+    }
+    /** Zeroes the data key and deletes its file (E3: promptly). */
+    async forgetKey() {
+        this.dek?.fill(0);
+        this.dek = undefined;
+        this.stream = undefined;
+        const place = this.store?.place;
+        if (place && this.keyOnDisk) {
+            this.keyOnDisk = false;
+            await place.removeKey(this.id).catch(() => undefined);
+        }
+    }
+    /** An upload a crashed run left in its journal. */
+    static async fromRow(row, readAt, opts) {
+        const u = new Large(str(row.bucket), str(row.key), int(row.size), str(row.sha256), readAt, { ...opts, partSize: int(row.part_size) });
+        u.id = str(row._id);
+        u.idem = str(row.idempotency_key);
+        u.uploadId = str(row.upload_id);
+        u.state = str(row.state);
+        const key = await opts.store?.place?.readKey(u.id).catch(() => undefined);
+        if (key && key.length === tws1.KEY_SIZE) {
+            u.dek = key;
+            u.keyOnDisk = true;
+        }
+        u.header = row.header ? fromBase64(str(row.header)) : EMPTY;
+        u.wrapped = str(row.wrapped_key);
+        u.keyVersion = int(row.key_version);
+        for (const p of opts.store?.journal.rows('parts') ?? [])
+            if (p.upload === u.id)
+                u.plain.set(int(p.number), str(p.plain_sha256));
+        u.resumed = true;
+        return u;
+    }
+    /** A new create and a fresh key. The source's part hashes stay: they still catch a file that changed. */
+    async reset() {
+        await this.forgetKey();
+        this.idem = uuid7();
+        this.uploadId = '';
+        this.header = EMPTY;
+        this.wrapped = '';
+        this.keyVersion = 0;
+        this.resumed = false;
+        this.state = 'new';
+    }
+}
+/**
+ * A stream's upload: created without its size, its last part declared at its sign, and its size and SHA-256 brought by
+ * complete. Held in memory only: nothing could read the stream again to resume it.
+ */
+export class StreamUpload {
+    bucket;
+    key;
+    partSize;
+    idem = uuid7();
+    uploadId = '';
+    stream;
+    wrapped = '';
+    keyVersion = 0;
+    path = undefined;
+    /** The measured speed when it shrank the part size (section 22.7), else undefined. */
+    slow;
+    waited = 0;
+    throttled = false;
+    lastError = '';
+    contentType;
+    metadata;
+    ifNoneMatch;
+    ifMatch;
+    constructor(bucket, key, partSize, opts = {}) {
+        this.bucket = bucket;
+        this.key = key;
+        this.partSize = partSize;
+        this.contentType = opts.contentType || '';
+        this.metadata = { ...(opts.metadata ?? {}) };
+        this.ifNoneMatch = Boolean(opts.ifNoneMatch);
+        this.ifMatch = opts.ifMatch || '';
+    }
+}
+/** The most telling of a step's task errors: an abort's reason, then the kinds named, in order, then the first. */
+function telling(errors, kinds, signal) {
+    if (signal?.aborted)
+        return signal.reason;
+    for (const kind of kinds) {
+        const e = errors.find((x) => x instanceof kind);
+        if (e !== undefined)
+            return e;
+    }
+    return errors[0];
+}
+/** Large uploads and streams for one DirectUploads. The methods tests replace are sendSealed and completeStream. */
+export class Parts {
+    up;
+    constructor(up) {
+        this.up = up;
+    }
+    /**
+     * Takes a large upload to its object. A final failure cancels it; an error after which it may resume (storage
+     * unavailable, a revoked key) keeps it, in its journal, when it has one on disk. An abort leaves a journaled upload
+     * for resumeUploads, and cancels one in memory, which nothing could resume.
+     */
+    async run(u, prog, signal) {
+        try {
+            for (;;) {
+                try {
+                    return await this.attempt(u, prog, signal);
+                }
+                catch (err) {
+                    if (!(err instanceof Restart) || signal?.aborted)
+                        throw err;
+                    u.restarts++;
+                    u.lastError = err.message;
+                    await this.abort(u);
+                    if (u.restarts > MAX_REBUILDS)
+                        throw new TeepinError(`${u.key}: the upload was started again ${u.restarts} times (${err.message})`);
+                    await u.reset();
+                    await u.save();
+                }
+            }
+        }
+        catch (err) {
+            if (signal?.aborted) {
+                if (!u.durable) {
+                    await this.abort(u, true);
+                    await u.forgetKey();
+                }
+                throw signal.reason;
+            }
+            if (keep(err)) {
+                if (!u.durable) {
+                    await this.abort(u); // nothing could resume it
+                    await u.forgetKey();
+                }
+                throw err;
+            }
+            // Final: cancelled, so its parts aren't kept (or billed) for nothing.
+            await this.abort(u);
+            await u.forgetKey();
+            u.state = 'failed';
+            u.lastError = message(err);
+            await u.save();
+            throw err;
+        }
+    }
+    /** Cancels the upload at the storage network: one call, best effort, never the control plane's rounds of waiting. */
+    async abort(u, stopping = false) {
+        if (u.uploadId)
+            await this.up.abortOne(u.bucket, u.uploadId, stopping);
+    }
+    async attempt(u, prog, signal) {
+        if (u.state === 'new')
+            await this.create(u, signal);
+        if (u.state === 'sending') {
+            if (!u.stream) {
+                if (!u.dek || !u.header.length)
+                    throw new Restart('the data key is gone');
+                u.stream = await tws1.Stream.resume(u.dek, u.header, u.size, u.partSize);
+            }
+            await this.sendParts(u, prog, signal);
+            u.state = 'completing';
+            await u.save();
+        }
+        return this.complete(u, signal);
+    }
+    async create(u, signal) {
+        await u.save(); // the idempotency key, before the call
+        const spec = { direct: true, idempotency_key: u.idem, key: u.key, size: u.size, part_size: u.partSize, sha256: u.sha256 };
+        if (u.contentType)
+            spec.content_type = u.contentType;
+        if (Object.keys(u.metadata).length)
+            spec.metadata = u.metadata;
+        if (u.ifNoneMatch)
+            spec.if_none_match = true;
+        if (u.ifMatch)
+            spec.if_match = u.ifMatch;
+        let res;
+        try {
+            res = (await this.up.control('POST', uploadsPath(u.bucket), spec, u, signal)).data;
+        }
+        catch (err) {
+            if (err instanceof APIError && err.code === 'upload_completed') {
+                u.uploadId = str(err.details.upload_id);
+                u.state = 'completing';
+                await u.save();
+                return;
+            }
+            if (err instanceof APIError && err.code === 'reservation_abandoned')
+                throw new Restart(err.code);
+            throw err;
+        }
+        const key = await this.up.checkKey(res.account_key);
+        if (int(res.part_size) !== u.partSize || int(res.size) !== u.size)
+            throw new DataIntegrityError(`${u.key}: the upload was created with another layout`, 'layout');
+        u.uploadId = str(res.upload_id);
+        const dek = this.up.newDataKey();
+        u.dek = dek;
+        u.stream = await tws1.Stream.create(dek, u.size, u.partSize);
+        u.header = u.stream.header;
+        u.wrapped = toBase64(await this.up.wrapKey(key.publicKey, key.account, tws1.objectIdBytes(u.uploadId), dek));
+        u.keyVersion = key.version;
+        u.state = 'sending';
+        await u.saveCreated();
+    }
+    async sendParts(u, prog, signal) {
+        const landed = new Set();
+        if (u.resumed) {
+            // After a crash: what storage holds, exactly as signed. Every part's source is still checked.
+            const { data } = await this.up.control('GET', `${uploadsPath(u.bucket)}/${u.uploadId}/parts`, undefined, u, signal);
+            for (const p of data.parts ?? [])
+                if (p.landed)
+                    landed.add(int(p.part_number));
+        }
+        for (const n of landed) {
+            await this.checkSource(u, n);
+            prog?.add(tws1.partOf(u.size, u.partSize, n).plainSize);
+        }
+        const todo = [];
+        for (let n = 1; n <= u.partCount; n++)
+            if (!landed.has(n))
+                todo.push(n);
+        const errors = [];
+        let stop = false;
+        const { ctl, unlink } = linked(signal);
+        const task = async (n) => {
+            let outcome = 'failed';
+            try {
+                if (stop)
+                    return;
+                await this.sendPart(u, n, ctl.signal);
+                outcome = u.throttled ? 'throttled' : 'ok';
+                prog?.add(tws1.partOf(u.size, u.partSize, n).plainSize);
+            }
+            catch (err) {
+                errors.push(err); // the coordinator decides
+                stop = true;
+            }
+            finally {
+                this.up.release(outcome);
+            }
+        };
+        const tasks = [];
+        try {
+            for (const n of todo) {
+                if (stop)
+                    break;
+                await this.up.limit.acquire(ctl.signal);
+                tasks.push(task(n));
+            }
+            await Promise.all(tasks);
+        }
+        catch (err) {
+            // Interrupted: each part task is stopped and waited for (section 22.13).
+            stop = true;
+            ctl.abort(err);
+            await joinCapped(tasks, this.up.cleanupMs);
+            unlink();
+            throw signal?.aborted ? signal.reason : err;
+        }
+        unlink();
+        // The most telling error: the abort, a changed file or a restart, before a passing failure.
+        if (errors.length)
+            throw telling(errors, [FileChangedError, Restart, DataIntegrityError], signal);
+    }
+    /**
+     * Part n's plaintext, read and hashed: journaled before its first byte leaves (D1 a), and the same as journaled on
+     * every later read (D1 b).
+     */
+    async checkSource(u, n) {
+        const p = tws1.partOf(u.size, u.partSize, n);
+        let data;
+        try {
+            data = await u.readAt(p.plainFirst, p.plainSize);
+        }
+        catch (err) {
+            throw new FileChangedError(u.path ?? u.key, message(err));
+        }
+        if (data.length !== p.plainSize)
+            throw new FileChangedError(u.path ?? u.key, `part ${n} is ${data.length} bytes, not ${p.plainSize}`);
+        const h = await this.up.digests.sha256(data);
+        const known = u.plain.get(n);
+        if (known === undefined) {
+            u.plain.set(n, h);
+            await u.savePart(n, h);
+        }
+        else if (known !== h) {
+            throw new FileChangedError(u.path ?? u.key, `part ${n} changed`);
+        }
+        return data;
+    }
+    async sign(u, n, md5, sha, extra, signal) {
+        try {
+            return (await this.up.control('POST', `${uploadsPath(u.bucket)}/${u.uploadId}/parts/${n}/sign`, { md5, sha256: sha, ...(extra ?? {}) }, u, signal)).data;
+        }
+        catch (err) {
+            if (err instanceof APIError && (err.code === 'upload_not_found' || err.code === 'reservation_abandoned'))
+                throw new Restart(err.code);
+            // The source hashes the same, so the bytes can only differ by key: never sent under another.
+            if (err instanceof APIError && err.code === 'part_mismatch')
+                throw new DataIntegrityError(`${u.key}: part ${n} was signed with other digests`, 'part');
+            throw err;
+        }
+    }
+    async sendPart(u, n, signal) {
+        if (!u.stream)
+            throw new Restart('the stream is gone');
+        let plain = await this.checkSource(u, n);
+        const sealed = await u.stream.sealPart(n, plain);
+        plain = undefined;
+        const md5 = this.up.digests.md5(sealed);
+        const sha = await this.up.digests.sha256(sealed);
+        await this.sendSealed(u, n, sealed, md5, sha, undefined, () => this.checkSource(u, n), signal);
+        await u.savePart(n, u.plain.get(n) ?? '', md5, sha, 'sent');
+    }
+    /** Signs part n and sends it until storage holds it as signed; recheck reads the source again when storage holds other bytes. Replaced in tests. */
+    async sendSealed(u, n, sealed, md5, sha, extra, recheck, signal) {
+        let signed = await this.sign(u, n, md5, sha, extra, signal);
+        let attempts = 0;
+        let resigns = 0;
+        for (;;) {
+            if (this.up.expiresSoon(signed))
+                signed = await this.sign(u, n, md5, sha, extra, signal);
+            let err;
+            let etag = '';
+            this.up.budget.onRequest();
+            try {
+                etag = await this.up.putMeasured(signed, sealed, signal);
+            }
+            catch (e) {
+                if (signal?.aborted)
+                    throw signal.reason;
+                if (!(e instanceof TeepinError))
+                    throw e;
+                err = e;
+            }
+            let outcome = storageOutcome(err);
+            // A browser can't read the ETag (the storage network doesn't expose it): an empty one is accepted.
+            if (outcome === 'sent' && err === undefined && etag !== '' && etag !== md5)
+                outcome = 'bad';
+            switch (outcome) {
+                case 'sent':
+                    return;
+                case 'resign':
+                    if (++resigns > 3)
+                        throw err;
+                    signed = await this.sign(u, n, md5, sha, extra, signal);
+                    break;
+                case 'bad':
+                    // Not the bytes signed: read and hash the source again (D1 b); the same source means a bug.
+                    if (recheck)
+                        await recheck();
+                    throw new DataIntegrityError(`${u.key}: part ${n} wasn't stored as signed`, 'part');
+                case 'unknown':
+                case 'unsent':
+                    // A part may simply be sent again: the same number, the same bytes.
+                    if (!this.up.budget.tryRetry())
+                        await this.up.wait(u, attempts, err, signal);
+                    attempts++;
+                    break;
+                case 'busy':
+                    await this.up.wait(u, attempts, err, signal);
+                    attempts++;
+                    break;
+                default:
+                    if (err instanceof APIError && err.statusCode === 404)
+                        throw new Restart('the storage network no longer has the upload');
+                    throw err;
+            }
+        }
+    }
+    async complete(u, signal) {
+        let raw;
+        try {
+            raw = (await this.up.control('POST', `${uploadsPath(u.bucket)}/${u.uploadId}/complete`, { wrapped_key: u.wrapped, key_version: u.keyVersion }, u, signal, 70000)).data;
+        }
+        catch (err) {
+            if (err instanceof APIError && (err.code === 'upload_mismatch' || err.code === 'reservation_abandoned'))
+                throw new Restart(err.code);
+            throw err;
+        }
+        const out = objectFrom(raw);
+        if (out.checksumSha256 && out.checksumSha256 !== u.sha256)
+            throw new DataIntegrityError(`${u.key}: the object's checksum isn't the file's`, 'checksum');
+        u.state = 'completed';
+        await u.forgetKey();
+        await u.save();
+        return out;
+    }
+    // --- streams of unknown size (section 22.1, E2 b) ----------------------------------------------------------------
+    /**
+     * Uploads everything source yields, sealing and sending up to concurrency parts at once. Any failure, or an abort,
+     * cancels the upload (one call): a stream can't be read again.
+     */
+    async runStream(s, source, concurrency, prog, signal) {
+        try {
+            try {
+                return await this.streamAttempt(s, source, Math.max(1, concurrency), prog, signal);
+            }
+            catch (err) {
+                if (err instanceof Restart && !signal?.aborted) {
+                    throw new TeepinError(`${s.key}: the upload was ended (${err.message}); a stream can't be read again, so upload it again`, { cause: err });
+                }
+                throw err;
+            }
+        }
+        catch (err) {
+            s.lastError = message(err);
+            await this.abort(s, Boolean(signal?.aborted));
+            throw signal?.aborted ? signal.reason : err;
+        }
+        finally {
+            s.stream = undefined;
+        }
+    }
+    async streamAttempt(s, source, concurrency, prog, signal) {
+        await this.createStream(s, signal);
+        const stream = s.stream;
+        if (!stream)
+            throw new Restart('the stream is gone');
+        const psize = s.partSize;
+        /** The next part's plaintext, read straight into one buffer (a part never exists twice while it is read): psize bytes, fewer only at the end. */
+        const take = async () => {
+            const buf = new Uint8Array(psize);
+            let got = 0;
+            while (got < psize) {
+                const b = await source.pull(psize - got, signal);
+                if (!b.length)
+                    break;
+                buf.set(b, got);
+                got += b.length;
+            }
+            if (got === 0)
+                return EMPTY;
+            return got < psize ? buf.subarray(0, got) : buf;
+        };
+        const errors = [];
+        let stop = false;
+        const slots = new Slots(concurrency);
+        const { ctl, unlink } = linked(signal);
+        /** Signs and sends part n, sealed from size plaintext bytes; its sealed bytes come in a box it empties when it ends. */
+        const task = async (n, box, size, last) => {
+            let outcome = 'failed';
+            try {
+                if (stop || !box.sealed)
+                    return;
+                const extra = last ? { last: true, plain_size: size } : undefined;
+                const md5 = this.up.digests.md5(box.sealed);
+                const sha = await this.up.digests.sha256(box.sealed);
+                await this.sendSealed(s, n, box.sealed, md5, sha, extra, undefined, ctl.signal);
+                outcome = s.throttled ? 'throttled' : 'ok';
+                prog?.add(size);
+            }
+            catch (err) {
+                errors.push(err); // the reader decides
+                stop = true;
+            }
+            finally {
+                box.sealed = undefined; // its part is let go before its slot is given back
+                this.up.release(outcome);
+                slots.release();
+            }
+        };
+        const whole = this.up.digests.incremental();
+        let total = 0;
+        const tasks = [];
+        try {
+            let cur = await take();
+            if (!cur.length)
+                throw new TeepinError(`${s.key}: the stream is empty`);
+            for (let n = 1; !stop; n++) {
+                // One part ahead: a part is the last only when nothing follows it.
+                const nxt = await take();
+                const last = nxt.length === 0;
+                if (!last && n >= this.up.sizes.maxParts) {
+                    if (s.slow)
+                        throw tooSlow(s.key, 0, s.slow, psize, this.up.sizes);
+                    throw new TooLargeError({
+                        statusCode: 413,
+                        message: `${s.key}: the stream is over ${this.up.sizes.maxParts} parts of ${psize} bytes; pass expectedSize (or a larger partSize) so its parts are large enough`,
+                        code: 'too_many_parts',
+                    });
+                }
+                const size = cur.length;
+                total += size;
+                whole.update(cur);
+                let pieces = await stream.sealSegments(n, cur, last);
+                cur = nxt; // the plaintext sealed is dropped before its pieces are joined
+                let sealed = concat(pieces);
+                pieces = undefined;
+                await slots.acquire(ctl.signal);
+                try {
+                    await this.up.limit.acquire(ctl.signal);
+                }
+                catch (err) {
+                    slots.release();
+                    throw err;
+                }
+                tasks.push(task(n, { sealed }, size, last));
+                sealed = undefined;
+                if (last)
+                    break;
+            }
+            await Promise.all(tasks);
+        }
+        catch (err) {
+            // Interrupted, or the read failed: each part task is stopped and waited for (section 22.13).
+            stop = true;
+            ctl.abort(err);
+            await joinCapped(tasks, this.up.cleanupMs);
+            unlink();
+            throw signal?.aborted ? signal.reason : err;
+        }
+        unlink();
+        if (errors.length)
+            throw telling(errors, [Restart, DataIntegrityError], signal);
+        return this.completeStream(s, total, whole.hex(), signal);
+    }
+    async createStream(s, signal) {
+        const spec = { direct: true, idempotency_key: s.idem, key: s.key, part_size: s.partSize };
+        if (s.contentType)
+            spec.content_type = s.contentType;
+        if (Object.keys(s.metadata).length)
+            spec.metadata = s.metadata;
+        if (s.ifNoneMatch)
+            spec.if_none_match = true;
+        if (s.ifMatch)
+            spec.if_match = s.ifMatch;
+        const { data: res } = await this.up.control('POST', uploadsPath(s.bucket), spec, s, signal);
+        const key = await this.up.checkKey(res.account_key);
+        if (int(res.part_size) !== s.partSize || (res.size !== undefined && res.size !== null)) {
+            throw new DataIntegrityError(`${s.key}: the upload was created with another layout`, 'layout');
+        }
+        s.uploadId = str(res.upload_id);
+        const dek = this.up.newDataKey();
+        let wrapped;
+        try {
+            s.stream = await tws1.OpenStream.create(dek, s.partSize);
+            wrapped = await this.up.wrapKey(key.publicKey, key.account, tws1.objectIdBytes(s.uploadId), dek);
+        }
+        finally {
+            dek.fill(0); // the stream holds its derived keys; nothing journals this one
+        }
+        s.wrapped = toBase64(wrapped);
+        s.keyVersion = key.version;
+    }
+    /** Completes a stream's upload with the size and SHA-256 read. Replaced in tests. */
+    async completeStream(s, size, sha256, signal) {
+        let raw;
+        try {
+            raw = (await this.up.control('POST', `${uploadsPath(s.bucket)}/${s.uploadId}/complete`, { wrapped_key: s.wrapped, key_version: s.keyVersion, size, sha256 }, s, signal, 70000)).data;
+        }
+        catch (err) {
+            if (err instanceof APIError && (err.code === 'upload_mismatch' || err.code === 'reservation_abandoned'))
+                throw new Restart(err.code);
+            throw err;
+        }
+        const out = objectFrom(raw);
+        if ((out.checksumSha256 && out.checksumSha256 !== sha256) || out.size !== size) {
+            throw new DataIntegrityError(`${s.key}: the object isn't the stream that was read`, 'checksum');
+        }
+        return out;
+    }
+}
+// --- reading what a caller hands over ----------------------------------------------------------------------------
+/** Whether body is a stream (a ReadableStream or an async iterable) rather than data that can be read at any offset. */
+export function isStreamBody(body) {
+    if (typeof ReadableStream !== 'undefined' && body instanceof ReadableStream)
+        return true;
+    return typeof body === 'object' && body !== null && Symbol.asyncIterator in body && !('read' in body && 'size' in body);
+}
+/** A ReadableStream or an async iterable, read a piece at a time: no piece is copied before it is taken. */
+export function streamSource(body) {
+    let rest = EMPTY;
+    let ended = false;
+    let next;
+    let release;
+    if (typeof ReadableStream !== 'undefined' && body instanceof ReadableStream) {
+        const reader = body.getReader();
+        next = async (signal) => {
+            const r = await abortable(reader.read(), signal);
+            return r.done ? null : (r.value ?? EMPTY);
+        };
+        release = async (reason) => {
+            // Never waits: a read still pending (a source that stalled) would hold it up.
+            if (!ended)
+                void reader.cancel(reason).catch(() => undefined);
+        };
+    }
+    else {
+        const it = body[Symbol.asyncIterator]();
+        next = async (signal) => {
+            const r = await abortable(it.next(), signal);
+            return r.done ? null : (r.value ?? EMPTY);
+        };
+        release = async () => {
+            // Never waits: a generator's return waits for the next() it is in, which a stalled source never ends.
+            if (!ended)
+                void Promise.resolve(it.return?.(undefined)).catch(() => undefined);
+        };
+    }
+    return {
+        async pull(max, signal) {
+            while (!rest.length) {
+                if (ended)
+                    return EMPTY;
+                const c = await next(signal);
+                if (c === null) {
+                    ended = true;
+                    return EMPTY;
+                }
+                rest = c;
+            }
+            const out = rest.length > max ? rest.subarray(0, max) : rest;
+            rest = rest.subarray(out.length);
+            return out;
+        },
+        async release(reason) {
+            rest = EMPTY;
+            await release(reason);
+            ended = true;
+        },
+    };
+}
+/**
+ * head (what was read first, to choose the way), then the rest of inner. head is handed on and dropped as soon as its
+ * bytes are taken, not held for the upload.
+ */
+export function prefixed(head, inner) {
+    let h = head.length ? head : undefined;
+    return {
+        get holding() {
+            return h !== undefined;
+        },
+        async pull(max, signal) {
+            if (h) {
+                const out = h.length > max ? h.subarray(0, max) : h;
+                h = h.length > max ? h.subarray(max) : undefined;
+                return out;
+            }
+            return inner.pull(max, signal);
+        },
+        release: (reason) => {
+            h = undefined;
+            return inner.release(reason);
+        },
+    };
+}
+/** Up to n bytes from source, into one buffer (shorter only at the source's end). */
+export async function readUpTo(source, n, signal) {
+    const parts = [];
+    let got = 0;
+    while (got < n) {
+        const b = await source.pull(n - got, signal);
+        if (!b.length)
+            break;
+        parts.push(b);
+        got += b.length;
+    }
+    return parts.length === 1 ? parts[0] : concat(parts);
+}
+//# sourceMappingURL=large.js.map