@teepin/sdk 0.2.1 → 0.3.0-rc.1

package/dist/cjs/node/downloads.js

@@ -0,0 +1,835 @@
+"use strict";
+// Copyright 2026 TEEPIN Project
+// Licensed under the Apache License, Version 2.0
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.caseInsensitive = exports.downloadPrefix = exports.downloadFiles = exports.testHooks = void 0;
+// Batch downloads to a folder: downloadFiles and downloadPrefix (TEEPIN-STORAGE-DESIGN.md sections 19.15, 22.5 and
+// 24.4), a port of teepin-python's _downloads.py with the same rules.
+//
+// Read sessions are signed 1,000 objects to a request (objects/read), and a large object's later windows one at a
+// time. The work is a pool of pieces, one per object or per window of a large object, concurrency at a time:
+//
+// - a piece's bytes are verified as they arrive and written into <name>.teepin-part beside the target, fsynced, then
+//   journaled;
+// - an object whose pieces are all written is checked against its SHA-256 (read back from the part file), then renamed
+//   into place, so a target is never half written;
+// - a run stopped by a passing error (the network, storage, a revoked key), by an abort, or by the process ending keeps
+//   its journal and part files: running the same download again goes on from the written pieces of each object whose
+//   version hasn't changed.
+//
+// skipExisting decides from the object's details before anything is signed (signatures are metered): the file there
+// must have the object's size and plaintext SHA-256, never its ETag.
+//
+// Paths (src/direct/downloads-plan.ts has the rules on names): no link under the destination may carry a write out of
+// it. That's checked before anything is signed, and again before a part file is made and before it's renamed. A part
+// file is only ever new (never a name already there, which could be a link into another file) or one an earlier run
+// made with no other name, and it's written only through a handle that is still that file, so a link or a file put in
+// its place later is never written through.
+//
+// The journal is the state directory's downloads/<run-id>/: run.json, events.jsonl (appended, each event fsynced before
+// the action that needs it) and lock (made with O_EXCL, holding the host and process id; a lock whose process is gone
+// is taken over). A run adopts the unfinished objects of earlier runs at its paths, and what's left of an earlier run
+// is rewritten whole (a temporary file renamed over it), or the run removed once nothing is left.
+const node_crypto_1 = require("node:crypto");
+const node_fs_1 = require("node:fs");
+const promises_1 = require("node:fs/promises");
+const node_os_1 = require("node:os");
+const node_path_1 = require("node:path");
+const reads_js_1 = require("../direct/reads.js");
+const downloads_plan_js_1 = require("../direct/downloads-plan.js");
+const errors_js_1 = require("../errors.js");
+const journal_js_1 = require("./journal.js");
+const transfer_js_1 = require("../transfer.js");
+/** For tests only (a test checks that nothing under src sets it): called once each journal write is durable. */
+exports.testHooks = {};
+const rangeId = (r) => `${r[0]}-${r[1]}`;
+const codeOf = (err) => (err instanceof Error && 'code' in err ? String(err.code) : '');
+const missing = (err) => codeOf(err) === 'ENOENT' || codeOf(err) === 'ENOTDIR';
+/** O_NOFOLLOW where the OS has it (not Windows: there, a handle's identity check stops a link). */
+const NOFOLLOW = node_fs_1.constants.O_NOFOLLOW ?? 0;
+const READ_CHUNK = 2 ** 20;
+/**
+ * Downloads many objects, each to destDir joined with its key (a/b.jpg to destDir/a/b.jpg), and returns one
+ * DownloadResult per key, in order (a key given twice is one). One object's failure never fails another.
+ *
+ * Read sessions are signed 1,000 objects to a request. Up to concurrency objects, or windows of a large object, are
+ * fetched at once, each verified before it is written to <name>.teepin-part beside its target; an object is checked
+ * against its SHA-256 and renamed into place only when whole.
+ *
+ * A download stopped by a passing error (the network, the storage network unavailable, a revoked key), by an abort or
+ * by the process ending is pending: its part file and the run's journal stay, and running the same download again
+ * goes on from what was written, unless the object has changed since.
+ *
+ * A key that isn't a safe path under destDir fails (UnsafePathError): "..", an absolute path, a name Windows can't
+ * have (on every OS), a link under destDir leading out of it, or two keys for one file (names that differ only by case,
+ * where names ignore case). A key ending in "/" (a folder marker) is skipped.
+ */
+function downloadFiles(storage, bucket, keys, destDir, opts = {}) {
+    return run(storage, bucket, keys.map((k) => [k, k]), destDir, new Map(), opts);
+}
+exports.downloadFiles = downloadFiles;
+/**
+ * Downloads every object under prefix (all of them for ""), each to destDir joined with its key after the prefix, as
+ * downloadFiles does. With skipExisting, the listing's size and SHA-256 decide, so a file already there costs nothing
+ * more.
+ */
+async function downloadPrefix(storage, bucket, prefix, destDir, opts = {}) {
+    const objs = [];
+    try {
+        opts.signal?.throwIfAborted();
+        for await (const o of storage.objects(bucket, prefix, opts.signal))
+            objs.push(o);
+    }
+    catch (err) {
+        if (opts.signal?.aborted)
+            throw opts.signal.reason;
+        throw err;
+    }
+    const pairs = objs.map((o) => [o.key, o.key.slice(prefix.length).replace(/^\/+/, '')]);
+    return run(storage, bucket, pairs, destDir, new Map(objs.map((o) => [o.key, o])), opts);
+}
+exports.downloadPrefix = downloadPrefix;
+async function run(storage, bucket, pairs, destDir, details, opts) {
+    const signal = opts.signal;
+    let batch;
+    try {
+        signal?.throwIfAborted();
+        const root = (0, node_path_1.resolve)(destDir);
+        const planned = await (0, downloads_plan_js_1.plan)(pairs, {
+            windows: process.platform === 'win32',
+            insensitive: await caseInsensitive(root),
+            target: (parts, rel) => targetPath(root, parts, rel),
+            shown: (rel) => root + node_path_1.sep + rel,
+        });
+        signal?.throwIfAborted();
+        batch = new BatchDownload(storage, bucket, root, details, opts);
+        await batch.go(planned.entries.filter((e) => !e.result));
+        return batch.output(planned.entries, planned.collisions);
+    }
+    catch (err) {
+        if (signal?.aborted)
+            throw signal.reason; // the abort's reason wins, whatever it interrupted
+        throw err;
+    }
+    finally {
+        await batch?.end();
+    }
+}
+/** One object being downloaded to its path. */
+class Target {
+    entry;
+    s;
+    dek;
+    ranges;
+    part;
+    done = new Set();
+    /** The part file, once made or adopted. */
+    id;
+    error;
+    resumed = false;
+    saved = false;
+    constructor(entry, s, 
+    /** This download's own copy of the data key, zeroed when the run ends. */
+    dek, ranges) {
+        this.entry = entry;
+        this.s = s;
+        this.dek = dek;
+        this.ranges = ranges;
+        this.part = entry.path + downloads_plan_js_1.PART_SUFFIX;
+    }
+    get key() {
+        return this.entry.key;
+    }
+    get path() {
+        return this.entry.path;
+    }
+}
+class Progress {
+    total;
+    fn;
+    done = 0;
+    constructor(total, fn) {
+        this.total = total;
+        this.fn = fn;
+    }
+    add(n) {
+        if (!n)
+            return;
+        this.done += n;
+        this.fn?.(this.done, this.total);
+    }
+}
+/** One downloadFiles or downloadPrefix call. */
+class BatchDownload {
+    storage;
+    bucket;
+    root;
+    details;
+    opts;
+    reads;
+    stateDir;
+    signal;
+    concurrency;
+    results = new Map();
+    targets = [];
+    journal = null;
+    prog = new Progress(0);
+    /** The error that stopped the run (a revoked key, say): what's left stays pending. */
+    stopError;
+    /** The run went to its end (not stopped by an abort or an error thrown out of it). */
+    ended = false;
+    constructor(storage, bucket, root, details, opts) {
+        this.storage = storage;
+        this.bucket = bucket;
+        this.root = root;
+        this.details = details;
+        this.opts = opts;
+        this.reads = storage['reads']; // the storage service's own, so read sessions share its key cache
+        this.stateDir = storage.client.stateDir || defaultStateDir();
+        this.signal = opts.signal;
+        this.concurrency = opts.concurrency && opts.concurrency > 0 ? Math.floor(opts.concurrency) : transfer_js_1.DEFAULT_CONCURRENCY;
+    }
+    async go(entries) {
+        if (this.opts.journal ?? true)
+            this.journal = await RunJournal.create(this.stateDir, this.bucket);
+        const todo = await this.skip(entries);
+        const adopted = this.journal ? await this.adopt(new Set(todo.map((e) => e.path))) : new Map();
+        let sessions = new Map();
+        try {
+            if (todo.length)
+                sessions = await this.reads.sessions(this.bucket, todo.map((e) => e.key), this.signal);
+            for (const entry of todo) {
+                // Every key has a session or its error (an object still in the old stage: stagedError).
+                const s = sessions.get(entry.key);
+                if (s instanceof reads_js_1.Session)
+                    await this.target(entry, s, adopted.get(entry.path));
+                else
+                    this.results.set(entry, { key: entry.key, path: entry.path, status: 'failed', error: s, resumed: false });
+            }
+            await this.parts();
+            await this.pieces();
+        }
+        finally {
+            for (const t of this.targets)
+                t.dek?.fill(0);
+            for (const s of sessions.values())
+                if (s instanceof reads_js_1.Session)
+                    s.forget();
+        }
+    }
+    output(entries, collisions) {
+        const out = entries.map((e) => {
+            const r = e.result ?? this.results.get(e);
+            if (!r)
+                throw new errors_js_1.TeepinError(`${e.key}: the download ended without a result`);
+            return r;
+        });
+        this.ended = true;
+        return [...out, ...collisions];
+    }
+    /** Closes the run, always: removed when nothing is left to go on with, else kept (unlocked) for the next run. */
+    async end() {
+        const run = this.journal;
+        if (!run)
+            return;
+        const pending = [...this.results.values()].some((r) => r.status === 'pending');
+        if (pending || !this.ended)
+            await run.release();
+        else
+            await run.remove().catch(() => run.release()); // a run that can't be removed is removed by the next one
+    }
+    /** What's left after skipExisting, decided before anything is signed. */
+    async skip(entries) {
+        if (!this.opts.skipExisting)
+            return [...entries];
+        const todo = [];
+        for (const entry of entries) {
+            if (await isFile(entry.path)) {
+                let obj = this.details.get(entry.key);
+                if (!obj) {
+                    try {
+                        obj = await this.storage.statObject(this.bucket, entry.key, this.signal);
+                    }
+                    catch (err) {
+                        if (!(err instanceof errors_js_1.NotFoundError))
+                            throw err;
+                        this.results.set(entry, { key: entry.key, path: entry.path, status: 'failed', error: err, resumed: false });
+                        continue;
+                    }
+                }
+                if (await sameFile(entry.path, obj, this.signal)) {
+                    this.results.set(entry, { key: entry.key, path: entry.path, status: 'skipped', object: obj, resumed: false });
+                    continue;
+                }
+            }
+            todo.push(entry);
+        }
+        return todo;
+    }
+    /**
+     * The object's target: its path checked again, its folder made, and its earlier run's part file adopted when it's
+     * still this version's and only this run's to write. Nothing is written yet.
+     */
+    async target(entry, s, prior) {
+        try {
+            await checkInside(this.root, entry.path); // again, just before anything is written: links can appear
+            await (0, promises_1.mkdir)((0, node_path_1.dirname)(entry.path), { recursive: true });
+        }
+        catch (err) {
+            s.forget();
+            this.results.set(entry, { key: entry.key, path: entry.path, status: 'failed', error: err, resumed: false });
+            return;
+        }
+        const dek = s.dek ? s.dek.slice() : null;
+        s.forget();
+        const t = new Target(entry, s, dek, this.reads.ranges(s, 0));
+        if (prior && prior.version === s.version && prior.size === s.size) {
+            t.id = await ownFile(t.part, s.size);
+            if (t.id) {
+                for (const r of t.ranges)
+                    if (prior.ranges.has(rangeId(r)))
+                        t.done.add(rangeId(r));
+                t.resumed = t.done.size > 0;
+            }
+        }
+        this.targets.push(t);
+    }
+    /**
+     * Journals every target, then makes the part files of those not adopted. Each is new, never a name already there:
+     * writing into an old name could write through a link (hard or symbolic) into another file.
+     */
+    async parts() {
+        await this.journal?.append(this.targets.flatMap((t) => [
+            { e: 'object', path: t.path, key: t.key, version: t.s.version, size: t.s.size },
+            ...t.ranges.filter((r) => t.done.has(rangeId(r))).map((r) => ({ e: 'range', path: t.path, a: r[0], b: r[1] })),
+        ]));
+        for (const t of [...this.targets]) {
+            if (t.id)
+                continue;
+            try {
+                await (0, promises_1.rm)(t.part, { force: true });
+                const fh = await (0, promises_1.open)(t.part, 'wx');
+                try {
+                    await fh.truncate(t.s.size);
+                    t.id = identity(await fh.stat({ bigint: true }));
+                }
+                finally {
+                    await fh.close();
+                }
+            }
+            catch (err) {
+                this.targets.splice(this.targets.indexOf(t), 1);
+                t.dek?.fill(0);
+                this.results.set(t.entry, { key: t.key, path: t.path, status: 'failed', error: err, resumed: false });
+            }
+        }
+    }
+    async pieces() {
+        const targets = this.targets;
+        this.prog = new Progress(targets.reduce((n, t) => n + t.s.size, 0), this.opts.onProgress);
+        for (const t of targets)
+            this.prog.add(t.ranges.reduce((n, r) => n + (t.done.has(rangeId(r)) ? r[1] - r[0] : 0), 0));
+        const work = [];
+        for (const t of targets) {
+            if (t.done.size === t.ranges.length)
+                work.push([t, null]); // every piece written before a stop: finish it
+            for (const r of t.ranges)
+                if (!t.done.has(rangeId(r)))
+                    work.push([t, r]);
+        }
+        await pool(this.concurrency, work, this.signal, ([t, r]) => this.piece(t, r));
+        for (const t of targets)
+            this.results.set(t.entry, await this.result(t));
+    }
+    /** One piece: never throws, its error is recorded on its object (an abort ends the pool). */
+    async piece(t, r) {
+        if (this.stopError !== undefined || t.error !== undefined || this.signal?.aborted)
+            return;
+        try {
+            if (r) {
+                await this.write(t, r);
+                await this.journal?.append([{ e: 'range', path: t.path, a: r[0], b: r[1] }]);
+                t.done.add(rangeId(r));
+                if (t.done.size < t.ranges.length)
+                    return;
+            }
+            await this.finish(t);
+        }
+        catch (err) {
+            if (t.error === undefined)
+                t.error = err;
+            if ((0, downloads_plan_js_1.stopsRun)(err))
+                this.stopError ??= err;
+        }
+    }
+    /** The object's bytes [a, b), each verified before it's written, then fsynced. */
+    async write(t, [a, b]) {
+        const fh = await openOwn(t, true);
+        try {
+            let pos = a;
+            for await (const c of this.reads.plaintext(t.s, t.dek, a, b, t.ranges.length === 1, this.signal)) {
+                await writeAt(fh, c, pos);
+                pos += c.length;
+                this.prog.add(c.length);
+            }
+            if (pos !== b)
+                throw new errors_js_1.DataIntegrityError(`${t.key}: ${pos - a} bytes of the ${b - a} from ${a}`, 'truncated');
+            await fh.sync();
+        }
+        finally {
+            await fh.close();
+        }
+    }
+    /** Every piece written: checked whole, then renamed into place, with the object's upload time. */
+    async finish(t) {
+        if (t.ranges.length > 1 && t.s.checkable) {
+            const fh = await openOwn(t, false);
+            let got;
+            try {
+                got = await sha256Of(fh, this.signal);
+            }
+            finally {
+                await fh.close();
+            }
+            if (got !== t.s.sha256)
+                throw new errors_js_1.ChecksumMismatchError(`${t.key}: received ${got}, stored ${t.s.sha256}`);
+        }
+        await checkInside(this.root, t.path); // and again before the rename
+        await checkOwn(t);
+        await (0, journal_js_1.renameOver)(t.part, t.path); // on Windows, waits a moment for another program to let go of the target
+        t.saved = true;
+        const when = t.s.uploadedAt;
+        if (when)
+            await (0, promises_1.lutimes)(t.path, when, when).catch(() => undefined);
+        await this.journal?.append([{ e: 'saved', path: t.path }]);
+    }
+    async result(t) {
+        const base = { key: t.key, path: t.path, resumed: t.resumed };
+        if (t.saved)
+            return { ...base, status: 'saved', object: t.s.object() };
+        const error = t.error ?? this.stopError;
+        if (error === undefined || (0, downloads_plan_js_1.passing)(error))
+            return { ...base, status: 'pending', error };
+        // Final: nothing to go on from. The part file is removed only while no link leads its path out of the destination.
+        await checkInside(this.root, t.path)
+            .then(() => (0, promises_1.rm)(t.part, { force: true }))
+            .catch(() => undefined);
+        await this.journal?.append([{ e: 'failed', path: t.path, error: String(error) }]).catch(() => undefined);
+        return { ...base, status: 'failed', error };
+    }
+    /**
+     * Earlier runs' unfinished objects at these paths: their version, size and written pieces, moved into this run's
+     * journal. Each is taken out of its run's journal first, so no two journals ever claim one part file's pieces (a stop
+     * in between loses them, and the object starts again). A run left with nothing unfinished is removed.
+     */
+    async adopt(paths) {
+        const out = new Map();
+        const own = this.journal;
+        if (!own)
+            return out;
+        for (const id of await runIds(this.stateDir)) {
+            if (id === own.id)
+                continue;
+            const other = new RunJournal(this.stateDir, id);
+            if (!(await takeLock(other.lock)))
+                continue; // another process is working on it
+            const taken = [];
+            try {
+                const entries = replay(await (0, promises_1.readFile)(other.events, 'utf8').catch((err) => (missing(err) ? '' : Promise.reject(err))));
+                const left = [];
+                for (const [path, e] of entries) {
+                    if (e.state !== 'open')
+                        continue;
+                    if (paths.has(path) && !out.has(path))
+                        taken.push([path, e]);
+                    else
+                        left.push([path, e]);
+                }
+                if (!left.length) {
+                    await other.remove();
+                }
+                else {
+                    if (taken.length)
+                        await (0, journal_js_1.writeAtomic)(other.events, left.flatMap(([path, e]) => eventsOf(path, e)).map(line).join(''));
+                    await releaseLock(other.lock);
+                }
+            }
+            catch {
+                await releaseLock(other.lock); // unreadable, or not rewritten: left as it was, nothing taken
+                continue;
+            }
+            for (const [path, e] of taken)
+                out.set(path, { version: e.version, size: e.size, ranges: e.ranges });
+            await own.append(taken.flatMap(([path, e]) => eventsOf(path, e)));
+        }
+        return out;
+    }
+}
+/**
+ * Runs fn for each item, at most n at once, until signal aborts; fn never throws. Every worker is waited for, so nothing
+ * is left running; then an abort throws its reason.
+ */
+async function pool(n, items, signal, fn) {
+    let next = 0;
+    const worker = async () => {
+        while (next < items.length && !signal?.aborted)
+            await fn(items[next++]);
+    };
+    await Promise.all(Array.from({ length: Math.max(1, Math.min(n, items.length)) }, worker));
+    signal?.throwIfAborted();
+}
+// --- files ----------------------------------------------------------------------------
+async function writeAt(fh, data, pos) {
+    for (let done = 0; done < data.length;)
+        done += (await fh.write(data, done, data.length - done, pos + done)).bytesWritten;
+}
+async function sha256Of(fh, signal) {
+    const h = (0, node_crypto_1.createHash)('sha256');
+    const buf = new Uint8Array(READ_CHUNK);
+    for (let pos = 0;;) {
+        signal?.throwIfAborted();
+        const { bytesRead } = await fh.read(buf, 0, buf.length, pos);
+        if (!bytesRead)
+            return h.digest('hex');
+        h.update(buf.subarray(0, bytesRead));
+        pos += bytesRead;
+    }
+}
+async function sha256File(path, signal) {
+    const fh = await (0, promises_1.open)(path, 'r');
+    try {
+        return await sha256Of(fh, signal);
+    }
+    finally {
+        await fh.close();
+    }
+}
+const isFile = (path) => (0, promises_1.stat)(path).then((st) => st.isFile(), () => false);
+/**
+ * Whether the file at path already is the object: its size and plaintext SHA-256 (never the ETag). An object whose
+ * checksum is a composite of parts can't be compared, so it's never the same.
+ */
+async function sameFile(path, obj, signal) {
+    const st = await (0, promises_1.stat)(path).catch(() => null);
+    if (!st || st.size !== obj.size)
+        return false;
+    if (!obj.checksumSha256 || obj.etag.includes('-'))
+        return false;
+    return (await sha256File(path, signal)) === obj.checksumSha256;
+}
+const identity = (st) => ({ dev: st.dev, ino: st.ino });
+/** The file at path when it's a regular file of size bytes with no other name (not a link, nor hard-linked): its identity. */
+async function ownFile(path, size) {
+    const st = await (0, promises_1.lstat)(path, { bigint: true }).catch(() => null);
+    return st && st.isFile() && st.nlink === 1n && st.size === BigInt(size) ? identity(st) : undefined;
+}
+/** UnsafePathError unless the target's part file is still the one this run made or adopted, with no other name. */
+async function checkOwn(t) {
+    const st = await (0, promises_1.lstat)(t.part, { bigint: true }).catch(() => null);
+    if (!st || !sameFileAs(st, t))
+        throw new downloads_plan_js_1.UnsafePathError(`${t.part} was replaced while it was written`);
+}
+function sameFileAs(st, t) {
+    return st.isFile() && st.nlink === 1n && t.id !== undefined && st.dev === t.id.dev && st.ino === t.id.ino;
+}
+/** The target's part file, opened (not through a link) and checked to still be the one this run made or adopted. */
+async function openOwn(t, write) {
+    const fh = await (0, promises_1.open)(t.part, (write ? node_fs_1.constants.O_RDWR : node_fs_1.constants.O_RDONLY) | NOFOLLOW);
+    try {
+        if (!sameFileAs(await fh.stat({ bigint: true }), t))
+            throw new downloads_plan_js_1.UnsafePathError(`${t.part} was replaced while it was written`);
+        return fh;
+    }
+    catch (err) {
+        await fh.close();
+        throw err;
+    }
+}
+// --- paths ----------------------------------------------------------------------------
+/** Whether p is root or under it (both resolved). */
+function within(root, p) {
+    const rel = (0, node_path_1.relative)(root, p);
+    return rel === '' || (rel !== '..' && !rel.startsWith('..' + node_path_1.sep) && !(0, node_path_1.isAbsolute)(rel));
+}
+/**
+ * Where a key's parts go under root: UnsafePathError when that isn't under it, or a link under it leads out of it.
+ */
+async function targetPath(root, parts, rel) {
+    const path = (0, node_path_1.resolve)(root, ...parts);
+    if (path === root || !within(root, path))
+        throw new downloads_plan_js_1.UnsafePathError(`${JSON.stringify(rel)} isn't a safe path under the destination`);
+    await checkInside(root, path);
+    return path;
+}
+/**
+ * UnsafePathError unless path's folder, with every link resolved, is under root's, and its part file isn't a link: a
+ * link under the destination must never carry a write outside it.
+ */
+async function checkInside(root, path) {
+    const top = await realDir(root);
+    const real = await realDir((0, node_path_1.dirname)(path));
+    if (top === null || real === null || !within(top, real) || (await isLink(path + downloads_plan_js_1.PART_SUFFIX))) {
+        throw new downloads_plan_js_1.UnsafePathError(`${JSON.stringify(path)} isn't a safe path under the destination: a link leads out of it`);
+    }
+}
+const isLink = (path) => (0, promises_1.lstat)(path).then((st) => st.isSymbolicLink(), () => false);
+/**
+ * A folder's real path, every link resolved, as far as it exists; the rest as it is (folders a download would make).
+ * null when it can't be told: a link to nothing (making the folder would follow it), or a folder that can't be read.
+ */
+async function realDir(dir) {
+    const rest = [];
+    for (let cur = (0, node_path_1.resolve)(dir);;) {
+        try {
+            return (0, node_path_1.join)(await (0, promises_1.realpath)(cur), ...rest);
+        }
+        catch (err) {
+            if (!missing(err))
+                return null;
+        }
+        if (await (0, promises_1.lstat)(cur).then(() => true, () => false))
+            return null; // there, yet it leads nowhere
+        const up = (0, node_path_1.dirname)(cur);
+        if (up === cur)
+            return null;
+        rest.unshift((0, node_path_1.basename)(cur));
+        cur = up;
+    }
+}
+/**
+ * Whether names under dir ignore case (Windows, macOS's default volumes), found by trying; true when it can't be told,
+ * the safe side. dir is made if it isn't there.
+ */
+async function caseInsensitive(dir) {
+    try {
+        await (0, promises_1.mkdir)(dir, { recursive: true });
+        const name = `.teepin-case-${(0, node_crypto_1.randomBytes)(6).toString('hex')}`;
+        const probe = (0, node_path_1.join)(dir, name);
+        await (await (0, promises_1.open)(probe, 'wx')).close();
+        try {
+            await (0, promises_1.stat)((0, node_path_1.join)(dir, name.toUpperCase()));
+            return true;
+        }
+        catch (err) {
+            return !missing(err);
+        }
+        finally {
+            await (0, promises_1.rm)(probe, { force: true });
+        }
+    }
+    catch {
+        return true;
+    }
+}
+exports.caseInsensitive = caseInsensitive;
+// --- the journal ----------------------------------------------------------------------
+/** The state directory for this OS (section 19.12), or TEEPIN_STATE_DIR. */
+function defaultStateDir() {
+    const override = process.env.TEEPIN_STATE_DIR;
+    if (override)
+        return override;
+    if (process.platform === 'win32')
+        return (0, node_path_1.join)(process.env.LOCALAPPDATA || (0, node_path_1.join)((0, node_os_1.homedir)(), 'AppData', 'Local'), 'teepin');
+    if (process.platform === 'darwin')
+        return (0, node_path_1.join)((0, node_os_1.homedir)(), 'Library', 'Application Support', 'teepin');
+    return (0, node_path_1.join)(process.env.XDG_STATE_HOME || (0, node_path_1.join)((0, node_os_1.homedir)(), '.local', 'state'), 'teepin');
+}
+/** A UUIDv7: it sorts by the time it was made. */
+function uuid7() {
+    const b = (0, node_crypto_1.randomBytes)(16);
+    b.writeUIntBE(Date.now(), 0, 6);
+    b[6] = 0x70 | (b[6] & 0x0f);
+    b[8] = 0x80 | (b[8] & 0x3f);
+    const h = b.toString('hex');
+    return `${h.slice(0, 8)}-${h.slice(8, 12)}-${h.slice(12, 16)}-${h.slice(16, 20)}-${h.slice(20)}`;
+}
+const line = (e) => JSON.stringify(e) + '\n';
+function eventsOf(path, e) {
+    return [
+        { e: 'object', path, key: e.key, version: e.version, size: e.size },
+        ...[...e.ranges.values()].map(([a, b]) => ({ e: 'range', path, a, b })),
+    ];
+}
+/** One line of a journal as an event, or undefined for one that isn't (the last line, cut short by a crash). */
+function parseEvent(text) {
+    let v;
+    try {
+        v = JSON.parse(text);
+    }
+    catch {
+        return undefined;
+    }
+    if (typeof v !== 'object' || v === null || !('e' in v) || !('path' in v) || typeof v.path !== 'string')
+        return undefined;
+    const path = v.path;
+    const num = (x) => (typeof x === 'number' && Number.isSafeInteger(x) && x >= 0 ? x : undefined);
+    if (v.e === 'object' && 'key' in v && 'version' in v && 'size' in v) {
+        const size = num(v.size);
+        if (typeof v.key === 'string' && typeof v.version === 'string' && size !== undefined)
+            return { e: 'object', path, key: v.key, version: v.version, size };
+    }
+    else if (v.e === 'range' && 'a' in v && 'b' in v) {
+        const a = num(v.a);
+        const b = num(v.b);
+        if (a !== undefined && b !== undefined && a <= b)
+            return { e: 'range', path, a, b };
+    }
+    else if (v.e === 'saved') {
+        return { e: 'saved', path };
+    }
+    else if (v.e === 'failed') {
+        return { e: 'failed', path, error: 'error' in v ? String(v.error) : '' };
+    }
+    return undefined;
+}
+/** A journal's events, replayed: each path's download as last written. */
+function replay(text) {
+    const out = new Map();
+    for (const raw of text.split('\n')) {
+        const ev = raw ? parseEvent(raw) : undefined;
+        if (!ev)
+            continue;
+        if (ev.e === 'object') {
+            out.set(ev.path, { key: ev.key, version: ev.version, size: ev.size, state: 'open', ranges: new Map() });
+            continue;
+        }
+        const e = out.get(ev.path);
+        if (!e)
+            continue;
+        if (ev.e === 'range')
+            e.ranges.set(rangeId([ev.a, ev.b]), [ev.a, ev.b]);
+        else
+            e.state = ev.e;
+    }
+    return out;
+}
+/** Lock files this process holds: a lock with this process's id and not here is left from an earlier process with it. */
+const held = new Set();
+/** Whether a lock file is left by a process that's gone (on this host), so it can be taken over. */
+async function staleLock(path) {
+    let text;
+    let mtime;
+    try {
+        text = await (0, promises_1.readFile)(path, 'utf8');
+        mtime = (await (0, promises_1.stat)(path)).mtimeMs;
+    }
+    catch (err) {
+        return missing(err); // gone meanwhile: try again
+    }
+    let owner;
+    try {
+        owner = JSON.parse(text);
+    }
+    catch {
+        owner = undefined;
+    }
+    if (typeof owner !== 'object' || owner === null || !('host' in owner) || !('pid' in owner) || typeof owner.pid !== 'number') {
+        return Date.now() - mtime > 60000; // half written: its maker may still be writing it
+    }
+    if (owner.host !== (0, node_os_1.hostname)())
+        return false; // another computer's (a shared folder): never taken
+    if (owner.pid === process.pid)
+        return !held.has(path);
+    try {
+        process.kill(owner.pid, 0);
+        return false;
+    }
+    catch (err) {
+        return codeOf(err) !== 'EPERM'; // EPERM: alive, someone else's
+    }
+}
+/** Takes a run's lock: true when this process now holds it, false when a live process does. */
+async function takeLock(path) {
+    for (let tries = 0; tries < 3; tries++) {
+        try {
+            const fh = await (0, promises_1.open)(path, 'wx', 0o600);
+            try {
+                await fh.writeFile(JSON.stringify({ host: (0, node_os_1.hostname)(), pid: process.pid }));
+            }
+            finally {
+                await fh.close();
+            }
+            held.add(path);
+            return true;
+        }
+        catch (err) {
+            if (codeOf(err) !== 'EEXIST')
+                return false;
+        }
+        if (!(await staleLock(path)))
+            return false;
+        await (0, promises_1.rm)(path, { force: true });
+    }
+    return false;
+}
+async function releaseLock(path) {
+    held.delete(path);
+    await (0, promises_1.rm)(path, { force: true }).catch(() => undefined);
+}
+/** The ids of the state directory's download runs, oldest first. */
+async function runIds(stateDir) {
+    const root = (0, node_path_1.join)(stateDir, 'downloads');
+    const names = await (0, promises_1.readdir)(root).catch(() => []);
+    const out = [];
+    for (const n of names)
+        if (await isFile((0, node_path_1.join)(root, n, 'run.json')))
+            out.push(n);
+    return out.sort();
+}
+/** Makes path (and its parents) readable by its owner only; on Windows the profile folder's own ACL is relied on. */
+async function privateDir(path) {
+    await (0, promises_1.mkdir)(path, { recursive: true, mode: 0o700 });
+    if (process.platform !== 'win32')
+        await (0, promises_1.chmod)(path, 0o700);
+}
+/** One download run's folder in the state directory: run.json, events.jsonl and its lock. */
+class RunJournal {
+    id;
+    dir;
+    constructor(stateDir, id) {
+        this.id = id;
+        this.dir = (0, node_path_1.join)(stateDir, 'downloads', id);
+    }
+    get events() {
+        return (0, node_path_1.join)(this.dir, 'events.jsonl');
+    }
+    get lock() {
+        return (0, node_path_1.join)(this.dir, 'lock');
+    }
+    /** A new run, locked by this process. */
+    static async create(stateDir, bucket) {
+        await privateDir(stateDir);
+        await privateDir((0, node_path_1.join)(stateDir, 'downloads'));
+        const run = new RunJournal(stateDir, uuid7());
+        await (0, promises_1.mkdir)(run.dir, { mode: 0o700 });
+        if (!(await takeLock(run.lock)))
+            throw new errors_js_1.TeepinError(`download run ${run.id} is locked`);
+        await (0, journal_js_1.writeAtomic)((0, node_path_1.join)(run.dir, 'run.json'), JSON.stringify({ id: run.id, kind: 'downloads', bucket, created: new Date().toISOString() }) + '\n');
+        return run;
+    }
+    /** Appends events together and fsyncs them: durable when it resolves. */
+    async append(events) {
+        if (!events.length)
+            return;
+        const fh = await (0, promises_1.open)(this.events, 'a', 0o600);
+        try {
+            await fh.appendFile(events.map(line).join(''));
+            await fh.sync();
+        }
+        finally {
+            await fh.close();
+        }
+        exports.testHooks.journaled?.(events);
+    }
+    async release() {
+        await releaseLock(this.lock);
+    }
+    /** Deletes the run: its journal first (throwing if that can't be deleted, with the lock still held), its lock last. */
+    async remove() {
+        await (0, promises_1.rm)(this.events, { force: true });
+        await (0, promises_1.rm)((0, node_path_1.join)(this.dir, 'run.json'), { force: true }).catch(() => undefined);
+        await releaseLock(this.lock);
+        await (0, promises_1.rm)(this.dir, { recursive: true, force: true }).catch(() => undefined);
+    }
+}
+//# sourceMappingURL=downloads.js.map