@teepin/sdk 0.2.1 → 0.3.0-rc.1

package/dist/esm/direct/uploads.js

@@ -0,0 +1,1660 @@
+// Copyright 2026 TEEPIN Project
+// Licensed under the Apache License, Version 2.0
+import { APIError, ConnectionError, DataIntegrityError, FileChangedError, ForbiddenError, PaymentRequiredError, PreconditionFailedError, StorageUnavailableError, TeepinError, UnauthorizedError, apiError, } from '../errors.js';
+import { md5Hex } from '../md5.js';
+import { fromBase64 } from './bytes.js';
+import { AdaptiveLimit, COMMIT_VERIFY_TRIES, MAX_REBUILDS, PACK_MAX_OBJECTS, PACK_MIN_TARGET, PACK_OBJECT_LIMIT, PACK_TARGET_BYTES, PART_RULES, RetryBudget, SIGN_MARGIN_MS, START_CONCURRENCY, STREAM_CONCURRENCY, SpeedMeter, directPartSize, envNumber, isPassing, isThrottle, nextPack, packObjectLimit, packTarget, storageOutcome, streamPartSize, waitDelayMs, } from './engine.js';
+import { abortable, Deferred, joinCapped, linked, objectFrom, Progress, toBase64, uuid7 } from './common.js';
+import * as hpke from './hpke.js';
+import { MemoryJournal } from './journal.js';
+import { Large, Parts, StreamUpload } from './large.js';
+import { Sha256 } from './sha256.js';
+import * as tws1 from './tws1.js';
+export { abortable, Deferred, joinCapped, linked, objectFrom, Progress, Slots, toBase64, uuid7 } from './common.js';
+/** An unfinished run is shown as expired after this long untouched (7 days). */
+export const RUN_EXPIRY_MS = 7 * 86400000;
+/** The state directory's size that earns a warning (section 17.12), unless TEEPIN_STATE_WARN_BYTES says. */
+export const STATE_WARN_ENV = 'TEEPIN_STATE_WARN_BYTES';
+export const STATE_WARN_BYTES = 2 ** 30;
+/** How long a stopping step waits for its tasks, and a cleanup call may take, in ms (section 22.13's cap). */
+export const CLEANUP_MS = 5000;
+/** The longest a timer can be set for (setTimeout's limit); a longer one would fire at once. */
+const MAX_TIMER_MS = 2 ** 31 - 1;
+const str = (v) => (v === undefined || v === null ? '' : String(v));
+const int = (v) => Math.trunc(Number(v || 0)) || 0;
+const bucketPath = (bucket) => `/v1/storage/buckets/${encodeURIComponent(bucket)}`;
+const unquote = (etag) => etag.trim().replace(/^W\//, '').replace(/^"|"$/g, '');
+const hex = (b) => Array.from(b, (x) => x.toString(16).padStart(2, '0')).join('');
+/** What an error says, for a journal: its code (or name) and message. */
+export function describe(err) {
+    if (err === undefined || err === null)
+        return '';
+    const code = (err instanceof APIError && err.code) || (err instanceof Error ? err.name : 'Error');
+    return `${code}: ${err instanceof Error ? err.message : String(err)}`;
+}
+/** Errors that stop a whole run, with its files kept for resumeUploads. */
+export function stopsRun(err) {
+    return err instanceof UnauthorizedError || err instanceof ForbiddenError || err instanceof PaymentRequiredError;
+}
+/**
+ * Whether an empty file's failed put is final. A passing failure (the network, a busy server) or one that stops the run
+ * (a revoked key, no credit) leaves it queued in the journal for resumeUploads, as a pack's files are left.
+ */
+export function emptyPutFinal(err) {
+    return !(isPassing(err) || stopsRun(err));
+}
+/** An object as a journal keeps it (JSON), and back. */
+function objectJSON(o) {
+    return { ...o, createdAt: o.createdAt.toISOString(), updatedAt: o.updatedAt.toISOString(), uploadedAt: o.uploadedAt?.toISOString() };
+}
+function reviveObject(v) {
+    if (!v || typeof v !== 'object')
+        return undefined;
+    const d = v;
+    const date = (x) => new Date(str(x) || NaN);
+    return {
+        id: str(d.id),
+        key: str(d.key),
+        size: Number(d.size ?? 0),
+        contentType: d.contentType || undefined,
+        metadata: d.metadata,
+        checksumSha256: d.checksumSha256 || undefined,
+        etag: str(d.etag),
+        partCount: Number(d.partCount ?? 0),
+        status: str(d.status),
+        backend: str(d.backend),
+        createdAt: date(d.createdAt),
+        updatedAt: date(d.updatedAt),
+        uploadedAt: d.uploadedAt ? date(d.uploadedAt) : undefined,
+    };
+}
+/** Runs fn for every item, at most n at once; the first failure stops the rest. An abort throws its reason. */
+async function pool(n, items, signal, fn) {
+    let next = 0;
+    let failure;
+    const worker = async () => {
+        while (!failure && next < items.length && !signal?.aborted) {
+            const item = items[next++];
+            try {
+                await fn(item);
+            }
+            catch (err) {
+                failure ??= { err };
+            }
+        }
+    };
+    await Promise.all(Array.from({ length: Math.max(1, Math.min(n, items.length)) }, worker));
+    if (signal?.aborted)
+        throw signal.reason;
+    if (failure)
+        throw failure.err;
+}
+export const webDigests = {
+    md5: md5Hex,
+    sha256: async (data) => hex(new Uint8Array(await crypto.subtle.digest('SHA-256', data))),
+    incremental: () => {
+        const h = new Sha256();
+        return { update: (d) => void h.update(d), hex: () => h.hexDigest() };
+    },
+};
+/** Pins kept for the life of this client (browsers; the node entry keeps them in the state directory). */
+export class MemoryPins {
+    pins = new Map();
+    async check(accountId, version, publicKey) {
+        const id = JSON.stringify([accountId, version]);
+        const encoded = toBase64(publicKey);
+        const have = this.pins.get(id);
+        if (have !== undefined)
+            return have === encoded;
+        this.pins.set(id, encoded);
+        return true;
+    }
+}
+// --- items and packs ----------------------------------------------------------------------------------------------
+/** One object on its way into a pack. */
+export class Item {
+    key;
+    size;
+    sha256;
+    read;
+    ifNoneMatch;
+    path;
+    fileId;
+    objectId = '';
+    result;
+    error;
+    /** false when the error leaves the item journaled for resumeUploads. */
+    final = true;
+    /** putObject's: set when a pack takes the item, resolved when its result is in, and to wake its waiting caller. */
+    picked = false;
+    done;
+    wake;
+    /** The pack and object id its file row last journaled. */
+    journaled = '';
+    contentType;
+    metadata;
+    ifMatch;
+    constructor(key, size, sha256, read, contentType = '', metadata, ifNoneMatch = false, ifMatch = '', path, fileId) {
+        this.key = key;
+        this.size = size;
+        this.sha256 = sha256;
+        this.read = read;
+        this.ifNoneMatch = ifNoneMatch;
+        this.path = path;
+        this.fileId = fileId;
+        this.contentType = contentType || '';
+        this.metadata = { ...(metadata ?? {}) };
+        this.ifMatch = ifMatch || '';
+    }
+    reserveJSON() {
+        const o = { key: this.key, size: this.size, sha256: this.sha256 };
+        if (this.contentType)
+            o.content_type = this.contentType;
+        if (Object.keys(this.metadata).length)
+            o.metadata = this.metadata;
+        if (this.ifNoneMatch)
+            o.if_none_match = true;
+        if (this.ifMatch)
+            o.if_match = this.ifMatch;
+        return o;
+    }
+}
+/** One pack's state, kept in its store (a run's journal, or memory). */
+export class Pack {
+    bucket;
+    items;
+    store;
+    id;
+    state = 'new';
+    idem = uuid7();
+    reservation = {};
+    signBody = {};
+    signed = {};
+    size = 0;
+    md5 = '';
+    sha256 = '';
+    fileName = '';
+    data;
+    attempts = 0;
+    rebuilds = 0;
+    verifies = 0;
+    resigns = 0;
+    waited = 0;
+    throttled = false;
+    lastError = '';
+    constructor(bucket, items, store, id) {
+        this.bucket = bucket;
+        this.items = items;
+        this.store = store;
+        this.id = id ?? uuid7();
+    }
+    get serverId() {
+        return str(this.reservation.pack);
+    }
+}
+/** The pack can't go on: its items fail with err (final: false keeps them journaled for resumeUploads). */
+class Stop extends Error {
+    err;
+    final;
+    constructor(err, final = true) {
+        super(err instanceof Error ? err.message : String(err));
+        this.err = err;
+        this.final = final;
+    }
+}
+/** A pack's state and bytes in memory: putObject's packs, and the packs of a run journaled in memory. */
+export class PackStore {
+    async savePack(p) {
+        void p;
+    }
+    async putBytes(p, data) {
+        p.data = data;
+    }
+    async getBytes(p) {
+        return p.data;
+    }
+    async dropBytes(p) {
+        p.data = undefined;
+    }
+    async itemsDone(done) {
+        for (const [it, obj, err, final] of done) {
+            it.result = obj;
+            it.error = err;
+            it.final = final;
+        }
+    }
+}
+/** A run's packs in its journal, and their bytes in its directory (or in memory, for a run journaled in memory). */
+export class RunStore extends PackStore {
+    journal;
+    place;
+    constructor(journal, place) {
+        super();
+        this.journal = journal;
+        this.place = place;
+    }
+    async savePack(p) {
+        const entries = [
+            {
+                table: 'packs',
+                id: p.id,
+                row: {
+                    _id: p.id,
+                    idempotency_key: p.idem,
+                    state: p.state,
+                    reservation: p.reservation,
+                    file_name: p.fileName,
+                    size: p.size,
+                    md5: p.md5,
+                    sha256: p.sha256,
+                    sign_body: p.signBody,
+                    signed: p.signed,
+                    attempts: p.attempts,
+                    last_error: p.lastError,
+                    updated: Date.now(),
+                },
+            },
+        ];
+        for (const it of p.items) {
+            const mark = `${p.id}|${it.objectId}`;
+            if (it.fileId === undefined || it.result || it.error !== undefined || it.journaled === mark)
+                continue;
+            const row = this.journal.get('files', it.fileId);
+            if (!row)
+                continue;
+            entries.push({ table: 'files', id: it.fileId, row: { ...row, pack: p.id, object_id: it.objectId || null, state: 'packed' } });
+        }
+        entries.push(...this.touch());
+        await this.journal.write(entries);
+        for (const it of p.items)
+            if (it.fileId !== undefined && !it.result && it.error === undefined)
+                it.journaled = `${p.id}|${it.objectId}`;
+    }
+    /** The run row with its updated time now. */
+    touch() {
+        const run = this.journal.get('run', 'run');
+        return run ? [{ table: 'run', id: 'run', row: { ...run, updated: Date.now() } }] : [];
+    }
+    async putBytes(p, data) {
+        if (!this.place) {
+            p.data = data;
+            return;
+        }
+        p.fileName = `${p.id}.pack`;
+        await this.place.writePack(p.fileName, data);
+    }
+    async getBytes(p) {
+        if (!this.place)
+            return p.data;
+        if (!p.fileName)
+            return undefined;
+        return this.place.readPack(p.fileName);
+    }
+    async dropBytes(p) {
+        p.data = undefined;
+        if (this.place && p.fileName) {
+            await this.place.removePack(p.fileName).catch(() => undefined);
+            p.fileName = '';
+        }
+    }
+    async itemsDone(done) {
+        await super.itemsDone(done);
+        const entries = [];
+        for (const [it, obj, err, final] of done) {
+            if (it.fileId === undefined)
+                continue;
+            const row = this.journal.get('files', it.fileId);
+            if (!row)
+                continue;
+            if (obj)
+                entries.push({ table: 'files', id: it.fileId, row: { ...row, state: 'saved', object_id: obj.id, result: objectJSON(obj), error: '' } });
+            else if (final)
+                entries.push({ table: 'files', id: it.fileId, row: { ...row, state: 'failed', error: describe(err) } });
+            else
+                entries.push({ table: 'files', id: it.fileId, row: { ...row, error: describe(err) } });
+        }
+        if (entries.length)
+            await this.journal.write(entries);
+    }
+}
+/**
+ * Who releases an interrupted run: whichever ends last, the run's own step (once it has stopped) or its last pack task.
+ * A run that isn't interrupted is finished by its own step as usual, and this never fires.
+ */
+export class RunCloser {
+    live = 0;
+    stopped = false;
+    fired = false;
+    started() {
+        this.live++;
+    }
+    /** A task ended (taskDone) or the run's step stopped: true for the one call that should release the run. */
+    ended(taskDone) {
+        if (taskDone)
+            this.live--;
+        else
+            this.stopped = true;
+        if (this.stopped && this.live === 0 && !this.fired) {
+            this.fired = true;
+            return true;
+        }
+        return false;
+    }
+}
+/**
+ * Direct uploads for one storage service: the account key, putObject's shared packs, upload runs, resume and cleanup.
+ * The methods tests replace (as the Python tests patch _direct.py) are newDataKey, encryptObject, wrapKey, putSigned,
+ * expiresSoon, dispatch, send and hashParts.
+ */
+export class DirectUploads {
+    client;
+    limit;
+    budget = new RetryBudget();
+    parts;
+    /** The sizes it works with (tests shrink them). */
+    sizes = {
+        ...PART_RULES,
+        packObjectLimit: PACK_OBJECT_LIMIT,
+        packTarget: PACK_TARGET_BYTES,
+        packMinTarget: PACK_MIN_TARGET,
+        packMaxObjects: PACK_MAX_OBJECTS,
+        streamConcurrency: STREAM_CONCURRENCY,
+    };
+    /**
+     * The measured upload speed to the storage network: shrinks packs and new uploads' parts on a slow link (section
+     * 22.7). Tests set it with speed.set.
+     */
+    speed = new SpeedMeter();
+    /**
+     * A storage PUT's own timer: at least minMs, and its bytes at bytesPerSecond (30 s and 64 KiB/s); on a link measured
+     * slower, twice its time at that speed (section 22.7). Tests shorten it.
+     */
+    putTimeout = { minMs: 30000, bytesPerSecond: 65536 };
+    /** How long a stopping step waits for its tasks, and a cleanup call may take (ms). */
+    cleanupMs = CLEANUP_MS;
+    digests = webDigests;
+    pins = new MemoryPins();
+    /** Runs on disk: the node entry's (undefined in browsers). */
+    host;
+    /** Where warnings go: a run removed by cleanUploads, a large state directory. */
+    warn = (m) => console.warn(m);
+    accountId;
+    queue = [];
+    /** Wake-ups of putObject calls waiting for a slot: resolved when one comes free. */
+    slotWaiters = [];
+    memory = new PackStore();
+    constructor(client) {
+        this.client = client;
+        this.limit = new AdaptiveLimit(START_CONCURRENCY, client.uploadConcurrency);
+        this.parts = new Parts(this);
+    }
+    // --- what tests replace -----------------------------------------------------
+    newDataKey() {
+        return tws1.newDataKey();
+    }
+    encryptObject(dek, plain) {
+        return tws1.encrypt(dek, plain);
+    }
+    wrapKey(publicKey, account, objectId, dek) {
+        return hpke.wrapKey(publicKey, account, objectId, dek);
+    }
+    /** Whether a signature is too close to its expiry to use. */
+    expiresSoon(signed) {
+        const exp = Date.parse(str(signed.expires_at));
+        return Number.isNaN(exp) || exp - Date.now() < SIGN_MARGIN_MS;
+    }
+    /**
+     * Sends one signed PUT to the storage network, with exactly the signed headers and never the API key; returns its
+     * ETag, unquoted ("" when the answer has none, as a browser sees it: the storage network doesn't expose it).
+     */
+    async putSigned(signed, data, signal) {
+        const bps = this.speed.bytesPerSecond;
+        const t = this.putTimeout;
+        const ms = Math.max(t.minMs, (data.length / t.bytesPerSecond) * 1000, bps ? ((2 * data.length) / bps) * 1000 : 0);
+        const { ctl, unlink } = linked(signal);
+        const timer = setTimeout(() => ctl.abort(new PutTimedOut(ms)), ms);
+        try {
+            const headers = {};
+            for (const [k, v] of Object.entries(signed.headers ?? {}))
+                headers[k] = str(v);
+            const res = await this.client.sendSigned({ method: str(signed.method) || 'PUT', url: str(signed.url), headers, body: data, signal: ctl.signal });
+            await res.arrayBuffer().catch(() => undefined);
+            return unquote(res.headers.get('etag') ?? '');
+        }
+        catch (err) {
+            if (signal?.aborted)
+                throw signal.reason;
+            throw err;
+        }
+        finally {
+            clearTimeout(timer);
+            unlink();
+        }
+    }
+    /**
+     * putSigned, measured (section 22.7): the PUT every pack and part goes through. One that succeeds is a sample; one its
+     * own timer ended with no answer is an upper bound (a slow link, measured from a cold start too). Any other failure (an
+     * error status, a refused connection, the caller's abort) is never measured.
+     */
+    async putMeasured(signed, data, signal) {
+        const start = performance.now();
+        let etag;
+        try {
+            etag = await this.putSigned(signed, data, signal);
+        }
+        catch (err) {
+            if (err instanceof PutTimedOut && !signal?.aborted)
+                this.speed.observeTimeout(data.length, performance.now() - start);
+            throw err;
+        }
+        this.speed.observe(data.length, performance.now() - start);
+        return etag;
+    }
+    /**
+     * The pack/parts choice for every way in (putObject, upload, uploadFiles, copyObject): an object over this goes in
+     * parts. At the speed measured so far (section 22.7).
+     */
+    packObjectLimit() {
+        return packObjectLimit(this.speed.requestBytes(), this.sizes.packObjectLimit, this.sizes.minBytes);
+    }
+    /** The next pack's target size, at the speed measured so far. */
+    packTarget() {
+        return packTarget(this.speed.requestBytes(), this.sizes.packTarget, this.sizes.packMinTarget);
+    }
+    // --- shared plumbing ----------------------------------------------------------
+    /** Where runs keep their state, when it's on disk. */
+    get runHost() {
+        if (!this.host)
+            throw new TeepinError('upload runs on disk need @teepin/sdk/node');
+        return this.host;
+    }
+    /**
+     * A control-plane call (each is idempotent, so retried by the client as safe), with rounds of waiting while the
+     * control plane is busy or failing, up to the upload's wait (p's; with no p, none). Returns the status and the answer.
+     */
+    async control(method, path, body, p, signal, timeout) {
+        for (let round = 0;; round++) {
+            try {
+                const { response } = await this.client.send({ method, path, json: body ?? undefined, mode: 'safe', signal, timeout });
+                const text = response.status === 204 ? '' : await response.text();
+                let data = {};
+                try {
+                    data = text ? JSON.parse(text) : {};
+                }
+                catch {
+                    throw new TeepinError(`${method} ${path}: the answer isn't JSON`);
+                }
+                return { status: response.status, data: data };
+            }
+            catch (err) {
+                if (signal?.aborted)
+                    throw signal.reason;
+                if (err instanceof APIError) {
+                    // 501: direct storage is off. A 404 with no code of ours: a deployment from before the routes existed (a missing
+                    // bucket or pack always names itself).
+                    if (err.code === 'direct_upload_unsupported' || err.statusCode === 501 || (err.statusCode === 404 && (err.code === '' || err.code === 'not_found'))) {
+                        throw unsupported(err);
+                    }
+                }
+                if (!isPassing(err) || !p)
+                    throw err;
+                await this.wait(p, round, err, signal);
+            }
+        }
+    }
+    /** One round of waiting for a service to come back; StorageUnavailableError once p has waited as long as it may. */
+    async wait(p, round, err, signal) {
+        const delay = waitDelayMs(round, err instanceof APIError ? err.retryAfterMs : undefined);
+        if (isThrottle(err))
+            p.throttled = true;
+        if (p.waited + delay > this.client.uploadWait) {
+            throw new StorageUnavailableError(`storage didn't come back within ${Math.round(this.client.uploadWait / 1000)} s: ${err instanceof Error ? err.message : String(err)}`, { cause: err });
+        }
+        p.waited += delay;
+        await this.client.sleep(delay, signal);
+    }
+    /** The account key from an answer, checked against the suite, this client's account and the pin. */
+    async checkKey(raw) {
+        const ak = (raw ?? {});
+        if (ak.suite !== hpke.SUITE)
+            throw new DataIntegrityError(`unsupported key suite ${JSON.stringify(ak.suite)}`, 'account_key');
+        const account = str(ak.account_id);
+        if (!account)
+            throw new DataIntegrityError("the API didn't name the account its key belongs to", 'account_key');
+        const publicKey = fromBase64(str(ak.public_key));
+        const version = int(ak.version);
+        if (this.accountId === undefined)
+            this.accountId = account;
+        else if (this.accountId !== account) {
+            throw new DataIntegrityError(`the API named account ${account}, not ${this.accountId}, in one client`, 'account_key');
+        }
+        if (!(await this.pins.check(account, version, publicKey))) {
+            throw new DataIntegrityError(`account ${account}'s key version ${version} changed; refusing to encrypt to it`, 'account_key');
+        }
+        return { account: tws1.objectIdBytes(account), publicKey, version };
+    }
+    /** Items' results: journaled together, then their callers woken. */
+    async done(store, done) {
+        if (!done.length)
+            return;
+        await store.itemsDone(done);
+        for (const [it] of done)
+            it.done?.resolve();
+    }
+    // --- a pack's life --------------------------------------------------------------
+    /**
+     * Takes a pack to committed, delivering every item's result. Throws only an error that stops a whole run (auth,
+     * permission, credit), after recording it on the pack's items, or the abort's reason, recording nothing.
+     */
+    async drive(p, signal) {
+        try {
+            while (p.state !== 'committed' && p.state !== 'failed') {
+                signal?.throwIfAborted();
+                switch (p.state) {
+                    case 'new':
+                        await this.reserve(p, signal);
+                        break;
+                    case 'reserved':
+                        await this.build(p);
+                        break;
+                    case 'built':
+                        await this.sign(p, signal);
+                        break;
+                    case 'signed':
+                        await this.send(p, signal);
+                        break;
+                    case 'conflict':
+                    case 'bad':
+                        await this.renew(p);
+                        break;
+                    default:
+                        await this.commit(p, signal);
+                }
+            }
+        }
+        catch (err) {
+            // Interrupted: the store holds the state for resume, and the abort's reason wins over whatever was met.
+            if (signal?.aborted)
+                throw signal.reason;
+            if (err instanceof Stop)
+                return this.fail(p, err.err, err.final);
+            if (stopsRun(err)) {
+                await this.fail(p, err, false);
+                throw err;
+            }
+            if (err instanceof StorageUnavailableError)
+                return this.fail(p, err, false);
+            if (err instanceof TeepinError)
+                return this.fail(p, err, true);
+            throw err;
+        }
+    }
+    async fail(p, err, final) {
+        p.lastError = describe(err);
+        if (final) {
+            p.state = 'failed';
+            await p.store.dropBytes(p);
+        }
+        await p.store.savePack(p);
+        await this.done(p.store, p.items.filter((it) => !it.result && it.error === undefined).map((it) => [it, undefined, err, final]));
+    }
+    async reserve(p, signal) {
+        await p.store.savePack(p); // the idempotency key, before the call
+        const body = { idempotency_key: p.idem, objects: p.items.map((it) => it.reserveJSON()) };
+        let res;
+        try {
+            res = (await this.control(`POST`, `${bucketPath(p.bucket)}/packs`, body, p, signal)).data;
+        }
+        catch (err) {
+            if (err instanceof APIError && err.code === 'reservation_abandoned') {
+                p.state = 'conflict';
+                await p.store.savePack(p);
+                return;
+            }
+            if (err instanceof APIError && err.code === 'pack_committed') {
+                // Committed earlier, its answer lost: commit again for the stored result.
+                p.reservation = { pack: str(err.details.pack) };
+                p.state = 'committing';
+                await p.store.savePack(p);
+                return;
+            }
+            throw err;
+        }
+        await this.checkKey(res.account_key);
+        const ids = new Map((res.objects ?? []).map((o) => [str(o.key), str(o.object_id)]));
+        for (const it of p.items)
+            it.objectId = ids.get(it.key) ?? '';
+        p.reservation = res;
+        p.state = 'reserved';
+        await p.store.savePack(p);
+    }
+    async build(p) {
+        const key = await this.checkKey(p.reservation.account_key);
+        const built = await this.buildPack(p, key);
+        if ('changed' in built) {
+            await this.done(p.store, built.changed.map(([it, err]) => [it, undefined, err, true]));
+            // The reservation names files that changed: the rest go under a new one.
+            const gone = new Set(built.changed.map(([it]) => it));
+            p.items = p.items.filter((it) => !gone.has(it));
+            p.state = p.items.length ? 'conflict' : 'failed';
+            p.rebuilds--; // not the pack's fault
+            await p.store.savePack(p);
+            return;
+        }
+        await p.store.putBytes(p, built.data);
+        p.size = built.data.length;
+        p.md5 = this.digests.md5(built.data);
+        p.sha256 = await this.digests.sha256(built.data);
+        p.signBody = { size: p.size, md5: p.md5, sha256: p.sha256, objects: built.objects };
+        p.state = 'built';
+        await p.store.savePack(p);
+    }
+    /**
+     * Every item read, checked against its queued hash, encrypted with a fresh key and appended to the pack, then
+     * decrypt-checked ("saved" means readable, section 19.3) and its key wrapped; or the items that changed since they
+     * were queued.
+     */
+    async buildPack(p, key) {
+        const pack = new tws1.Pack();
+        const built = [];
+        const changed = [];
+        try {
+            for (const it of p.items) {
+                let plain;
+                try {
+                    plain = await it.read();
+                }
+                catch (err) {
+                    changed.push([it, new FileChangedError(it.path ?? it.key, err instanceof Error ? err.message : String(err))]);
+                    continue;
+                }
+                if (plain.length !== it.size || (await this.digests.sha256(plain)) !== it.sha256) {
+                    changed.push([it, new FileChangedError(it.path ?? it.key)]);
+                    continue;
+                }
+                const dek = this.newDataKey();
+                const stored = await this.encryptObject(dek, plain);
+                const off = await pack.appendNeedle(tws1.objectIdBytes(it.objectId), stored);
+                built.push({ it, dek, off, n: stored.length });
+            }
+            if (changed.length)
+                return { changed };
+            const data = pack.bytes();
+            for (const { it, dek, off, n } of built) {
+                let ok;
+                try {
+                    const stored = await tws1.readNeedle(data, off, tws1.objectIdBytes(it.objectId), n);
+                    ok = (await this.digests.sha256(await tws1.decrypt(dek, stored))) === it.sha256;
+                }
+                catch (err) {
+                    if (!(err instanceof DataIntegrityError))
+                        throw err;
+                    ok = false;
+                }
+                if (!ok)
+                    throw new Stop(new DataIntegrityError(`${it.key} didn't decrypt back to its source`, 'build'));
+            }
+            const objects = [];
+            for (const { it, dek, off, n } of built) {
+                const wrapped = await this.wrapKey(key.publicKey, key.account, tws1.objectIdBytes(it.objectId), dek);
+                objects.push({ object_id: it.objectId, offset: off, stored_size: n, wrapped_key: toBase64(wrapped), key_version: key.version });
+            }
+            return { data, objects };
+        }
+        finally {
+            for (const { dek } of built)
+                dek.fill(0);
+        }
+    }
+    async sign(p, signal) {
+        let signed;
+        try {
+            signed = (await this.control(`POST`, `${bucketPath(p.bucket)}/packs/${p.serverId}/sign`, p.signBody, p, signal)).data;
+        }
+        catch (err) {
+            if (err instanceof APIError && err.code === 'reservation_abandoned') {
+                p.state = 'conflict';
+                await p.store.savePack(p);
+                return;
+            }
+            if (err instanceof APIError && ['manifest_mismatch', 'bad_wrapped_key', 'invalid_request', 'pack_not_found'].includes(err.code))
+                throw new Stop(err);
+            throw err;
+        }
+        p.signed = signed;
+        p.state = 'signed';
+        await p.store.savePack(p);
+    }
+    /** A pack's one PUT. Replaced in tests. */
+    async send(p, signal) {
+        if (this.expiresSoon(p.signed)) {
+            p.state = 'built'; // the same manifest signs again
+            await p.store.savePack(p);
+            return;
+        }
+        const data = await p.store.getBytes(p);
+        if (!data || (await this.digests.sha256(data)) !== p.sha256) {
+            p.state = 'bad'; // the pack file is lost or damaged: a new reservation, fresh keys
+            await p.store.savePack(p);
+            return;
+        }
+        p.state = 'uploading';
+        await p.store.savePack(p);
+        let err;
+        this.budget.onRequest();
+        try {
+            await this.putMeasured(p.signed, data, signal);
+        }
+        catch (e) {
+            if (signal?.aborted)
+                throw signal.reason;
+            if (!(e instanceof TeepinError))
+                throw e;
+            err = e;
+        }
+        switch (storageOutcome(err)) {
+            case 'sent':
+                p.state = 'sent';
+                break;
+            case 'unknown':
+                p.state = 'unknown';
+                break;
+            case 'resign':
+                if (++p.resigns > 3)
+                    throw new Stop(err);
+                p.state = 'built';
+                break;
+            case 'bad':
+                p.state = 'bad';
+                break;
+            case 'unsent':
+                p.state = 'signed';
+                if (!this.budget.tryRetry())
+                    await this.wait(p, p.attempts, err, signal);
+                p.attempts++;
+                break;
+            case 'busy':
+                p.state = 'signed';
+                await this.wait(p, p.attempts, err, signal);
+                p.attempts++;
+                break;
+            default:
+                throw new Stop(err);
+        }
+        await p.store.savePack(p);
+    }
+    async commit(p, signal) {
+        const unknown = p.state === 'unknown' || p.state === 'uploading';
+        if (p.state === 'sent') {
+            p.state = 'committing';
+            await p.store.savePack(p);
+        }
+        let status;
+        let res;
+        try {
+            ({ status, data: res } = await this.control(`POST`, `${bucketPath(p.bucket)}/packs/${p.serverId}/commit`, undefined, p, signal, 70000));
+        }
+        catch (err) {
+            if (!(err instanceof APIError))
+                throw err;
+            if (err.code === 'reservation_abandoned')
+                p.state = 'conflict';
+            else if (err.code === 'pack_mismatch')
+                p.state = 'bad';
+            else if (err.code === 'pack_not_signed')
+                p.state = 'built';
+            else if (err.code === 'bucket_not_found')
+                throw new Stop(err);
+            else
+                throw err;
+            await p.store.savePack(p);
+            return;
+        }
+        if (status === 202) {
+            p.verifies++;
+            if (unknown || p.verifies > COMMIT_VERIFY_TRIES) {
+                p.state = 'signed'; // not there: send the same bytes again
+                p.verifies = 0;
+            }
+            else {
+                await this.client.sleep(1000, signal);
+            }
+            await p.store.savePack(p);
+            return;
+        }
+        await this.deliver(p, res);
+        p.state = 'committed';
+        await p.store.dropBytes(p);
+        await p.store.savePack(p);
+    }
+    /** A new reservation and fresh keys for the pack's items (section 17.3). */
+    async renew(p) {
+        p.rebuilds++;
+        if (p.rebuilds > MAX_REBUILDS)
+            throw new Stop(new TeepinError(`the pack was rebuilt ${MAX_REBUILDS} times: ${p.lastError || p.state}`));
+        p.lastError = p.state;
+        await p.store.dropBytes(p);
+        p.idem = uuid7();
+        p.reservation = {};
+        p.signBody = {};
+        p.signed = {};
+        p.verifies = 0;
+        p.resigns = 0;
+        for (const it of p.items)
+            it.objectId = '';
+        p.state = 'new';
+        await p.store.savePack(p);
+    }
+    async deliver(p, res) {
+        const when = new Date(str(res.committed_at) || NaN);
+        const backend = str(res.backend);
+        const objects = res.objects ?? [];
+        const byId = new Map(objects.map((o) => [str(o.object_id), o]));
+        const byKey = new Map(objects.map((o) => [str(o.key), o]));
+        const done = [];
+        for (const it of p.items) {
+            if (it.result || it.error !== undefined)
+                continue;
+            const r = byId.get(it.objectId) ?? byKey.get(it.key);
+            if (!r)
+                done.push([it, undefined, new TeepinError(`the commit didn't report ${it.key}`), true]);
+            else if (r.result === 'saved') {
+                const obj = {
+                    id: str(r.object_id) || it.objectId,
+                    key: it.key,
+                    size: it.size,
+                    contentType: it.contentType || undefined,
+                    metadata: it.metadata,
+                    checksumSha256: it.sha256,
+                    etag: it.sha256,
+                    partCount: 0,
+                    status: 'available',
+                    backend,
+                    createdAt: when,
+                    updatedAt: when,
+                    uploadedAt: when,
+                };
+                done.push([it, obj, undefined, true]);
+            }
+            else {
+                const code = str(r.error) || 'upload_failed';
+                done.push([it, undefined, apiError({ statusCode: code === 'precondition_failed' ? 412 : 409, message: `${it.key}: ${code.replaceAll('_', ' ')}`, code }), true]);
+            }
+        }
+        await this.done(p.store, done);
+    }
+    // --- putObject: shared packs ----------------------------------------------------
+    /**
+     * Stores one object of up to 16 MiB in a pack shared with the other calls waiting now, and returns it once its pack
+     * commits. A waiting call dispatches the queue itself whenever a slot comes free (release wakes it), so a slot freed
+     * anywhere serves the queue. The wait for a slot is bounded by uploadWait: an item no pack took by then leaves the
+     * queue (so it certainly wasn't saved) with StorageUnavailableError; once a pack has it, the pack's own bounded waits
+     * decide (section 22.4). An abort while it waits takes it out of the queue; once a pack has it, the pack goes on (it
+     * is shared) and the call stops waiting for it.
+     */
+    async put(bucket, key, data, opts = {}, signal) {
+        signal?.throwIfAborted();
+        const sha = await this.digests.sha256(data);
+        const it = new Item(key, data.length, sha, async () => data, opts.contentType, opts.metadata, Boolean(opts.ifNoneMatch), normalizeIfMatch(opts.ifMatch));
+        it.done = new Deferred();
+        this.queue.push([bucket, it]);
+        this.limit.setPriority(true);
+        const wait = this.client.uploadWait;
+        const deadline = Date.now() + wait;
+        const leave = () => {
+            const queued = this.queue.some(([, i]) => i === it);
+            if (queued) {
+                this.queue = this.queue.filter(([, i]) => i !== it);
+                this.limit.setPriority(this.queue.length > 0);
+            }
+            return queued;
+        };
+        try {
+            while (!it.picked) {
+                // Registered before dispatching, so a slot freed meanwhile wakes this call.
+                const woken = new Deferred();
+                it.wake = woken;
+                this.slotWaiters.push(woken);
+                this.dispatch();
+                if (it.picked)
+                    break;
+                const left = deadline - Date.now();
+                if (left <= 0)
+                    break;
+                let timer;
+                try {
+                    // A timer past 2^31 - 1 ms fires at once in Node and browsers, so a very long uploadWait waits in slices.
+                    const slice = Math.min(left, MAX_TIMER_MS);
+                    await abortable(Promise.race([woken.promise, new Promise((r) => (timer = setTimeout(r, slice)))]), signal);
+                }
+                finally {
+                    clearTimeout(timer);
+                }
+            }
+        }
+        catch (err) {
+            leave();
+            throw err;
+        }
+        if (!it.picked && leave())
+            throw new StorageUnavailableError(`no upload slot came free within ${Math.round(wait / 1000)} s; ${key} wasn't saved`);
+        await abortable(it.done.promise, signal);
+        if (it.error !== undefined)
+            throw it.error;
+        if (!it.result)
+            throw new TeepinError(`${key}: no result`);
+        return it.result;
+    }
+    /** Forms a pack from what's waiting whenever a send slot is free. Replaced in tests. */
+    dispatch() {
+        while (this.queue.length && this.limit.tryAcquire()) {
+            const bucket = this.queue[0][0];
+            const waiting = this.queue.filter(([b]) => b === bucket).map(([, it]) => it);
+            const [batch] = nextPack(waiting, (i) => i.size, (i) => i.key, this.packTarget(), this.sizes.packMaxObjects);
+            const chosen = new Set(batch);
+            this.queue = this.queue.filter(([, it]) => !chosen.has(it));
+            this.limit.setPriority(this.queue.length > 0);
+            for (const it of batch) {
+                it.picked = true;
+                it.wake?.resolve(); // its caller may be waiting for a slot: it has one now
+            }
+            void this.runShared(new Pack(bucket, batch, this.memory));
+        }
+    }
+    async runShared(p) {
+        let outcome = 'failed';
+        try {
+            await this.drive(p);
+            outcome = p.throttled ? 'throttled' : p.state === 'committed' ? 'ok' : 'failed';
+        }
+        catch (err) {
+            for (const it of p.items)
+                if (!it.result && it.error === undefined)
+                    it.error = err; // every caller gets its answer
+        }
+        finally {
+            for (const it of p.items)
+                it.done?.resolve();
+            this.release(outcome);
+        }
+    }
+    /**
+     * Every slot comes back through here, from putObject's packs and a run's alike, and putObject's waiting calls are
+     * woken to dispatch: while they wait, a run's next pack waits too (AdaptiveLimit.priority).
+     */
+    release(outcome) {
+        this.limit.release(outcome);
+        const waiters = this.slotWaiters;
+        this.slotWaiters = [];
+        for (const w of waiters)
+            w.resolve();
+    }
+    // --- empty objects, large objects and streams ------------------------------------
+    /**
+     * An empty object: the metadata-only route (section 23.5, A2), which carries no bytes (a pack holds none, and an
+     * upload needs none). Retried by the client as a safe call; no rounds of waiting.
+     */
+    async putEmpty(bucket, key, opts = {}, signal) {
+        const body = { key };
+        if (opts.contentType)
+            body.content_type = opts.contentType;
+        if (opts.metadata && Object.keys(opts.metadata).length)
+            body.metadata = opts.metadata;
+        if (opts.ifNoneMatch)
+            body.if_none_match = true;
+        const ifMatch = normalizeIfMatch(opts.ifMatch);
+        if (ifMatch)
+            body.if_match = ifMatch;
+        try {
+            const { data } = await this.client.call({ method: 'POST', path: `${bucketPath(bucket)}/object/empty`, json: body, mode: 'safe', signal });
+            return objectFrom(data);
+        }
+        catch (err) {
+            if (signal?.aborted)
+                throw signal.reason;
+            if (err instanceof APIError &&
+                (err.code === 'direct_upload_unsupported' || err.statusCode === 501 || (err.statusCode === 404 && (err.code === '' || err.code === 'not_found')))) {
+                throw unsupported(err);
+            }
+            if (err instanceof PreconditionFailedError && opts.ifNoneMatch && (err.attempts ?? 1) > 1) {
+                throw new PreconditionFailedError({
+                    statusCode: 412,
+                    code: err.code,
+                    message: `${err.serverMessage}; if this upload was retried, an earlier attempt may have stored it`,
+                    requestId: err.requestId,
+                });
+            }
+            throw err;
+        }
+    }
+    /** An object over the pack limit from bytes, a Blob or any seekable source, in parts. Kept in memory: nothing could resume it after a crash. */
+    async putLarge(bucket, key, source, opts = {}, signal) {
+        const psize = this.partSize(source.size, opts.partSize ?? 0, key);
+        let hashed;
+        try {
+            hashed = await this.hashParts(source, psize);
+        }
+        catch (err) {
+            if (signal?.aborted)
+                throw signal.reason;
+            throw new FileChangedError(key, err instanceof Error ? err.message : String(err));
+        }
+        const u = new Large(bucket, key, source.size, hashed.whole, (o, n) => source.readAt(o, n), {
+            contentType: opts.contentType,
+            metadata: opts.metadata,
+            ifNoneMatch: opts.ifNoneMatch,
+            ifMatch: normalizeIfMatch(opts.ifMatch),
+            partSize: psize,
+            partHashes: hashed.parts,
+        });
+        return this.parts.run(u, opts.onProgress ? new Progress(source.size, opts.onProgress) : undefined, signal);
+    }
+    /**
+     * A stream over the pack limit whose size isn't known (section 22.1, E2 b), in parts held in memory (concurrency of
+     * them, the sizes' streamConcurrency unless given). Nothing could resume it after a crash.
+     */
+    async putStream(bucket, key, source, opts = {}, signal) {
+        const s = new StreamUpload(bucket, key, this.streamPartSize(opts.expectedSize ?? 0, opts.partSize ?? 0, key), {
+            contentType: opts.contentType,
+            metadata: opts.metadata,
+            ifNoneMatch: opts.ifNoneMatch,
+            ifMatch: normalizeIfMatch(opts.ifMatch),
+        });
+        const link = this.speed.link;
+        // Its parts were shrunk for a slow link: running out of them is the connection's speed (section 22.7).
+        if (link && s.partSize < streamPartSize(opts.expectedSize ?? 0, opts.partSize ?? 0, this.sizes))
+            s.slow = link;
+        const n = opts.concurrency && opts.concurrency > 0 ? opts.concurrency : this.sizes.streamConcurrency;
+        return this.parts.runStream(s, source, n, opts.onProgress ? new Progress(-1, opts.onProgress) : undefined, signal);
+    }
+    /**
+     * A new large upload's part size for size bytes, by this engine's rules, at the speed measured so far: TooLargeError
+     * with reason connection_speed when it can't be sent at it (section 22.7). name is for the error.
+     */
+    partSize(size, want = 0, name = '') {
+        return directPartSize(size, want, this.sizes, this.speed.link, name);
+    }
+    /** A new stream's part size (section 22.1, E2 b), at the speed measured so far, as partSize. */
+    streamPartSize(expectedSize = 0, want = 0, name = '') {
+        return streamPartSize(expectedSize, want, this.sizes, this.speed.link, name);
+    }
+    /**
+     * In one pass: the whole source's SHA-256 (declared at create) and each part's (checked as the part is sent, D1).
+     * Replaced in tests.
+     */
+    async hashParts(source, partSize) {
+        if (source.hashParts)
+            return source.hashParts(partSize);
+        const whole = this.digests.incremental();
+        const parts = new Map();
+        for (const p of tws1.parts(source.size, partSize)) {
+            const data = await source.readAt(p.plainFirst, p.plainSize);
+            if (data.length !== p.plainSize)
+                throw new TeepinError('the source changed size while it was read');
+            whole.update(data);
+            parts.set(p.number, await this.digests.sha256(data));
+        }
+        return { whole: whole.hex(), parts };
+    }
+    // --- upload runs ------------------------------------------------------------------
+    /** A run's first step: journaled (on disk unless journal is false), and every file hashed. */
+    async beginFiles(bucket, entries, opts, signal) {
+        const host = this.runHost;
+        const place = opts.journal === false ? undefined : await host.create();
+        const j = place?.journal ?? new MemoryJournal();
+        const now = Date.now();
+        const store = new RunStore(j, place);
+        try {
+            await j.put('run', 'run', {
+                id: place?.id ?? uuid7(),
+                kind: 'upload',
+                bucket,
+                created: now,
+                updated: now,
+                status: 'open',
+                options: { if_none_match: Boolean(opts.ifNoneMatch) },
+            });
+            const hashed = new Array(entries.length);
+            await pool(this.limit.ceiling, [...entries.keys()], signal, async (i) => {
+                hashed[i] = await host.hashFile(entries[i][1]);
+            });
+            return await this.journalFiles(bucket, store, entries, hashed, opts);
+        }
+        catch (err) {
+            await this.abandon(store, place); // nothing is under way
+            throw signal?.aborted ? signal.reason : err;
+        }
+    }
+    async journalFiles(bucket, store, entries, hashed, opts) {
+        const j = store.journal;
+        const host = this.runHost;
+        const results = new Map();
+        const items = [];
+        const rows = [];
+        entries.forEach(([key, path], i) => {
+            const h = hashed[i];
+            const id = j.nextId('files');
+            if (h instanceof Error) {
+                rows.push({ table: 'files', id, row: { _id: id, path, key, size: -1, mtime: '', sha256: '', state: 'failed', error: describe(h) } });
+                results.set(id, { key, path, status: 'failed', error: h });
+                return;
+            }
+            const ct = opts.contentType || host.contentType(path) || '';
+            rows.push({
+                table: 'files',
+                id,
+                row: {
+                    _id: id,
+                    path,
+                    key,
+                    size: h.size,
+                    mtime: h.mtime,
+                    sha256: h.sha256,
+                    content_type: ct,
+                    metadata: { ...(opts.metadata ?? {}) },
+                    if_none_match: Boolean(opts.ifNoneMatch),
+                    if_match: '',
+                    state: 'queued',
+                },
+            });
+            items.push(this.fileItem(key, path, h.size, h.sha256, ct, opts.metadata, Boolean(opts.ifNoneMatch), id));
+        });
+        await j.write([...rows, ...store.touch()]);
+        return { bucket, store, place: store.place, items, packs: [], results };
+    }
+    fileItem(key, path, size, sha, contentType, metadata, ifNoneMatch, fileId) {
+        const host = this.runHost;
+        return new Item(key, size, sha, () => host.readWhole(path, size), contentType, metadata, ifNoneMatch, '', path, fileId);
+    }
+    /**
+     * A run's middle and last steps: its empty files put (the A2 route), then its queued items packed, its packs already
+     * under way and its large files sent, every file's result recorded and the run finished. partSize is for files sent
+     * in parts (0: the default).
+     */
+    async runState(state, onProgress, partSize = 0, signal) {
+        try {
+            const empties = state.items.filter((it) => it.size === 0);
+            for (const it of empties) {
+                try {
+                    const obj = await this.putEmpty(state.bucket, it.key, { contentType: it.contentType || undefined, metadata: it.metadata, ifNoneMatch: it.ifNoneMatch }, signal);
+                    await this.done(state.store, [[it, obj, undefined, true]]);
+                }
+                catch (err) {
+                    if (signal?.aborted || !(err instanceof TeepinError))
+                        throw err;
+                    await this.done(state.store, [[it, undefined, err, emptyPutFinal(err)]]);
+                }
+            }
+        }
+        catch (err) {
+            await this.abandon(state.store, state.place); // interrupted before any pack started
+            throw signal?.aborted ? signal.reason : err;
+        }
+        // The empty files stay in state.items, so send reports them with the rest (it packs only sizes above 0).
+        return this.sendRun(state, onProgress, partSize, signal);
+    }
+    async sendRun(state, onProgress, partSize, signal) {
+        const { bucket, store, place, items } = state;
+        const lim = this.packObjectLimit();
+        // A file whose upload in parts a crash left open goes on in parts, whatever the speed now (section 22.7).
+        const inParts = new Set(store.journal
+            .rows('uploads')
+            .filter((r) => r.state !== 'completed' && r.state !== 'failed')
+            .map((r) => str(r.file_id)));
+        const large = items.filter((it) => it.size > lim || (it.size > 0 && it.fileId !== undefined && inParts.has(it.fileId)));
+        const chosen = new Set(large);
+        const small = items.filter((it) => it.size > 0 && !chosen.has(it));
+        // The small files are packed as slots come free, each pack at the speed measured by then (section 22.7).
+        const packs = [...state.packs];
+        let total = 0;
+        for (const p of packs)
+            for (const it of p.items)
+                total += it.size;
+        for (const it of [...small, ...large])
+            total += it.size;
+        const prog = new Progress(total, onProgress);
+        const stop = [];
+        const closer = new RunCloser();
+        // The run's tasks stop when the caller aborts, or when this step fails.
+        const { ctl, unlink } = linked(signal);
+        let failure;
+        const failed = (err) => {
+            if (failure)
+                return;
+            failure = { err };
+            ctl.abort(err);
+        };
+        const pack = async (p) => {
+            let outcome = 'failed';
+            try {
+                if (stop.length) {
+                    await this.fail(p, stop[0], false);
+                    return;
+                }
+                await this.drive(p, ctl.signal);
+                outcome = p.throttled ? 'throttled' : p.state === 'committed' ? 'ok' : 'failed';
+                for (const it of p.items)
+                    if (it.result)
+                        prog.add(it.size);
+            }
+            catch (err) {
+                if (ctl.signal.aborted || !stopsRun(err))
+                    throw err;
+                stop.push(err);
+            }
+            finally {
+                this.release(outcome);
+            }
+        };
+        const go = async (p) => {
+            try {
+                await pack(p);
+            }
+            finally {
+                if (closer.ended(true))
+                    await this.abandon(store, place); // the last task of an interrupted run releases it
+            }
+        };
+        const tasks = [];
+        try {
+            const start = (p) => {
+                closer.started();
+                tasks.push(go(p).catch(failed));
+            };
+            for (const p of [...packs]) {
+                await this.limit.acquire(ctl.signal);
+                if (failure) {
+                    this.release('failed');
+                    throw failure.err;
+                }
+                start(p);
+            }
+            for (let rest = small; rest.length;) {
+                await this.limit.acquire(ctl.signal);
+                if (failure) {
+                    this.release('failed');
+                    throw failure.err;
+                }
+                let chunk;
+                [chunk, rest] = nextPack(rest, (i) => i.size, (i) => i.key, this.packTarget(), this.sizes.packMaxObjects);
+                const p = new Pack(bucket, chunk, store);
+                packs.push(p);
+                start(p);
+            }
+            for (const it of large) {
+                if (stop.length) {
+                    await this.done(store, [[it, undefined, stop[0], false]]);
+                    continue;
+                }
+                try {
+                    const u = await this.largeItem(bucket, it, store, partSize);
+                    const obj = await this.parts.run(u, prog, ctl.signal);
+                    await this.done(store, [[it, obj, undefined, true]]);
+                }
+                catch (err) {
+                    if (ctl.signal.aborted)
+                        throw ctl.signal.reason;
+                    if (stopsRun(err)) {
+                        await this.done(store, [[it, undefined, err, false]]);
+                        stop.push(err);
+                    }
+                    else if (err instanceof StorageUnavailableError)
+                        await this.done(store, [[it, undefined, err, false]]);
+                    else if (err instanceof TeepinError)
+                        await this.done(store, [[it, undefined, err, true]]);
+                    else
+                        throw err;
+                }
+            }
+            // A task that fails stops the run at once (its controller aborts), as joining it first would.
+            await abortable(Promise.all(tasks), ctl.signal);
+            if (failure)
+                throw failure.err;
+        }
+        catch (err) {
+            // Interrupted, or failed: every pack still under way is stopped and waited for (up to the cap); then the run's
+            // journal is closed and its lock released, so resumeUploads in this same process can finish it. Never while a pack
+            // might still commit (it could be saved twice): whichever ends last, this step or the last pack task, releases it.
+            ctl.abort(err);
+            await joinCapped(tasks, this.cleanupMs);
+            if (closer.ended(false))
+                await this.abandon(store, place);
+            unlink();
+            throw signal?.aborted ? signal.reason : failure ? failure.err : err;
+        }
+        unlink();
+        const seen = new Set(items);
+        const every = [...items, ...packs.flatMap((p) => p.items).filter((it) => !seen.has(it))];
+        const results = state.results;
+        for (const it of every) {
+            if (it.fileId === undefined || results.has(it.fileId))
+                continue;
+            // pending: a passing error (storage down, a revoked key) left it journaled for resumeUploads; failed is final.
+            const status = it.result ? 'saved' : it.final ? 'failed' : 'pending';
+            results.set(it.fileId, { key: it.key, path: it.path, status, object: it.result, error: it.error });
+        }
+        await this.finish(store, place);
+        if (stop.length)
+            throw stop[0];
+        return [...results.entries()].sort(([a], [b]) => Number(a) - Number(b)).map(([, r]) => r);
+    }
+    /** A large file's upload: the one its journal left unfinished, or a new one. */
+    async largeItem(bucket, it, store, partSize) {
+        const host = this.runHost;
+        const path = it.path ?? '';
+        const readAt = (off, n) => host.readAt(path, off, n);
+        const open = store.journal
+            .rows('uploads')
+            .filter((r) => str(r.file_id) === it.fileId && r.state !== 'completed' && r.state !== 'failed')
+            .sort((a, b) => Number(b.updated) - Number(a.updated));
+        const common = { contentType: it.contentType, metadata: it.metadata, ifNoneMatch: it.ifNoneMatch, ifMatch: it.ifMatch, path, store, fileId: it.fileId };
+        if (open.length) {
+            const u = await Large.fromRow(open[0], readAt, common);
+            if (u.state === 'new' && u.plain.size === 0) {
+                // Never created, so no part hashes were journaled: take them now, against the queued hash.
+                const h = await this.hashFileParts(it, readAt, u.partSize);
+                if (h.whole !== it.sha256)
+                    throw new FileChangedError(path);
+                u.plain = h.parts;
+            }
+            return u;
+        }
+        const psize = this.partSize(it.size, partSize, it.key);
+        const h = await this.hashFileParts(it, readAt, psize);
+        if (h.whole !== it.sha256)
+            throw new FileChangedError(path);
+        return new Large(bucket, it.key, it.size, it.sha256, readAt, { ...common, partSize: psize, partHashes: h.parts });
+    }
+    /** A large file's whole and part hashes; a file that can't be read the same way is a changed file. */
+    async hashFileParts(it, readAt, partSize) {
+        const host = this.runHost;
+        const path = it.path ?? '';
+        const source = { size: it.size, readAt };
+        if (host.hashParts)
+            source.hashParts = (ps) => host.hashParts(path, it.size, ps);
+        try {
+            return await this.hashParts(source, partSize);
+        }
+        catch (err) {
+            if (err instanceof FileChangedError)
+                throw err;
+            throw new FileChangedError(path || it.key, err instanceof Error ? err.message : String(err));
+        }
+    }
+    /** An interrupted run, left for resumeUploads: its journal closed and its lock released (its directory stays). Safe to call twice. */
+    async abandon(store, place) {
+        if (place)
+            await place.release();
+        else
+            await store.journal.close().catch(() => undefined);
+    }
+    async finish(store, place) {
+        const j = store.journal;
+        const counts = countStates(j.rows('files'));
+        const pending = (counts.get('queued') ?? 0) + (counts.get('packed') ?? 0);
+        const run = j.get('run', 'run');
+        if (pending) {
+            if (run)
+                await j.put('run', 'run', { ...run, updated: Date.now(), status: 'open' });
+            await this.abandon(store, place);
+            return;
+        }
+        await j.close();
+        if (!place)
+            return;
+        const host = this.runHost;
+        await host.history(`run ${str(run?.id) || place.id} bucket=${str(run?.bucket)} saved=${counts.get('saved') ?? 0} failed=${counts.get('failed') ?? 0}`);
+        await place.remove();
+        const size = await host.size().catch(() => 0);
+        const warnAt = envNumber(STATE_WARN_ENV, STATE_WARN_BYTES);
+        if (size > warnAt)
+            this.warn(`teepin: the upload state directory holds ${size} bytes; cleanUploads() removes old runs`);
+    }
+    // --- resume, listing and cleanup ------------------------------------------------------
+    /** Continues every interrupted run no other process (or run in this one) is working on, and returns their files' results. */
+    async resume(onProgress, signal) {
+        const host = this.runHost;
+        const out = [];
+        for (const id of await host.ids()) {
+            signal?.throwIfAborted();
+            let place;
+            try {
+                place = await host.take(id);
+            }
+            catch (err) {
+                // A damaged journal: never skipped silently, and never in the way of the other runs.
+                this.warn(`teepin: upload run ${id} can't be resumed: ${err instanceof Error ? err.message : String(err)}`);
+                continue;
+            }
+            if (!place)
+                continue;
+            let state;
+            try {
+                state = await this.beginResume(place, signal);
+            }
+            catch (err) {
+                await place.release();
+                throw signal?.aborted ? signal.reason : err;
+            }
+            out.push(...(await this.runState(state, onProgress, 0, signal))); // it releases the run itself, as it ends
+        }
+        return out;
+    }
+    /** A run's first step on resume: its journal read back, its queued files checked again (a changed one fails, and its large upload is cancelled). */
+    async beginResume(place, signal) {
+        const store = new RunStore(place.journal, place);
+        const { state, changed } = await this.readRun(place, store);
+        for (const [fid, it, path] of changed) {
+            signal?.throwIfAborted();
+            await this.endUploads(store, fid); // its large upload, if any: cancelled, its key deleted
+            const err = new FileChangedError(path);
+            await this.done(store, [[it, undefined, err, true]]);
+            state.results.set(fid, { key: it.key, path, status: 'failed', error: err });
+        }
+        return state;
+    }
+    async readRun(place, store) {
+        const host = this.runHost;
+        const j = store.journal;
+        const bucket = str(j.get('run', 'run')?.bucket);
+        const results = new Map();
+        const byPack = new Map();
+        const queued = [];
+        const changed = [];
+        for (const f of j.rows('files')) {
+            const id = str(f._id);
+            const key = str(f.key);
+            const path = str(f.path);
+            if (f.state === 'saved') {
+                results.set(id, { key, path, status: 'saved', object: reviveObject(f.result) });
+                continue;
+            }
+            if (f.state === 'failed') {
+                results.set(id, { key, path, status: 'failed', error: new TeepinError(str(f.error)) });
+                continue;
+            }
+            const it = this.fileItem(key, path, int(f.size), str(f.sha256), str(f.content_type), f.metadata ?? {}, Boolean(f.if_none_match), id);
+            it.objectId = str(f.object_id);
+            if (f.state === 'packed' && f.pack) {
+                it.journaled = `${str(f.pack)}|${it.objectId}`;
+                const list = byPack.get(str(f.pack)) ?? [];
+                list.push(it);
+                byPack.set(str(f.pack), list);
+            }
+            else {
+                // Queued: checked again as it's queued again (section 17.5); a change fails it.
+                const h = await host.hashFile(path);
+                if (h instanceof Error || h.size !== int(f.size) || h.sha256 !== str(f.sha256)) {
+                    changed.push([id, it, path]);
+                    continue;
+                }
+                queued.push(it);
+            }
+        }
+        const packs = [];
+        for (const r of j.rows('packs')) {
+            const pid = str(r._id);
+            if (r.state === 'committed' || r.state === 'failed')
+                continue;
+            const its = byPack.get(pid);
+            byPack.delete(pid);
+            if (!its?.length)
+                continue;
+            const p = new Pack(bucket, its, store, pid);
+            p.state = (str(r.state) || 'new');
+            p.idem = str(r.idempotency_key);
+            p.reservation = r.reservation ?? {};
+            p.signBody = r.sign_body ?? {};
+            p.signed = r.signed ?? {};
+            p.fileName = str(r.file_name);
+            p.size = int(r.size);
+            p.md5 = str(r.md5);
+            p.sha256 = str(r.sha256);
+            p.attempts = int(r.attempts);
+            if (p.state === 'uploading')
+                p.state = 'unknown'; // the PUT may have landed: commit first
+            packs.push(p);
+        }
+        for (const its of byPack.values())
+            queued.push(...its); // packed into a pack that's gone: queue them again
+        await this.sweepOrphans(place, j, packs);
+        return { state: { bucket, store, place, items: queued, packs, results }, changed };
+    }
+    /** Pack files the journal doesn't name, and data keys of uploads that have ended, are deleted (section 17.12, E3). */
+    async sweepOrphans(place, j, packs) {
+        const keep = new Set(packs.map((p) => p.fileName).filter(Boolean));
+        for (const name of await place.packNames().catch(() => []))
+            if (!keep.has(name))
+                await place.removePack(name).catch(() => undefined);
+        const open = new Set(j
+            .rows('uploads')
+            .filter((r) => OPEN_UPLOAD.has(str(r.state)))
+            .map((r) => str(r._id)));
+        for (const name of await place.keyNames().catch(() => []))
+            if (!open.has(name))
+                await place.removeKey(name).catch(() => undefined);
+    }
+    /**
+     * Cancels a file's unfinished large uploads at the storage network and deletes their journaled data keys (E3): a file
+     * that won't be sent must not leave parts behind to be kept, and billed, until they expire.
+     */
+    async endUploads(store, fileId) {
+        for (const r of store.journal.rows('uploads')) {
+            if (str(r.file_id) !== fileId || !OPEN_UPLOAD.has(str(r.state)))
+                continue;
+            if (r.upload_id)
+                await this.abortOne(str(r.bucket), str(r.upload_id));
+            await store.journal.put('uploads', str(r._id), { ...r, state: 'failed', updated: Date.now() });
+            await store.place?.removeKey(str(r._id)).catch(() => undefined);
+        }
+    }
+    /** Cancels an upload: one call (the client's own retries, none while stopping), best effort, since the upload sweeper ends what it misses. */
+    async abortOne(bucket, uploadId, stopping = false) {
+        try {
+            await this.client.send({
+                method: 'DELETE',
+                path: `${bucketPath(bucket)}/uploads/${encodeURIComponent(uploadId)}`,
+                mode: 'safe',
+                maxRetries: stopping ? 0 : undefined,
+                timeout: this.cleanupMs,
+            });
+        }
+        catch {
+            // the upload sweeper ends it
+        }
+    }
+    /** The runs kept in the state directory. */
+    async listRuns() {
+        const host = this.runHost;
+        const out = [];
+        const now = Date.now();
+        for (const id of await host.ids()) {
+            const seen = await host.peek(id).catch(() => undefined); // a damaged journal is left out, not fatal
+            if (!seen)
+                continue;
+            const run = seen.journal.get('run', 'run');
+            if (!run)
+                continue;
+            const counts = countStates(seen.journal.rows('files'));
+            let files = 0;
+            for (const n of counts.values())
+                files += n;
+            const updated = new Date(Number(run.updated));
+            out.push({
+                id: str(run.id) || id,
+                bucket: str(run.bucket),
+                created: new Date(Number(run.created)),
+                updated,
+                files,
+                saved: counts.get('saved') ?? 0,
+                failed: counts.get('failed') ?? 0,
+                pending: (counts.get('queued') ?? 0) + (counts.get('packed') ?? 0),
+                expired: now - updated.getTime() > RUN_EXPIRY_MS,
+                inUse: seen.inUse,
+            });
+        }
+        return out;
+    }
+    /**
+     * Removes runs untouched for longer than olderThan ms that no process is working on, with a warning for each: never
+     * silently. Their open large uploads are cancelled, and their data keys go with their journals (E3).
+     */
+    async clean(olderThan, signal) {
+        const host = this.runHost;
+        const removed = [];
+        const cutoff = Date.now() - olderThan;
+        for (const r of await this.listRuns()) {
+            signal?.throwIfAborted();
+            if (r.inUse || r.updated.getTime() > cutoff)
+                continue;
+            const place = await host.take(r.id).catch(() => undefined);
+            if (!place)
+                continue;
+            try {
+                for (const u of place.journal.rows('uploads')) {
+                    if (u.upload_id && OPEN_UPLOAD.has(str(u.state)))
+                        await this.abortOne(str(u.bucket), str(u.upload_id));
+                }
+                this.warn(`teepin: removing upload run ${r.id} (bucket ${r.bucket}): ${r.pending} files not uploaded, untouched since ${r.updated.toISOString()}`);
+                await place.remove();
+                removed.push(r);
+            }
+            catch (err) {
+                await place.release();
+                throw err;
+            }
+        }
+        await host.trimHistory?.();
+        return removed;
+    }
+}
+// --- helpers ------------------------------------------------------------------------------------------------------------
+/** A storage PUT its own timer ended with no answer (putSigned): a ConnectionError, and evidence of a slow link. */
+class PutTimedOut extends ConnectionError {
+    constructor(ms) {
+        super(`no answer from the storage network in ${Math.round(ms)} ms`);
+    }
+}
+/** An If-Match value as the control plane takes it: unquoted, or "*". */
+export function normalizeIfMatch(v) {
+    if (!v)
+        return '';
+    return v === '*' ? '*' : unquote(v);
+}
+function countStates(rows) {
+    const out = new Map();
+    for (const r of rows)
+        out.set(str(r.state), (out.get(str(r.state)) ?? 0) + 1);
+    return out;
+}
+/** The states of a large upload that may still have parts at the storage network. */
+const OPEN_UPLOAD = new Set(['new', 'sending', 'completing']);
+function unsupported(err) {
+    return apiError({
+        statusCode: err.statusCode,
+        message: "this deployment doesn't accept direct uploads, and this SDK uploads no other way",
+        code: err.code || 'direct_upload_unsupported',
+        requestId: err.requestId,
+    });
+}
+//# sourceMappingURL=uploads.js.map