@teepin/sdk 0.2.0 → 0.3.0-rc.1

package/dist/esm/direct/reads.js

@@ -0,0 +1,1275 @@
+// Copyright 2026 TEEPIN Project
+// Licensed under the Apache License, Version 2.0
+// Reads straight from the storage network (TEEPIN-STORAGE-DESIGN.md sections 21.3, 22.5 and 24), a port of
+// teepin-python's _reads.py with the same rules.
+//
+// A read session (object/read) gives an object's format, where its bytes are, its data key, and signed requests for
+// them. Every byte is verified before it is used:
+//
+// - tws1 in its own blob: windows (the server's, 64 MiB), read segment by segment as they stream, each GCM tag checked
+//   (the header's key commitment first, the last segment told by the session's size). A window that breaks off goes
+//   on from its last verified segment, under a new signature.
+// - anything packed: the needle first (TPK1, the object id, which is the session's version, the stored size, and the
+//   stored bytes' SHA-256), then the whole object decrypted (tws1, teepin-v1) or taken as stored (plain).
+// - plain in its own blob (legacy objects only): as stored.
+// - source "api": an object still in the API's old stage. It isn't read (the API's content route is retired): the read
+//   fails with stagedError until the object has been moved into storage.
+//
+// A whole-object read also checks the plaintext SHA-256 against the session's, as its last bytes arrive, except for a
+// legacy object stored in parts, whose checksum is a composite. Streamed bytes are hashed with sha256.ts, since a
+// browser's WebCrypto can only hash a whole buffer.
+//
+// Data keys are cached in memory for the client's keyCacheTtl (10 minutes), by bucket, key and version, so later reads
+// sign without them. Each read takes its own copy and zeroes it when done; the cache zeroes its copies on expiry,
+// eviction and close.
+//
+// Failures: a passing one (the network, a busy storage network) is retried with backoff; an expired or refused
+// signature is signed again; a 404 is signed again once (a server pack may have been compacted), then NotFoundError;
+// a failed check is retried once, then DataIntegrityError.
+//
+// A share link's reads (LinkReads, section 26.3) are the same, with their sessions from the link's token.
+//
+// Cancellation is an AbortSignal (section 22.13's rules). An abort ends a read at once and rejects with the signal's
+// reason: open responses are closed, a wait is cut short, and a download's parallel windows are all stopped and waited
+// for, so no request is left running. Cleanup never retries or sleeps.
+//
+// Nothing here imports a Node module: the same code runs in Node 20+ and browsers.
+import { backoff } from '../client.js';
+import { APIError, ChecksumMismatchError, ConnectionError, DataIntegrityError, InvalidLinkError, KeyErasedError, NotFoundError, ObjectChangedError, TeepinError, apiError, } from '../errors.js';
+import { concat, constantTimeEqual, fromBase64, isInt } from './bytes.js';
+import { SIGN_MARGIN_MS } from './engine.js';
+import { FORMAT_SERVER, FORMAT_TWS1, FORMATS, SOURCE_API, SOURCE_STORAGE, openServerV1 } from './formats.js';
+import { Sha256 } from './sha256.js';
+import * as tws1 from './tws1.js';
+/** The server's read window until it shows its own: 64 MiB of stored bytes. */
+export const DEFAULT_WINDOW = 64 * 2 ** 20;
+/** How long a data key stays cached, in ms, unless the client says. */
+export const DEFAULT_KEY_CACHE_TTL_MS = 600000;
+/** The most a plain blob's read takes from its body at once. */
+const READ_CHUNK = 2 ** 20;
+/** Keys a batch read session names at most (the control plane's cap). */
+const READ_BATCH = 1000;
+const EMPTY = new Uint8Array(0);
+const bucketPath = (bucket) => `/v1/storage/buckets/${encodeURIComponent(bucket)}`;
+const unquote = (etag) => etag.trim().replace(/^W\//, '').replace(/^"|"$/g, '');
+const str = (v) => (v === undefined || v === null ? '' : String(v));
+const int = (v) => Math.trunc(Number(v || 0)) || 0;
+/** A time from the API, or undefined when there is none or it doesn't parse. */
+function when(v) {
+    if (!v)
+        return undefined;
+    const t = Date.parse(String(v));
+    return Number.isNaN(t) ? undefined : new Date(t);
+}
+async function sha256Hex(data) {
+    return Array.from(new Uint8Array(await crypto.subtle.digest('SHA-256', data)), (b) => b.toString(16).padStart(2, '0')).join('');
+}
+/** The error for reading an object still in the API's old stage (a session with source "api"): it can't be read yet. */
+export function stagedError(key) {
+    return new TeepinError(`${key}: this object is still being moved into storage and can't be read yet; try again later`);
+}
+/** A window that stopped short: go on from the last verified byte. A ConnectionError, as it is to a caller. */
+class Broken extends ConnectionError {
+}
+/** A signature too close to its expiry to use. */
+class Expired extends TeepinError {
+    constructor() {
+        super('the signature is about to expire');
+        this.name = 'Expired';
+    }
+}
+/** A controller that aborts with parent's reason, and a function that unlinks it once it is no longer needed. */
+export function linked(parent) {
+    const ctl = new AbortController();
+    if (!parent)
+        return { ctl, unlink: () => { } };
+    if (parent.aborted) {
+        ctl.abort(parent.reason);
+        return { ctl, unlink: () => { } };
+    }
+    const onAbort = () => ctl.abort(parent.reason);
+    parent.addEventListener('abort', onAbort, { once: true });
+    return { ctl, unlink: () => parent.removeEventListener('abort', onAbort) };
+}
+// --- sessions -----------------------------------------------------------------
+/** One signed request to the storage network. */
+export class Signed {
+    url;
+    headers;
+    expires;
+    prefix;
+    first;
+    last;
+    constructor(url, headers, 
+    /** When the signature expires (ms since the epoch); undefined when the session didn't say. */
+    expires, 
+    /** Bytes before the object's own (a packed object's needle). */
+    prefix, 
+    /** The object's stored bytes it covers, inclusive. */
+    first, last) {
+        this.url = url;
+        this.headers = headers;
+        this.expires = expires;
+        this.prefix = prefix;
+        this.first = first;
+        this.last = last;
+    }
+    static of(d) {
+        const headers = {};
+        for (const [k, v] of Object.entries(d.headers ?? {}))
+            headers[k] = str(v);
+        return new Signed(str(d.url), headers, when(d.expires_at)?.getTime(), int(d.prefix), int(d.stored_first), int(d.stored_last));
+    }
+    /** The bytes it answers: the prefix and the object's own. */
+    get length() {
+        return this.prefix + this.last - this.first + 1;
+    }
+    /** Whether it can still be used: not within a minute of its expiry. */
+    fresh() {
+        return this.expires === undefined || this.expires - Date.now() > SIGN_MARGIN_MS;
+    }
+}
+/** One read session. dek is this session's own copy of the data key. */
+export class Session {
+    bucket;
+    key;
+    version;
+    size;
+    storedSize;
+    etag;
+    sha256;
+    contentType;
+    metadata;
+    format;
+    source;
+    uploadedAt;
+    dek;
+    ad;
+    requests;
+    constructor(bucket, d) {
+        this.bucket = bucket;
+        this.key = str(d.key);
+        this.version = str(d.version);
+        this.size = int(d.size);
+        this.storedSize = int(d.stored_size);
+        this.etag = unquote(str(d.etag));
+        this.sha256 = str(d.sha256);
+        this.contentType = str(d.content_type);
+        this.metadata = { ...(d.metadata ?? {}) };
+        this.format = str(d.format);
+        this.source = str(d.source) || SOURCE_STORAGE;
+        this.uploadedAt = when(d.uploaded_at);
+        this.dek = d.key_material ? fromBase64(String(d.key_material)) : null;
+        this.ad = fromBase64(str(d.associated_data));
+        this.requests = (d.requests ?? []).map((r) => Signed.of(r));
+        if (this.source === SOURCE_STORAGE && !FORMATS.includes(this.format)) {
+            throw new DataIntegrityError(`${this.key}: unknown storage format ${JSON.stringify(this.format)}`, 'format');
+        }
+    }
+    /** Still in the API's old stage: not readable yet (stagedError). */
+    get staged() {
+        return this.source === SOURCE_API;
+    }
+    get packed() {
+        return this.requests.length > 0 && this.requests[this.requests.length - 1].prefix > 0;
+    }
+    /** The window it signs: its last request (a later window's first one is the header). */
+    get window() {
+        return this.requests[this.requests.length - 1];
+    }
+    get needsKey() {
+        return !this.staged && this.storedSize > 0 && (this.format === FORMAT_TWS1 || this.format === FORMAT_SERVER);
+    }
+    /** Whether the whole object's SHA-256 can be checked (not a legacy composite of parts). */
+    get checkable() {
+        return Boolean(this.sha256) && !this.etag.includes('-');
+    }
+    /** Zeroes this session's copy of the key. */
+    forget() {
+        this.dek?.fill(0);
+        this.dek = null;
+    }
+    /** The object's details, as statObject would give them. */
+    object() {
+        const parts = /-(\d+)$/.exec(this.etag);
+        const t = this.uploadedAt ?? new Date(NaN);
+        return {
+            id: this.version,
+            key: this.key,
+            size: this.size,
+            contentType: this.contentType || undefined,
+            metadata: this.metadata,
+            checksumSha256: this.sha256 || undefined,
+            etag: this.etag,
+            partCount: parts ? Number(parts[1]) : 0,
+            status: 'available',
+            backend: '',
+            createdAt: t,
+            updatedAt: t,
+            uploadedAt: this.uploadedAt,
+        };
+    }
+}
+/**
+ * Data keys by bucket and key, each for one version, for ttl ms (0: none are kept). It hands out copies, so zeroing one
+ * never breaks a read in progress, and zeroes its own on expiry, replacement, drop and clear.
+ */
+export class KeyCache {
+    ttl;
+    /** The clock, in ms (monotonic); a test may move it. */
+    now = () => performance.now();
+    entries = new Map();
+    constructor(ttl) {
+        this.ttl = ttl;
+    }
+    static id(bucket, key) {
+        return JSON.stringify([bucket, key]);
+    }
+    /** The cached version and a copy of its key, or undefined. */
+    get(bucket, key) {
+        const id = KeyCache.id(bucket, key);
+        const e = this.entries.get(id);
+        if (!e)
+            return undefined;
+        if (this.now() - e.at > this.ttl) {
+            this.entries.delete(id);
+            e.key.fill(0);
+            return undefined;
+        }
+        return { version: e.version, key: e.key.slice() };
+    }
+    /** Keeps a copy of dek for this version (the caller keeps its own). */
+    put(bucket, key, version, dek) {
+        if (this.ttl <= 0)
+            return; // the cache is off: the caller's copy is the only one
+        const id = KeyCache.id(bucket, key);
+        const old = this.entries.get(id);
+        if (old && old.version === version)
+            return;
+        this.entries.set(id, { version, key: dek.slice(), at: this.now() });
+        old?.key.fill(0);
+    }
+    drop(bucket, key) {
+        const id = KeyCache.id(bucket, key);
+        const e = this.entries.get(id);
+        this.entries.delete(id);
+        e?.key.fill(0);
+    }
+    clear() {
+        for (const e of this.entries.values())
+            e.key.fill(0);
+        this.entries.clear();
+    }
+    get size() {
+        return this.entries.size;
+    }
+}
+/** One read's failures since its last verified bytes, and what each means. */
+export class Tries {
+    reads;
+    s;
+    signal;
+    passing = 0;
+    bad = 0;
+    notFound = false;
+    constructor(reads, s, signal) {
+        this.reads = reads;
+        this.s = s;
+        this.signal = signal;
+    }
+    progressed() {
+        this.passing = 0;
+        this.bad = 0;
+    }
+    /** Resolves when the read should try again (after any wait); throws otherwise. An abort is never tried again. */
+    async failed(err) {
+        if (this.signal?.aborted)
+            throw this.signal.reason;
+        // A share link that expired (or was never good) stays so: signing again would only be refused again.
+        if (err instanceof ObjectChangedError || err instanceof InvalidLinkError)
+            throw err;
+        if (err instanceof DataIntegrityError) {
+            this.bad++; // retried once: a flipped byte in transit, or for good
+            if (this.bad > 1)
+                throw err;
+            return;
+        }
+        if (err instanceof APIError && err.statusCode === 404) {
+            // A server pack may have been compacted, so the bytes moved: sign again, once.
+            this.reads.keys.drop(this.s.bucket, this.s.key);
+            if (this.notFound) {
+                throw new NotFoundError({ statusCode: 404, message: `${this.s.key}: the storage network doesn't have this object`, code: 'object_not_found' });
+            }
+            this.notFound = true;
+            return;
+        }
+        const resign = err instanceof Expired || (err instanceof APIError && (err.statusCode === 401 || err.statusCode === 403));
+        const passing = err instanceof ConnectionError || (err instanceof APIError && (err.statusCode === 429 || err.statusCode >= 500));
+        if (!(resign || passing))
+            throw err;
+        this.passing++;
+        if (this.passing > this.reads.client.maxRetries) {
+            if (err instanceof Expired)
+                throw new TeepinError(`${this.s.key}: every signature expired before it could be used; check this computer's clock`);
+            throw err;
+        }
+        if (passing)
+            await this.reads.client.sleep(backoff(this.passing - 1, err), this.signal);
+    }
+}
+/** A signed GET's body as it arrives, read a piece at a time; each read waits at most idleMs for bytes. */
+export class Body {
+    ctl;
+    unlink;
+    idleMs;
+    signal;
+    reader;
+    rest = EMPTY;
+    ended;
+    closed = false;
+    constructor(response, ctl, unlink, idleMs, signal) {
+        this.ctl = ctl;
+        this.unlink = unlink;
+        this.idleMs = idleMs;
+        this.signal = signal;
+        this.reader = response.body?.getReader();
+        this.ended = !this.reader;
+    }
+    /** Up to max bytes (fewer is fine), empty at the end. A body that breaks off throws ConnectionError. */
+    async read(max) {
+        while (!this.rest.length) {
+            const c = await this.next();
+            if (!c)
+                return EMPTY;
+            this.rest = c;
+        }
+        const out = this.rest.length > max ? this.rest.subarray(0, max) : this.rest;
+        this.rest = this.rest.subarray(out.length);
+        return out;
+    }
+    /** n bytes, or fewer where the body ends. */
+    async readExact(n) {
+        const first = await this.read(n);
+        if (first.length === n || !first.length)
+            return first;
+        const parts = [first];
+        let got = first.length;
+        while (got < n) {
+            const c = await this.read(n - got);
+            if (!c.length)
+                break;
+            parts.push(c);
+            got += c.length;
+        }
+        return concat(parts);
+    }
+    async next() {
+        if (this.ended || !this.reader)
+            return null;
+        const ms = this.idleMs;
+        const timer = ms > 0 ? setTimeout(() => this.ctl.abort(new ConnectionError(`the storage network sent nothing for ${ms} ms`)), ms) : undefined;
+        try {
+            const { done, value } = await this.reader.read();
+            if (done) {
+                this.ended = true;
+                return null;
+            }
+            return value;
+        }
+        catch (err) {
+            if (this.signal?.aborted)
+                throw this.signal.reason;
+            const why = this.ctl.signal.reason;
+            if (this.ctl.signal.aborted && why instanceof ConnectionError)
+                throw why;
+            throw new ConnectionError(`the read broke off: ${err instanceof Error ? err.message : String(err)}`, err);
+        }
+        finally {
+            clearTimeout(timer);
+        }
+    }
+    /** Ends the request: a body not read to its end is cancelled and its connection dropped. Never waits. */
+    close() {
+        if (this.closed)
+            return;
+        this.closed = true;
+        this.unlink();
+        if (!this.ended) {
+            this.ctl.abort(new TeepinError('the read was closed'));
+            this.reader?.cancel().catch(() => undefined);
+        }
+    }
+}
+class Progress {
+    total;
+    fn;
+    done = 0;
+    constructor(total, fn) {
+        this.total = total;
+        this.fn = fn;
+    }
+    add(n) {
+        if (!this.fn || n === 0)
+            return;
+        this.done += n;
+        this.fn(this.done, this.total);
+    }
+}
+/**
+ * Reads through read sessions, for one client. The methods tests replace (as the Python tests patch _reads.py) are
+ * call, session, window, open and plaintext.
+ */
+export class DirectReads {
+    client;
+    keys;
+    constructor(client) {
+        this.client = client;
+        this.keys = new KeyCache(client.keyCacheTtl);
+    }
+    /** Zeroes the cached data keys. */
+    close() {
+        this.keys.clear();
+    }
+    // --- sessions ---------------------------------------------------------------
+    /** One read session (object/read), retried by the client as a safe call. */
+    async call(bucket, key, off, length, includeKey, signal) {
+        const json = { key, stored_offset: off, stored_length: length, include_key: includeKey };
+        const { data } = await this.client.call({
+            method: 'POST',
+            path: bucketPath(bucket) + '/object/read',
+            json,
+            mode: 'safe',
+            signal,
+        });
+        return new Session(bucket, data ?? {});
+    }
+    /**
+     * A read's first session, with the data key: from the cache when it holds this version's, so the server needn't send
+     * it again. An object still in the old stage throws stagedError.
+     */
+    async session(bucket, key, off = 0, length = 0, signal) {
+        let cached = this.keys.get(bucket, key);
+        let s;
+        try {
+            s = await this.call(bucket, key, off, length, cached === undefined, signal);
+            if (s.needsKey && !s.dek) {
+                if (cached && cached.version === s.version) {
+                    s.dek = cached.key;
+                    cached = undefined;
+                }
+                else {
+                    s = await this.call(bucket, key, off, length, true, signal);
+                }
+            }
+        }
+        finally {
+            cached?.key.fill(0);
+        }
+        if (s.staged) {
+            s.forget();
+            throw stagedError(key);
+        }
+        if (s.dek)
+            this.keys.put(bucket, key, s.version, s.dek);
+        return s;
+    }
+    /**
+     * Read sessions for many objects, signed 1,000 to a request (objects/read): a Session, or the error for an object
+     * that can't be read (each on its own; stagedError for one still in the old stage). Each Session holds its own key;
+     * the caller forgets it.
+     */
+    async sessions(bucket, keys, signal) {
+        const out = new Map();
+        const unique = [...new Set(keys)];
+        for (let i = 0; i < unique.length; i += READ_BATCH) {
+            const { data } = await this.client.call({
+                method: 'POST',
+                path: bucketPath(bucket) + '/objects/read',
+                json: { keys: unique.slice(i, i + READ_BATCH), include_keys: true },
+                mode: 'safe',
+                signal,
+            });
+            for (const item of data?.objects ?? []) {
+                const k = str(item.key);
+                if (item.error) {
+                    out.set(k, sessionError(k, item.error));
+                    continue;
+                }
+                let s;
+                try {
+                    s = new Session(bucket, item);
+                }
+                catch (err) {
+                    if (!(err instanceof DataIntegrityError))
+                        throw err;
+                    out.set(k, err);
+                    continue;
+                }
+                if (s.staged) {
+                    s.forget();
+                    out.set(k, stagedError(k));
+                    continue;
+                }
+                if (s.dek)
+                    this.keys.put(bucket, k, s.version, s.dek);
+                out.set(k, s);
+            }
+        }
+        for (const k of unique) {
+            if (!out.has(k))
+                out.set(k, new NotFoundError({ statusCode: 404, message: `${k}: missing from the read batch's answer`, code: 'object_not_found' }));
+        }
+        return out;
+    }
+    /** A later window of the same version, signed without the key. */
+    async window(s0, off, length, signal) {
+        const s = await this.call(s0.bucket, s0.key, off, length, false, signal);
+        if (s.version !== s0.version) {
+            s.forget();
+            throw new ObjectChangedError();
+        }
+        s.forget(); // never used: the read has its own copy (a server that sent one anyway gets it zeroed)
+        return s;
+    }
+    /** A signed GET, its headers in (the client's timeout), its body to read; Expired for a signature about to expire. */
+    async open(r, signal) {
+        if (!r.fresh())
+            throw new Expired();
+        signal?.throwIfAborted();
+        const { ctl, unlink } = linked(signal);
+        const ms = this.client.timeout;
+        const timer = ms > 0 ? setTimeout(() => ctl.abort(new ConnectionError(`no answer from the storage network in ${ms} ms`)), ms) : undefined;
+        try {
+            const response = await this.client.sendSigned({ method: 'GET', url: r.url, headers: r.headers, signal: ctl.signal });
+            return new Body(response, ctl, unlink, ms, signal);
+        }
+        catch (err) {
+            unlink();
+            if (signal?.aborted)
+                throw signal.reason;
+            throw err;
+        }
+        finally {
+            clearTimeout(timer);
+        }
+    }
+    // --- verified bytes ---------------------------------------------------------
+    /**
+     * The object's bytes [a, b), each verified before it is yielded; with check (a whole read), the object's SHA-256
+     * too, throwing ChecksumMismatchError after the last bytes.
+     */
+    async *plaintext(s, dek, a, b, check, signal) {
+        const checked = check && s.checkable;
+        if (!s.requests.length) {
+            if (s.size)
+                throw new DataIntegrityError(`${s.key}: the read session signed nothing`, 'session');
+            return;
+        }
+        if (s.packed || s.format === FORMAT_SERVER) {
+            const data = await this.whole(s, dek, signal);
+            if (checked) {
+                const got = await sha256Hex(data);
+                if (got !== s.sha256)
+                    throw new ChecksumMismatchError(`${s.key}: received ${got}, stored ${s.sha256}`);
+            }
+            if (b > a)
+                yield data.subarray(a, b);
+            return;
+        }
+        let chunks;
+        if (s.format === FORMAT_TWS1) {
+            if (!dek)
+                throw new DataIntegrityError(`${s.key}: the read session carried no key`, 'key');
+            chunks = this.tws1Blob(s, dek, a, b, signal);
+        }
+        else {
+            chunks = this.rawBlob(s, a, b, signal);
+        }
+        const h = checked ? new Sha256() : null;
+        for await (const c of chunks) {
+            h?.update(c);
+            yield c;
+        }
+        if (h) {
+            const got = h.hexDigest();
+            if (got !== s.sha256)
+                throw new ChecksumMismatchError(`${s.key}: received ${got}, stored ${s.sha256}`);
+        }
+    }
+    /** A packed object, its needle checked and decrypted whole; or a teepin-v1 object in its own blob, read whole and opened. */
+    async whole(s, dek, signal) {
+        const stored = s.packed ? await this.packed(s, signal) : await collect(this.rawBlob(s, 0, s.storedSize, signal));
+        let data;
+        if (s.format === FORMAT_TWS1 || s.format === FORMAT_SERVER) {
+            if (!dek)
+                throw new DataIntegrityError(`${s.key}: the read session carried no key`, 'key');
+            data = s.format === FORMAT_TWS1 ? await tws1.decrypt(dek, stored) : await openServerV1(dek, stored, s.ad);
+        }
+        else {
+            data = stored;
+        }
+        if (data.length !== s.size)
+            throw new DataIntegrityError(`${s.key}: ${data.length} bytes, not the ${s.size} stored`, 'size');
+        return data;
+    }
+    async packed(s0, signal) {
+        const tries = new Tries(this, s0, signal);
+        let cur = s0;
+        for (;;) {
+            try {
+                const r = cur.window;
+                const body = await this.open(r, signal);
+                let data;
+                try {
+                    data = await body.readExact(r.length);
+                }
+                finally {
+                    body.close();
+                }
+                if (data.length !== r.length)
+                    throw new Broken(`${data.length} of ${r.length} bytes`);
+                const stored = data.subarray(r.prefix);
+                await tws1.checkNeedle(data.subarray(0, r.prefix), tws1.objectIdBytes(s0.version), stored);
+                return stored;
+            }
+            catch (err) {
+                await tries.failed(err);
+                cur = await this.window(s0, 0, 0, signal);
+            }
+        }
+    }
+    async *tws1Blob(s0, dek, a, b, signal) {
+        const size = s0.size;
+        const n = tws1.segments(size);
+        const r = tws1.locate(size, a, b - a);
+        let seg = r.firstSegment;
+        const last = b <= a ? seg : Math.floor((b - 1) / tws1.SEGMENT_SIZE);
+        const [lastOff, lastLen] = tws1.segmentAt(size, last);
+        const end = lastOff + lastLen; // the stored end, exclusive
+        let skip = r.skip;
+        let left = r.length;
+        let keys = null;
+        let cap = DEFAULT_WINDOW;
+        const tries = new Tries(this, s0, signal);
+        let start = seg === 0 ? 0 : tws1.segmentAt(size, seg)[0];
+        let cur = s0.requests.length && s0.window.first === start ? s0 : null;
+        while (seg <= last) {
+            start = seg === 0 ? 0 : tws1.segmentAt(size, seg)[0];
+            let asked = 0;
+            try {
+                if (!cur) {
+                    asked = aligned(start, end, cap);
+                    cur = await this.window(s0, start, asked, signal);
+                }
+                const win = cur.window;
+                if (win.first !== start)
+                    throw new DataIntegrityError(`${s0.key}: a window signed from ${win.first}, not ${start}`, 'window');
+                if (asked && win.last - win.first + 1 < asked)
+                    cap = win.last - win.first + 1; // the server's window
+                if (!keys && start > 0)
+                    keys = await this.header(cur, dek, signal);
+                const body = await this.open(win, signal);
+                try {
+                    if (start === 0) {
+                        const head = await body.readExact(tws1.HEADER_SIZE);
+                        if (head.length < tws1.HEADER_SIZE)
+                            throw new Broken('the header broke off');
+                        if (!keys)
+                            keys = await tws1.openHeader(dek, head);
+                        else if (!constantTimeEqual(head, keys.header))
+                            throw new DataIntegrityError(`${s0.key}: the header changed`, 'header');
+                    }
+                    while (seg <= last) {
+                        const [soff, slen] = tws1.segmentAt(size, seg);
+                        if (soff + slen - 1 > win.last)
+                            break; // the window ends inside this segment: the next one starts with it
+                        const data = await body.readExact(slen);
+                        if (data.length < slen)
+                            throw new Broken(`segment ${seg} broke off`);
+                        if (!keys)
+                            throw new DataIntegrityError(`${s0.key}: no header to open segment ${seg} with`, 'header');
+                        const plain = await keys.open(seg, seg === n - 1, data);
+                        seg++;
+                        tries.progressed();
+                        const out = skip || left < plain.length ? plain.subarray(skip, skip + left) : plain;
+                        skip = 0;
+                        left -= out.length;
+                        if (out.length)
+                            yield out;
+                    }
+                }
+                finally {
+                    body.close();
+                }
+            }
+            catch (err) {
+                await tries.failed(err);
+            }
+            cur = null;
+        }
+    }
+    /** The object's keys from the header a later window's session signs first; its commitment is checked. */
+    async header(cur, dek, signal) {
+        const hr = cur.requests.length > 1 ? cur.requests[0] : null;
+        if (!hr || hr.first !== 0)
+            throw new DataIntegrityError(`${cur.key}: the read session didn't sign the header`, 'header');
+        const body = await this.open(hr, signal);
+        let head;
+        try {
+            head = await body.readExact(tws1.HEADER_SIZE);
+        }
+        finally {
+            body.close();
+        }
+        if (head.length < tws1.HEADER_SIZE)
+            throw new Broken('the header broke off');
+        return tws1.openHeader(dek, head);
+    }
+    /** Stored bytes [a, b) of an object in its own blob, as stored. */
+    async *rawBlob(s0, a, b, signal) {
+        let pos = a;
+        let cap = DEFAULT_WINDOW;
+        const tries = new Tries(this, s0, signal);
+        let cur = s0.requests.length && s0.window.first === a ? s0 : null;
+        while (pos < b) {
+            let asked = 0;
+            try {
+                if (!cur) {
+                    asked = Math.min(b - pos, cap);
+                    cur = await this.window(s0, pos, asked, signal);
+                }
+                const win = cur.window;
+                if (win.first !== pos)
+                    throw new DataIntegrityError(`${s0.key}: a window signed from ${win.first}, not ${pos}`, 'window');
+                if (asked && win.last - win.first + 1 < asked)
+                    cap = win.last - win.first + 1;
+                const body = await this.open(win, signal);
+                try {
+                    let want = Math.min(b, win.last + 1) - pos;
+                    while (want > 0) {
+                        const chunk = await body.read(Math.min(READ_CHUNK, want));
+                        if (!chunk.length)
+                            throw new Broken(`${want} bytes short`);
+                        pos += chunk.length;
+                        want -= chunk.length;
+                        tries.progressed();
+                        yield chunk;
+                    }
+                }
+                finally {
+                    body.close();
+                }
+            }
+            catch (err) {
+                await tries.failed(err);
+            }
+            cur = null;
+        }
+    }
+    // --- whole operations ---------------------------------------------------------
+    /** How a download splits: one range per server window (partSize may split finer), or one range for an object read whole. */
+    ranges(s, partSize) {
+        const size = s.size;
+        if (s.packed || !s.requests.length || s.format === FORMAT_SERVER || s.window.last + 1 >= s.storedSize)
+            return [[0, size]];
+        let stride = s.window.last - s.window.first + 1;
+        if (s.format === FORMAT_TWS1) {
+            const seg = tws1.SEGMENT_SIZE;
+            stride = Math.max(1, Math.floor((stride - tws1.HEADER_SIZE) / tws1.STORED_SEGMENT_SIZE)) * seg;
+            if (partSize > 0)
+                stride = Math.min(stride, Math.max(seg, Math.floor(partSize / seg) * seg));
+        }
+        else if (partSize > 0) {
+            stride = Math.min(stride, partSize);
+        }
+        const out = [];
+        for (let a = 0; a < size; a += stride)
+            out.push([a, Math.min(a + stride, size)]);
+        return out;
+    }
+    /**
+     * Writes the whole object to the target open makes (once per attempt, given the object's details): windows in
+     * parallel, each pinned to the first session's version. A SHA-256 mismatch is tried again once.
+     */
+    async download(bucket, key, open, p) {
+        let prog;
+        for (let attempt = 0;; attempt++) {
+            const s = await this.session(bucket, key, 0, 0, p.signal);
+            const dek = s.dek ? s.dek.slice() : null;
+            s.forget();
+            const progress = (prog ??= new Progress(s.size, p.onProgress));
+            try {
+                const target = open(s.object());
+                const ranges = this.ranges(s, p.partSize);
+                if (ranges.length === 1 || p.concurrency === 1) {
+                    await this.writeRange(s, dek, 0, s.size, p.verify, target, progress, p.signal);
+                    return s.object();
+                }
+                await pool(p.concurrency, ranges, p.signal, (r, signal) => this.writeRange(s, dek, r[0], r[1], false, target, progress, signal));
+                if (p.verify && s.checkable && target.sha256) {
+                    const got = await target.sha256(s.size);
+                    if (got !== s.sha256)
+                        throw new ChecksumMismatchError(`${key}: received ${got}, stored ${s.sha256}`);
+                }
+                return s.object();
+            }
+            catch (err) {
+                if (!(err instanceof ChecksumMismatchError) || attempt > 0)
+                    throw err;
+            }
+            finally {
+                dek?.fill(0);
+            }
+        }
+    }
+    async writeRange(s, dek, a, b, check, target, prog, signal) {
+        let pos = a;
+        for await (const c of this.plaintext(s, dek, a, b, check, signal)) {
+            await target.write(pos, c);
+            pos += c.length;
+            prog.add(c.length);
+        }
+    }
+    /**
+     * The first part of getObject: the session, checked, and the range [a, b) to read (start and end inclusive, end
+     * undefined for to the end); the bytes come from body.
+     */
+    async get(bucket, key, start, end, ifMatch, signal) {
+        const ranged = start > 0 || end !== undefined;
+        // A range signs a little at first (its window comes later); a whole read signs a window.
+        const s = await this.session(bucket, key, 0, ranged ? tws1.HEADER_SIZE + tws1.STORED_SEGMENT_SIZE : 0, signal);
+        if (ifMatch && s.etag !== unquote(ifMatch)) {
+            s.forget();
+            throw new ObjectChangedError();
+        }
+        const b = end === undefined ? s.size : Math.min(end + 1, s.size);
+        if (start < 0 || (ranged && start >= s.size) || start > b) {
+            s.forget();
+            throw apiError({ statusCode: 416, message: `${key}: bytes ${start}- are past the object's ${s.size} bytes`, code: 'invalid_range' });
+        }
+        const dek = s.dek ? s.dek.slice() : null;
+        s.forget();
+        return { session: s, dek, a: start, b, ranged };
+    }
+    /** The verified bytes [a, b); the key copy is zeroed at the end, or when the reader stops early. */
+    async *body(s, dek, a, b, check, signal) {
+        try {
+            yield* this.plaintext(s, dek, a, b, check, signal);
+        }
+        finally {
+            dek?.fill(0);
+        }
+    }
+    /**
+     * The first part of openObject: the session, the key copy, the block (one window, or the whole object) and the
+     * alignment of a jump.
+     */
+    async openFile(bucket, key, signal) {
+        const s = await this.session(bucket, key, 0, 0, signal);
+        const dek = s.dek ? s.dek.slice() : null;
+        s.forget();
+        return { session: s, dek, ...this.layout(s) };
+    }
+    /** How an ObjectFile reads s: its block (one window, or the whole object) and the alignment of a jump. */
+    layout(s) {
+        const block = this.ranges(s, 0)[0][1] || 1;
+        const align = s.packed || s.format === FORMAT_SERVER ? Math.max(1, s.size) : tws1.SEGMENT_SIZE;
+        return { block, align };
+    }
+    /** The verified bytes [a, b), joined; the whole object's SHA-256 is checked when that is what's asked for. */
+    fetch(s, dek, a, b, signal) {
+        return collect(this.plaintext(s, dek, a, b, a === 0 && b === s.size, signal));
+    }
+}
+// --- share links ------------------------------------------------------------------
+/** The route that opens a share link: a read session for the token, with no sign-in (section 26.2). */
+export const LINK_READ_PATH = '/v1/storage/links/read';
+/**
+ * Reads through a share link (section 26.3): the same engine and checks as DirectReads, with the link's read sessions
+ * (POST /v1/storage/links/read) in place of the authenticated ones. Every session carries the data key, so none is
+ * cached (the client's keyCacheTtl is 0), and every session after the first must be of the version the link first
+ * opened: ObjectChangedError otherwise. The bucket and key the engine passes around are unused: the token names the
+ * object.
+ *
+ * The first session takes the link's token. Each answer brings a continuation, and every later session takes the
+ * newest one instead: it reads only the version first opened (the server answers 412 for a replaced object, which is
+ * ObjectChangedError here), lasts 30 minutes from its issue, and never past the link's expiry plus 24 hours, so a
+ * download that began while the link was valid can finish after it expires. A continuation left idle too long is
+ * refused; the link's token is then tried once more, which opens only while the link itself is valid.
+ */
+export class LinkReads extends DirectReads {
+    token;
+    /** The version the link first opened (set by openLink); '' until then. */
+    version = '';
+    /** From the link's answers: how the link is meant to be offered, and the name to save the object as. */
+    disposition = '';
+    fileName = '';
+    /** The newest continuation, and when it stops working (ms); '' until the first answer. */
+    continuation = '';
+    continuationEnds = 0;
+    constructor(client, token) {
+        super(client);
+        this.token = token;
+    }
+    /** One read session for the link, retried by the client as a safe call; the version pinned once it is known. */
+    async call(bucket, _key, off, length, _includeKey, signal) {
+        const cont = this.continuation;
+        let d;
+        try {
+            d = await this.openWith(cont ? { continuation: cont } : { token: this.token }, off, length, signal);
+        }
+        catch (err) {
+            if (!cont)
+                throw err;
+            if (err instanceof APIError && err.statusCode === 412 && err.code === 'precondition_failed')
+                throw new ObjectChangedError();
+            if (!(err instanceof InvalidLinkError))
+                throw err;
+            d = await this.openWith({ token: this.token }, off, length, signal);
+        }
+        this.disposition = str(d.disposition) || this.disposition;
+        this.fileName = str(d.file_name) || this.fileName;
+        this.keep(d.continuation);
+        const s = new Session(bucket, d);
+        if (this.version && s.version !== this.version) {
+            s.forget();
+            throw new ObjectChangedError();
+        }
+        return s;
+    }
+    /** POST /v1/storage/links/read with the link's token or a continuation. */
+    async openWith(cred, off, length, signal) {
+        const { data } = await this.client.call({
+            method: 'POST',
+            path: LINK_READ_PATH,
+            json: { ...cred, stored_offset: off, stored_length: length },
+            mode: 'safe',
+            signal,
+        });
+        return data ?? {};
+    }
+    /** Keeps an answer's continuation when it lasts at least as long as the one held (windows may answer out of order). */
+    keep(c) {
+        if (!c || typeof c !== 'object')
+            return;
+        const token = str(c.token);
+        const ends = Date.parse(str(c.expires_at));
+        if (!token || Number.isNaN(ends) || ends < this.continuationEnds)
+            return;
+        this.continuation = token;
+        this.continuationEnds = ends;
+    }
+    /** A read's first session, always with its key (nothing is cached); an object still in the old stage throws stagedError. */
+    async session(bucket, key, off = 0, length = 0, signal) {
+        const s = await this.call(bucket, key, off, length, true, signal);
+        if (s.staged) {
+            s.forget();
+            throw stagedError(this.fileName || s.key || 'the linked object');
+        }
+        return s;
+    }
+}
+/** Everything chunks yields, joined. */
+export async function collect(chunks) {
+    const parts = [];
+    for await (const c of chunks)
+        parts.push(c);
+    return parts.length === 1 ? parts[0] : concat(parts);
+}
+/**
+ * Runs fn for every item, at most n at once. The first failure stops the others (their signal aborts), and every
+ * worker is waited for before it is thrown, so nothing is left running; an abort of signal throws its reason.
+ */
+async function pool(n, items, signal, fn) {
+    const { ctl, unlink } = linked(signal);
+    let next = 0;
+    let failed = false;
+    let failure;
+    const worker = async () => {
+        while (!failed && next < items.length && !ctl.signal.aborted) {
+            const item = items[next++];
+            try {
+                await fn(item, ctl.signal);
+            }
+            catch (err) {
+                if (!failed) {
+                    failed = true;
+                    failure = err;
+                }
+                ctl.abort(err);
+            }
+        }
+    };
+    try {
+        await Promise.all(Array.from({ length: Math.max(1, Math.min(n, items.length)) }, worker));
+    }
+    finally {
+        unlink();
+    }
+    if (signal?.aborted)
+        throw signal.reason;
+    if (failed)
+        throw failure;
+}
+/**
+ * A ReadableStream of a read's verified chunks, made only as they are asked for. An abort of signal, or a cancel, ends
+ * it at once: the stream errors with the reason, the read's requests stop, and release runs (it zeroes the read's key
+ * copy), as it does when the stream ends.
+ */
+export function readable(chunks, signal, release) {
+    const { ctl, unlink } = linked(signal);
+    let it;
+    let finished = false;
+    const end = () => {
+        if (finished)
+            return;
+        finished = true;
+        unlink();
+        release?.();
+        void it?.return(undefined).catch(() => undefined);
+    };
+    return new ReadableStream({
+        start(c) {
+            const onAbort = () => {
+                try {
+                    c.error(ctl.signal.reason);
+                }
+                catch {
+                    // already closed
+                }
+                end();
+            };
+            if (ctl.signal.aborted)
+                onAbort();
+            else
+                ctl.signal.addEventListener('abort', onAbort, { once: true });
+        },
+        async pull(c) {
+            it ??= chunks(ctl.signal);
+            try {
+                const r = await it.next();
+                if (r.done) {
+                    end();
+                    c.close();
+                }
+                else {
+                    c.enqueue(r.value);
+                }
+            }
+            catch (err) {
+                end();
+                c.error(ctl.signal.aborted ? ctl.signal.reason : err);
+            }
+        },
+        cancel(reason) {
+            ctl.abort(reason ?? new TeepinError('the read was cancelled'));
+            end();
+        },
+    }, { highWaterMark: 0 });
+}
+/** A stream's bytes, joined; its error, as it is. */
+export async function drain(body) {
+    const reader = body.getReader();
+    const parts = [];
+    try {
+        for (;;) {
+            const { done, value } = await reader.read();
+            if (done)
+                break;
+            parts.push(value);
+        }
+    }
+    finally {
+        reader.releaseLock();
+    }
+    return concat(parts);
+}
+const closedError = () => new TeepinError('the object file is closed');
+/**
+ * An object open for reading at any offset (TEEPIN-STORAGE-DESIGN.md section 22.5): read(offset, length), size, info
+ * and close().
+ *
+ * Reading straight on (each read starting where the last ended) fetches a block at a time (one window, 64 MiB on the
+ * storage network) and the next prefetch blocks ahead, each signed as it is fetched; a read somewhere else fetches
+ * only what it needs, in whole segments. Up to prefetch + 2 blocks are held. Every byte is verified before it is read,
+ * and every block is read from the version first opened: ObjectChangedError if the object is replaced. Close it when
+ * done: that stops its fetches and zeroes its copy of the data key.
+ */
+export class ObjectFile {
+    /** The object's size in bytes. */
+    size;
+    /** The object's details, as headObject gives them. */
+    info;
+    fetch;
+    block;
+    align;
+    prefetch;
+    onClose;
+    signal;
+    ctl;
+    unlink;
+    blocks = new Map(); // oldest first
+    end = 0; // where the last read ended: reading on from here is reading straight on
+    isClosed = false;
+    constructor(fetch, size, block, align, info, prefetch = 2, onClose, signal) {
+        this.fetch = fetch;
+        this.size = size;
+        this.block = Math.max(1, block);
+        this.align = Math.max(1, align);
+        this.prefetch = Math.max(0, Math.floor(prefetch) || 0);
+        this.info = info;
+        this.onClose = onClose;
+        this.signal = signal;
+        const { ctl, unlink } = linked(signal);
+        this.ctl = ctl;
+        this.unlink = unlink;
+    }
+    get closed() {
+        return this.isClosed;
+    }
+    /** Up to length bytes from offset: fewer only at the object's end, none past it. */
+    async read(offset, length) {
+        this.checkOpen();
+        if (!isInt(offset) || !isInt(length) || offset < 0 || length < 0) {
+            throw new TeepinError(`read(${offset}, ${length}): the offset and length must be whole numbers, 0 or more`);
+        }
+        const n = Math.min(length, Math.max(0, this.size - offset));
+        if (n === 0)
+            return new Uint8Array(0);
+        try {
+            const straight = offset === this.end;
+            // A jump fetches only what it reads, unless the object is read whole anyway (packed): then its one block is
+            // cached like any other.
+            const whole = this.align >= this.block;
+            let data;
+            if (!straight && !whole && n < this.block / 2 && !this.blocks.has(Math.floor(offset / this.block))) {
+                data = await this.some(offset, n);
+            }
+            else {
+                const out = [];
+                let pos = offset;
+                let left = n;
+                while (left > 0) {
+                    const i = Math.floor(pos / this.block);
+                    const blk = await this.get(i);
+                    const off = pos - i * this.block;
+                    const piece = blk.subarray(off, off + left);
+                    if (!piece.length)
+                        throw new DataIntegrityError('the object is shorter than its size', 'truncated');
+                    out.push(piece);
+                    pos += piece.length;
+                    left -= piece.length;
+                }
+                this.ahead(Math.floor(pos / this.block));
+                data = out.length === 1 ? out[0].slice() : concat(out);
+            }
+            this.checkOpen();
+            this.end = offset + data.length;
+            return data;
+        }
+        catch (err) {
+            if (this.signal?.aborted)
+                throw this.signal.reason;
+            if (this.isClosed)
+                throw closedError();
+            throw err;
+        }
+    }
+    /** Stops every fetch and zeroes this file's copy of the data key. Reads after it fail. */
+    close() {
+        if (this.isClosed)
+            return;
+        this.isClosed = true;
+        this.ctl.abort(closedError());
+        this.blocks.clear();
+        this.unlink();
+        this.onClose?.();
+    }
+    checkOpen() {
+        if (this.signal?.aborted)
+            throw this.signal.reason;
+        if (this.isClosed)
+            throw closedError();
+    }
+    /** Block i's fetch, started if it isn't, and made the newest; the oldest past the bound are dropped. */
+    submit(i) {
+        let e = this.blocks.get(i);
+        if (e) {
+            this.blocks.delete(i);
+        }
+        else {
+            const a = i * this.block;
+            const b = Math.min(a + this.block, this.size);
+            const { ctl, unlink } = linked(this.ctl.signal);
+            const promise = (async () => {
+                try {
+                    return await this.fetch(a, b, ctl.signal);
+                }
+                finally {
+                    unlink();
+                }
+            })();
+            const entry = { promise, ctl, readers: 0 };
+            // A failed block is fetched again by the next read that needs it (and a prefetch nobody waits for fails quietly).
+            promise.catch(() => {
+                if (this.blocks.get(i) === entry)
+                    this.blocks.delete(i);
+            });
+            e = entry;
+        }
+        this.blocks.set(i, e);
+        while (this.blocks.size > this.prefetch + 2) {
+            const [oldest, old] = this.blocks.entries().next().value;
+            this.blocks.delete(oldest);
+            if (old.readers === 0)
+                old.ctl.abort(new TeepinError('dropped from the read-ahead'));
+        }
+        return e;
+    }
+    async get(i) {
+        const e = this.submit(i);
+        e.readers++;
+        try {
+            return await e.promise;
+        }
+        finally {
+            e.readers--;
+        }
+    }
+    ahead(i) {
+        const last = Math.floor((this.size - 1) / this.block);
+        for (let j = i; j <= Math.min(i + this.prefetch, last); j++)
+            if (j * this.block < this.size)
+                this.submit(j);
+    }
+    /** n bytes from pos, fetched alone, whole segments only. */
+    async some(pos, n) {
+        const a = Math.floor(pos / this.align) * this.align;
+        const b = Math.min(this.size, Math.ceil((pos + n) / this.align) * this.align);
+        const data = await this.fetch(a, b, this.ctl.signal);
+        return data.slice(pos - a, pos - a + n);
+    }
+}
+/** The error a batch read gives one object, as the single route would throw it. */
+function sessionError(key, err) {
+    const code = str(err.code);
+    const message = `${key}: ${str(err.error) || code.replaceAll('_', ' ')}`;
+    if (code === 'key_erased')
+        return new KeyErasedError({ statusCode: 410, message, code });
+    if (code === 'object_not_found')
+        return new NotFoundError({ statusCode: 404, message, code });
+    return new APIError({ statusCode: 500, message, code });
+}
+/** Stored bytes to ask for from start: whole segments within cap (the header too from 0), at most to end. */
+function aligned(start, end, cap) {
+    let want;
+    if (start === 0) {
+        const n = Math.max(1, Math.floor((cap - tws1.HEADER_SIZE) / tws1.STORED_SEGMENT_SIZE));
+        want = tws1.HEADER_SIZE + n * tws1.STORED_SEGMENT_SIZE;
+    }
+    else {
+        want = Math.max(1, Math.floor(cap / tws1.STORED_SEGMENT_SIZE)) * tws1.STORED_SEGMENT_SIZE;
+    }
+    return Math.min(end - start, want);
+}
+//# sourceMappingURL=reads.js.map