@hostr/upload 0.1.0

package/dist/node.js

@@ -0,0 +1,1089 @@
+// src/node/index.ts
+import { open, mkdir, readFile, writeFile, unlink } from "node:fs/promises";
+import { join } from "node:path";
+import { tmpdir } from "node:os";
+
+// src/core/session.ts
+var storageKey = (fileId) => `hostr.upload.v1:${fileId}`;
+async function loadSession(store, fileId) {
+  try {
+    const raw = await store.get(storageKey(fileId));
+    if (raw == null) return null;
+    const parsed = JSON.parse(raw);
+    if (parsed?.v !== 1) return null;
+    return parsed;
+  } catch {
+    return null;
+  }
+}
+async function saveSession(store, s) {
+  await store.set(storageKey(s.fileId), JSON.stringify(s));
+}
+async function clearSession(store, fileId) {
+  await store.delete(storageKey(fileId));
+}
+function partSizeOf(s, n) {
+  if (n === s.expectedParts) {
+    return s.declaredSize - (s.expectedParts - 1) * s.partSize;
+  }
+  return s.partSize;
+}
+
+// src/api/client.ts
+var ApiError = class extends Error {
+  status;
+  code;
+  constructor(status, code) {
+    super(code ? `hostr api error ${status}: ${code}` : `hostr api error ${status}`);
+    this.name = "ApiError";
+    this.status = status;
+    this.code = code;
+  }
+};
+var NetworkError = class extends Error {
+  constructor(message = "network error") {
+    super(message);
+    this.name = "NetworkError";
+  }
+};
+var trimEndpoint = (endpoint) => endpoint.replace(/\/$/, "");
+async function req(fetchFn, endpoint, bearer, path, init = {}) {
+  const url = `${trimEndpoint(endpoint)}${path}`;
+  const headers = { authorization: `Bearer ${bearer}` };
+  let body;
+  if (init.body !== void 0) {
+    headers["content-type"] = "application/json";
+    body = JSON.stringify(init.body);
+  }
+  let res;
+  try {
+    res = await fetchFn(url, { method: init.method ?? "GET", headers, body });
+  } catch {
+    throw new NetworkError();
+  }
+  const text = await res.text();
+  const data = text ? JSON.parse(text) : {};
+  if (!res.ok) {
+    const code = data && typeof data === "object" && typeof data.error === "string" ? data.error : void 0;
+    throw new ApiError(res.status, code);
+  }
+  return data;
+}
+var HostrApi = class {
+  #endpoint;
+  #bearer;
+  #fetch;
+  constructor(endpoint, bearer, fetchFn = fetch) {
+    this.#endpoint = endpoint;
+    this.#bearer = bearer;
+    this.#fetch = fetchFn;
+  }
+  setBearer(bearer) {
+    this.#bearer = bearer;
+  }
+  getUpload(assetId) {
+    return req(this.#fetch, this.#endpoint, this.#bearer, `/v1/uploads/${assetId}`);
+  }
+  presignParts(assetId, partNumbers, expiresIn) {
+    return req(this.#fetch, this.#endpoint, this.#bearer, `/v1/uploads/${assetId}/parts`, {
+      method: "POST",
+      body: expiresIn === void 0 ? { partNumbers } : { partNumbers, expiresIn }
+    });
+  }
+  complete(assetId, body) {
+    return req(this.#fetch, this.#endpoint, this.#bearer, `/v1/uploads/${assetId}/complete`, {
+      method: "POST",
+      body
+    });
+  }
+  async abort(assetId) {
+    await req(this.#fetch, this.#endpoint, this.#bearer, `/v1/uploads/${assetId}`, { method: "DELETE" });
+  }
+};
+async function createUploadSession(opts, fetchFn = fetch) {
+  const { endpoint, apiKey, ...body } = opts;
+  return req(fetchFn, endpoint, apiKey, "/v1/uploads", { method: "POST", body });
+}
+function mintUploadToken(opts, fetchFn = fetch) {
+  const { endpoint, apiKey, assetId, tokenTtlSec } = opts;
+  return req(fetchFn, endpoint, apiKey, `/v1/uploads/${assetId}/token`, {
+    method: "POST",
+    body: tokenTtlSec === void 0 ? {} : { tokenTtlSec }
+  });
+}
+
+// src/core/retry.ts
+var RETRY_BUDGET = 6;
+function classifyPut(res, err) {
+  if (err instanceof NetworkError) return "network";
+  if (err != null) return "fatal";
+  if (res === null) return "network";
+  const { status } = res;
+  if (status === 403) return "expired";
+  if (status === 429 || status >= 500 && status < 600) return "transient";
+  return "fatal";
+}
+function classifyApi(err) {
+  if (err instanceof NetworkError) return "network";
+  if (err instanceof ApiError) {
+    if (err.status === 429 || err.status >= 500 && err.status < 600) return "transient";
+    return "fatal";
+  }
+  return "transient";
+}
+function backoffMs(attempt, rng = Math.random, capMs = 6e4) {
+  const base = 500 * 2 ** (attempt - 1);
+  const jittered = base * (1 + 0.5 * rng());
+  return Math.min(capMs, jittered);
+}
+
+// src/core/events.ts
+var Emitter = class {
+  listeners = /* @__PURE__ */ new Map();
+  on(ev, cb) {
+    let set = this.listeners.get(ev);
+    if (!set) {
+      set = /* @__PURE__ */ new Set();
+      this.listeners.set(ev, set);
+    }
+    const wrapped = cb;
+    set.add(wrapped);
+    return () => {
+      set.delete(wrapped);
+    };
+  }
+  emit(ev, v) {
+    const set = this.listeners.get(ev);
+    if (!set) return;
+    for (const cb of set) {
+      try {
+        cb(v);
+      } catch {
+      }
+    }
+  }
+};
+function computeProgress(i) {
+  const elapsedSec = (i.nowMs - i.startedAtMs) / 1e3;
+  const confirmedThisRun = i.confirmed - i.confirmedAtStart;
+  const throughputBps = elapsedSec >= 1 && confirmedThisRun > 0 ? confirmedThisRun / elapsedSec : null;
+  const bytesSent = Math.min(i.confirmed + i.inflight, i.total);
+  const etaSec = throughputBps === null ? null : (i.total - bytesSent) / throughputBps;
+  const progress = {
+    bytesSent,
+    bytesConfirmed: i.confirmed,
+    totalBytes: i.total,
+    throughputBps,
+    etaSec,
+    partsDone: i.partsDone,
+    partsTotal: i.partsTotal
+  };
+  if (i.partStates !== void 0) progress.partStates = i.partStates;
+  return progress;
+}
+
+// src/hash/hex.ts
+var HEX = "0123456789abcdef";
+function bytesToHex(b) {
+  let s = "";
+  for (let i = 0; i < b.length; i++) s += HEX[b[i] >> 4] + HEX[b[i] & 15];
+  return s;
+}
+function hexToBytes(s) {
+  const out = new Uint8Array(s.length >> 1);
+  for (let i = 0; i < out.length; i++) out[i] = parseInt(s.slice(i * 2, i * 2 + 2), 16);
+  return out;
+}
+
+// src/hash/sha256.ts
+var K = new Int32Array(64);
+var H0 = new Int32Array(8);
+{
+  const primes = [];
+  for (let n = 2; primes.length < 64; n++) if (primes.every((p) => n % p)) primes.push(n);
+  for (let i = 0; i < 64; i++) K[i] = Math.floor(primes[i] ** (1 / 3) % 1 * 2 ** 32) | 0;
+  for (let i = 0; i < 8; i++) H0[i] = Math.floor(Math.sqrt(primes[i]) % 1 * 2 ** 32) | 0;
+}
+var rotr = (x, n) => x >>> n | x << 32 - n;
+var Sha256 = class _Sha256 {
+  h = new Int32Array(H0);
+  buf = new Uint8Array(64);
+  bufLen = 0;
+  len = 0;
+  // total bytes; Number is exact to 2^53
+  w = new Int32Array(64);
+  update(data) {
+    this.len += data.length;
+    let off = 0;
+    if (this.bufLen > 0) {
+      const take = Math.min(64 - this.bufLen, data.length);
+      this.buf.set(data.subarray(0, take), this.bufLen);
+      this.bufLen += take;
+      off = take;
+      if (this.bufLen === 64) {
+        this.compress(this.buf, 0);
+        this.bufLen = 0;
+      }
+    }
+    for (; off + 64 <= data.length; off += 64) this.compress(data, off);
+    if (off < data.length) {
+      this.buf.set(data.subarray(off));
+      this.bufLen = data.length - off;
+    }
+  }
+  compress(p, off) {
+    const w = this.w;
+    for (let i = 0; i < 16; i++)
+      w[i] = p[off + 4 * i] << 24 | p[off + 4 * i + 1] << 16 | p[off + 4 * i + 2] << 8 | p[off + 4 * i + 3];
+    for (let i = 16; i < 64; i++) {
+      const s0 = rotr(w[i - 15], 7) ^ rotr(w[i - 15], 18) ^ w[i - 15] >>> 3;
+      const s1 = rotr(w[i - 2], 17) ^ rotr(w[i - 2], 19) ^ w[i - 2] >>> 10;
+      w[i] = w[i - 16] + s0 + w[i - 7] + s1 | 0;
+    }
+    let [a, b, c, d, e, f, g, hh] = [this.h[0], this.h[1], this.h[2], this.h[3], this.h[4], this.h[5], this.h[6], this.h[7]];
+    for (let i = 0; i < 64; i++) {
+      const S1 = rotr(e, 6) ^ rotr(e, 11) ^ rotr(e, 25);
+      const ch = e & f ^ ~e & g;
+      const t1 = hh + S1 + ch + K[i] + w[i] | 0;
+      const S0 = rotr(a, 2) ^ rotr(a, 13) ^ rotr(a, 22);
+      const maj = a & b ^ a & c ^ b & c;
+      const t2 = S0 + maj | 0;
+      hh = g;
+      g = f;
+      f = e;
+      e = d + t1 | 0;
+      d = c;
+      c = b;
+      b = a;
+      a = t1 + t2 | 0;
+    }
+    this.h[0] = this.h[0] + a | 0;
+    this.h[1] = this.h[1] + b | 0;
+    this.h[2] = this.h[2] + c | 0;
+    this.h[3] = this.h[3] + d | 0;
+    this.h[4] = this.h[4] + e | 0;
+    this.h[5] = this.h[5] + f | 0;
+    this.h[6] = this.h[6] + g | 0;
+    this.h[7] = this.h[7] + hh | 0;
+  }
+  /**
+   * Finalize on a clone so the hash can keep accepting updates.
+   *
+   * Padding: capture the message length in bits BEFORE touching the clone,
+   * then build the entire 0x80 + zero-padding + 64-bit length tail as one
+   * buffer sized so the clone's running byte count lands on a block
+   * boundary, and hand it to update() in a single call. update()'s own
+   * `len` bookkeeping on the clone is irrelevant after this point (the
+   * clone is discarded), so there is no need to keep it meaningful.
+   */
+  digestBytes() {
+    const c = this.clone();
+    const bitLen = c.len * 8;
+    const zeroCount = (56 - (c.len + 1) % 64 + 64) % 64;
+    const pad = new Uint8Array(1 + zeroCount + 8);
+    pad[0] = 128;
+    const lo = bitLen >>> 0, hi = Math.floor(bitLen / 2 ** 32);
+    const tailOff = 1 + zeroCount;
+    for (let i = 0; i < 4; i++) {
+      pad[tailOff + i] = hi >>> 8 * (3 - i) & 255;
+      pad[tailOff + 4 + i] = lo >>> 8 * (3 - i) & 255;
+    }
+    c.update(pad);
+    const out = new Uint8Array(32);
+    for (let i = 0; i < 8; i++)
+      for (let j = 0; j < 4; j++) out[4 * i + j] = c.h[i] >>> 8 * (3 - j) & 255;
+    return out;
+  }
+  digestHex() {
+    return bytesToHex(this.digestBytes());
+  }
+  exportState() {
+    return JSON.stringify({ h: [...this.h], buf: bytesToHex(this.buf.subarray(0, this.bufLen)), len: this.len });
+  }
+  importState(state) {
+    const s = JSON.parse(state);
+    this.h = new Int32Array(s.h);
+    this.buf.fill(0);
+    this.bufLen = s.buf.length / 2;
+    this.len = s.len;
+    for (let i = 0; i < this.bufLen; i++) this.buf[i] = parseInt(s.buf.slice(i * 2, i * 2 + 2), 16);
+  }
+  clone() {
+    const c = new _Sha256();
+    c.h = new Int32Array(this.h);
+    c.buf = new Uint8Array(this.buf);
+    c.bufLen = this.bufLen;
+    c.len = this.len;
+    return c;
+  }
+};
+
+// src/hash/md5.ts
+var K2 = new Int32Array(64);
+for (let i = 0; i < 64; i++) K2[i] = Math.floor(Math.abs(Math.sin(i + 1)) * 2 ** 32) | 0;
+var S = [7, 12, 17, 22, 5, 9, 14, 20, 4, 11, 16, 23, 6, 10, 15, 21];
+var rotl = (x, n) => x << n | x >>> 32 - n;
+var Md5 = class _Md5 {
+  h = new Int32Array([1732584193, 4023233417 | 0, 2562383102 | 0, 271733878]);
+  buf = new Uint8Array(64);
+  bufLen = 0;
+  len = 0;
+  // total bytes; Number is exact to 2^53
+  update(data) {
+    this.len += data.length;
+    let off = 0;
+    if (this.bufLen > 0) {
+      const take = Math.min(64 - this.bufLen, data.length);
+      this.buf.set(data.subarray(0, take), this.bufLen);
+      this.bufLen += take;
+      off = take;
+      if (this.bufLen === 64) {
+        this.compress(this.buf, 0);
+        this.bufLen = 0;
+      }
+    }
+    for (; off + 64 <= data.length; off += 64) this.compress(data, off);
+    if (off < data.length) {
+      this.buf.set(data.subarray(off));
+      this.bufLen = data.length - off;
+    }
+  }
+  compress(p, off) {
+    const m = new Int32Array(16);
+    for (let i = 0; i < 16; i++)
+      m[i] = p[off + 4 * i] | p[off + 4 * i + 1] << 8 | p[off + 4 * i + 2] << 16 | p[off + 4 * i + 3] << 24;
+    let a = this.h[0], b = this.h[1], c = this.h[2], d = this.h[3];
+    for (let i = 0; i < 64; i++) {
+      let f, g;
+      if (i < 16) {
+        f = b & c | ~b & d;
+        g = i;
+      } else if (i < 32) {
+        f = d & b | ~d & c;
+        g = (5 * i + 1) % 16;
+      } else if (i < 48) {
+        f = b ^ c ^ d;
+        g = (3 * i + 5) % 16;
+      } else {
+        f = c ^ (b | ~d);
+        g = 7 * i % 16;
+      }
+      const t = d;
+      d = c;
+      c = b;
+      b = b + rotl(a + f + K2[i] + m[g] | 0, S[(i >> 4) * 4 + (i & 3)]) | 0;
+      a = t;
+    }
+    this.h[0] = this.h[0] + a | 0;
+    this.h[1] = this.h[1] + b | 0;
+    this.h[2] = this.h[2] + c | 0;
+    this.h[3] = this.h[3] + d | 0;
+  }
+  /**
+   * Finalize on a clone so the hash can keep accepting updates.
+   *
+   * Padding: capture the message length in bits BEFORE touching the clone,
+   * then build the entire 0x80 + zero-padding + 64-bit length tail as one
+   * buffer sized so the clone's running byte count lands on a block
+   * boundary, and hand it to update() in a single call. update()'s own
+   * `len` bookkeeping on the clone is irrelevant after this point (the
+   * clone is discarded), so there is no need to keep it meaningful.
+   */
+  digestBytes() {
+    const c = this.clone();
+    const bitLen = c.len * 8;
+    const zeroCount = (56 - (c.len + 1) % 64 + 64) % 64;
+    const pad = new Uint8Array(1 + zeroCount + 8);
+    pad[0] = 128;
+    const lo = bitLen >>> 0, hi = Math.floor(bitLen / 2 ** 32);
+    const tailOff = 1 + zeroCount;
+    for (let i = 0; i < 4; i++) {
+      pad[tailOff + i] = lo >>> 8 * i & 255;
+      pad[tailOff + 4 + i] = hi >>> 8 * i & 255;
+    }
+    c.update(pad);
+    const out = new Uint8Array(16);
+    for (let i = 0; i < 4; i++)
+      for (let j = 0; j < 4; j++) out[4 * i + j] = c.h[i] >>> 8 * j & 255;
+    return out;
+  }
+  digestHex() {
+    return bytesToHex(this.digestBytes());
+  }
+  exportState() {
+    return JSON.stringify({ h: [...this.h], buf: bytesToHex(this.buf.subarray(0, this.bufLen)), len: this.len });
+  }
+  importState(state) {
+    const s = JSON.parse(state);
+    this.h = new Int32Array(s.h);
+    this.buf.fill(0);
+    this.bufLen = s.buf.length / 2;
+    this.len = s.len;
+    for (let i = 0; i < this.bufLen; i++) this.buf[i] = parseInt(s.buf.slice(i * 2, i * 2 + 2), 16);
+  }
+  clone() {
+    const c = new _Md5();
+    c.h = new Int32Array(this.h);
+    c.buf = new Uint8Array(this.buf);
+    c.bufLen = this.bufLen;
+    c.len = this.len;
+    return c;
+  }
+};
+
+// src/hash/composite.ts
+function compositeEtag(md5Hexes) {
+  const h = new Md5();
+  for (const hex of md5Hexes) h.update(hexToBytes(hex));
+  return `${h.digestHex()}-${md5Hexes.length}`;
+}
+
+// src/core/engine.ts
+var SYSTEMIC_TRANSPORT_FAILURE_THRESHOLD = 3;
+var IntegrityError = class extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "IntegrityError";
+  }
+};
+var Stopped = class extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "Stopped";
+  }
+};
+var stripQuotes = (s) => s.replace(/^"|"$/g, "");
+var TERMINAL = ["complete", "failed", "aborted"];
+var UploadEngine = class {
+  done;
+  resolveDone;
+  rejectDone;
+  emitter = new Emitter();
+  presigned = /* @__PURE__ */ new Map();
+  /** Presign fetches since the last confirmed part. Healthy uploads confirm
+   *  constantly, so this stays at zero and costs nothing; in a sustained
+   *  failure loop (every PUT dying without landing a part) it grows, and
+   *  presign() spaces further /parts fetches on the same backoff curve the
+   *  'expired' storm uses — the API call rate is what trips rate limits, so
+   *  it gets its own governor, independent of per-part attempt cadence and
+   *  worker count. */
+  presignsSinceConfirm = 0;
+  /** The in-flight /parts fetch, shared so concurrent cache-missing workers
+   *  ride one round-trip and re-check the cache instead of each firing an
+   *  overlapping batch of their own (same memo shape as hashLanePromise). */
+  presignInflight = null;
+  claimed = /* @__PURE__ */ new Set();
+  inflightSent = /* @__PURE__ */ new Map();
+  stopped = false;
+  running = false;
+  restartPending = false;
+  startedAt = 0;
+  confirmedAtStart = 0;
+  lastEmit = 0;
+  deps;
+  opts;
+  session;
+  /** The in-flight sha256 lane, tracked so a pause→resume never starts a
+   *  second concurrent lane over the same file. Cleared once settled so a
+   *  later resume can start a fresh one from the persisted midstate. */
+  hashLanePromise = null;
+  /** Engine-wide (not per-part): a CORS-blocked bucket fails every worker's
+   *  PUT the same way, so the streak accumulates across parts. Deliberately
+   *  not bumped by apiCall's network stalls — the API answering while every
+   *  R2 PUT dies is exactly the bucket-CORS signature. */
+  consecutiveNetworkFailures = 0;
+  diagnosticFired = false;
+  /** Resolvers for anyone currently parked in waitOnline(), woken the
+   *  instant pause()/abort()/fail() halts the engine — without this a
+   *  stalled engine could only be interrupted by the network itself
+   *  coming back online. */
+  stopWaiters = /* @__PURE__ */ new Set();
+  constructor(deps, opts, session) {
+    this.deps = deps;
+    this.opts = opts;
+    this.session = session;
+    this.done = new Promise((res, rej) => {
+      this.resolveDone = res;
+      this.rejectDone = rej;
+    });
+    this.done.catch(() => {
+    });
+  }
+  on(ev, cb) {
+    return this.emitter.on(ev, cb);
+  }
+  get state() {
+    return this.session.status;
+  }
+  start() {
+    if (TERMINAL.includes(this.session.status)) return;
+    if (this.running) {
+      this.restartPending = true;
+      return;
+    }
+    this.stopped = false;
+    this.running = true;
+    this.run().catch((e) => {
+      if (!(e instanceof Stopped)) this.fail(e instanceof Error ? e : new Error(String(e)));
+    }).finally(() => {
+      this.running = false;
+      if (this.restartPending) {
+        this.restartPending = false;
+        this.start();
+      }
+    });
+  }
+  pause() {
+    this.halt();
+    this.restartPending = false;
+    this.setStatus("paused");
+  }
+  resume() {
+    this.start();
+  }
+  async abort() {
+    this.halt();
+    this.setStatus("aborted");
+    await this.deps.api.abort(this.session.assetId).catch(() => {
+    });
+    await clearSession(this.deps.store, this.session.fileId);
+  }
+  /** Stop dispatch everywhere at once: new part claims, waitOnline's
+   *  parked callers, and apiCall's network-retry loop all observe this on
+   *  their next check. */
+  halt() {
+    this.stopped = true;
+    for (const w of this.stopWaiters) w();
+    this.stopWaiters.clear();
+  }
+  setStatus(s) {
+    if (this.session.status === s) return;
+    this.session.status = s;
+    this.emitter.emit("statechange", s);
+  }
+  fail(e) {
+    this.halt();
+    this.setStatus("failed");
+    this.emitter.emit("error", e);
+    this.rejectDone(e);
+  }
+  async run() {
+    const remote = await this.apiCall(() => this.deps.api.getUpload(this.session.assetId));
+    if (remote.status !== "uploading") {
+      if (["uploaded", "queued", "processing", "ready"].includes(remote.status)) return this.finish();
+      throw new Error(`upload is ${remote.status}, cannot continue`);
+    }
+    await this.reconcile(remote.parts);
+    if (this.stopped) return;
+    this.setStatus("running");
+    this.startedAt = this.deps.clock.now();
+    this.confirmedAtStart = this.bytesConfirmed();
+    const hashLane = this.getHashLane();
+    await Promise.all(Array.from({ length: this.opts.concurrency }, () => this.worker()));
+    if (this.stopped) return;
+    this.session.sha256 = await hashLane;
+    if (this.stopped) return;
+    await saveSession(this.deps.store, this.session);
+    await this.finish();
+  }
+  async finish() {
+    this.setStatus("completing");
+    await saveSession(this.deps.store, this.session);
+    const res = await this.apiCall(() => this.deps.api.complete(
+      this.session.assetId,
+      this.session.sha256 ? { sha256: this.session.sha256 } : {}
+    ));
+    const expected = this.expectedComposite();
+    if (expected && res.etag && res.etag !== expected)
+      throw new IntegrityError(`R2 assembled ${res.etag}; client computed ${expected}`);
+    await clearSession(this.deps.store, this.session.fileId);
+    await this.deps.file.close?.();
+    this.setStatus("complete");
+    const info = {
+      assetId: this.session.assetId,
+      etag: res.etag ?? expected ?? "",
+      sha256: this.session.sha256,
+      bytes: res.bytes ?? this.session.declaredSize
+    };
+    this.emitter.emit("complete", info);
+    this.resolveDone(info);
+  }
+  expectedComposite() {
+    const md5s = [];
+    for (let n = 1; n <= this.session.expectedParts; n++) {
+      const m = this.session.done[n];
+      if (!m) return null;
+      md5s.push(m);
+    }
+    return compositeEtag(md5s);
+  }
+  /** Reconcile local bookkeeping against what R2 actually holds before resuming.
+   *  Local claims R2 can't confirm are stale and forgotten; parts whose stored
+   *  md5 matches R2's etag are kept as-is; a mismatch means the landed bytes
+   *  aren't verified as ours, so it's dropped for re-upload. For parts R2 holds
+   *  but local `done` has no record of (state lost — reinstall, cleared
+   *  storage), the local byte range is re-read and re-hashed; it's only
+   *  adopted as done when that hash matches R2's etag, never trusted blind. */
+  async reconcile(remote) {
+    const remoteByN = new Map(remote.map((p) => [p.partNumber, p]));
+    for (const n of Object.keys(this.session.done).map(Number))
+      if (!remoteByN.has(n)) delete this.session.done[n];
+    for (const p of remote) {
+      const have = this.session.done[p.partNumber];
+      if (have === p.etag) continue;
+      if (have) {
+        delete this.session.done[p.partNumber];
+        continue;
+      }
+      const offset = (p.partNumber - 1) * this.session.partSize;
+      const body = await this.deps.file.read(offset, partSizeOf(this.session, p.partNumber));
+      const h = this.deps.hasher.md5();
+      h.update(body);
+      const md5 = h.digestHex();
+      if (md5 === p.etag) this.session.done[p.partNumber] = md5;
+    }
+    if (this.session.status === "aborted") return;
+    await saveSession(this.deps.store, this.session);
+  }
+  nextPart() {
+    for (let n = 1; n <= this.session.expectedParts; n++)
+      if (!this.session.done[n] && !this.claimed.has(n)) return n;
+    return null;
+  }
+  async worker() {
+    while (!this.stopped) {
+      const n = this.nextPart();
+      if (n == null) return;
+      this.claimed.add(n);
+      try {
+        await this.uploadPart(n);
+      } finally {
+        this.claimed.delete(n);
+        this.inflightSent.delete(n);
+      }
+    }
+  }
+  async uploadPart(n) {
+    let budget = RETRY_BUDGET, attempt = 0, consecutiveExpired = 0;
+    let cls;
+    for (; ; ) {
+      if (this.stopped) return;
+      await this.waitOnline();
+      if (this.stopped) return;
+      let caught;
+      try {
+        const url = await this.presign(n, cls === "expired");
+        const offset = (n - 1) * this.session.partSize;
+        const expectedLen = partSizeOf(this.session, n);
+        const body = await this.deps.file.read(offset, expectedLen);
+        if (body.length !== expectedLen)
+          throw new Error(
+            `part ${n}: source file changed size mid-upload (expected ${expectedLen} bytes, read ${body.length}) \u2014 the file was modified or truncated after the upload started`
+          );
+        const h = this.deps.hasher.md5();
+        h.update(body);
+        const md5 = h.digestHex();
+        const res = await this.deps.transport.put(
+          url,
+          body,
+          { onProgress: (s) => this.onPartProgress(n, s) }
+        );
+        if (res.status >= 200 && res.status < 300) {
+          if (res.etag && stripQuotes(res.etag) === md5) {
+            if (this.session.status === "aborted") return;
+            this.notePutOutcome("ok");
+            this.session.done[n] = md5;
+            this.presignsSinceConfirm = 0;
+            await saveSession(this.deps.store, this.session);
+            this.inflightSent.delete(n);
+            this.emitProgress(true);
+            return;
+          }
+          cls = "corrupt";
+        } else cls = classifyPut(res, void 0);
+      } catch (err) {
+        if (err instanceof Stopped) return;
+        caught = err instanceof Error ? err : void 0;
+        cls = err instanceof ApiError ? classifyApi(err) : classifyPut(null, err);
+      }
+      this.inflightSent.delete(n);
+      this.notePutOutcome(cls);
+      if (cls === "fatal") {
+        this.halt();
+        throw caught ?? new Error(`part ${n}: unrecoverable upload error`);
+      }
+      if (cls === "expired") {
+        this.presigned.delete(n);
+        consecutiveExpired++;
+        if (consecutiveExpired > 1) await this.deps.clock.sleep(backoffMs(consecutiveExpired, this.deps.rng));
+        continue;
+      }
+      consecutiveExpired = 0;
+      attempt++;
+      if (cls !== "network" && --budget <= 0) {
+        this.halt();
+        throw new Error(`part ${n}: retries exhausted (${cls})`);
+      }
+      if (cls === "network") this.setStatus("stalled");
+      await this.deps.clock.sleep(backoffMs(attempt, this.deps.rng));
+      if (cls === "network" && !this.stopped) this.setStatus("running");
+    }
+  }
+  async presign(n, afterExpiry = false) {
+    const c = this.presigned.get(n);
+    if (c && this.presignFresh(c)) return c.url;
+    if (this.presignInflight) {
+      await this.presignInflight;
+      if (this.stopped) throw new Stopped();
+      const landed = this.presigned.get(n);
+      if (landed && this.presignFresh(landed)) return landed.url;
+    }
+    if (!afterExpiry && this.presignsSinceConfirm > 0) {
+      await this.deps.clock.sleep(backoffMs(this.presignsSinceConfirm, this.deps.rng));
+      if (this.stopped) throw new Stopped();
+      const landed = this.presigned.get(n);
+      if (landed && this.presignFresh(landed)) return landed.url;
+    }
+    this.presignsSinceConfirm++;
+    const want = [n];
+    for (let m = 1; m <= this.session.expectedParts && want.length < this.opts.presignBatch; m++) {
+      const e = this.presigned.get(m);
+      if (m !== n && !this.session.done[m] && !(e && this.presignFresh(e))) want.push(m);
+    }
+    const pending = this.apiCall(() => this.deps.api.presignParts(this.session.assetId, want, this.opts.presignTtlSec));
+    const inflight = pending.then(() => {
+    }, () => {
+    });
+    this.presignInflight = inflight;
+    try {
+      const res = await pending;
+      for (const u of res.urls)
+        this.presigned.set(u.partNumber, { url: u.url, expiresAt: this.deps.clock.now() + res.expiresIn * 1e3 });
+      return this.presigned.get(n).url;
+    } finally {
+      if (this.presignInflight === inflight) this.presignInflight = null;
+    }
+  }
+  /** Fresh = safely usable for a new PUT: at least 60s of validity left, so
+   *  a part starting now won't have its URL expire mid-flight. */
+  presignFresh(c) {
+    return c.expiresAt - 6e4 > this.deps.clock.now();
+  }
+  /** API calls: infinite patience for network loss, one token refresh on 401, else throw.
+   *  Throws Stopped (never surfaced) if pause()/abort() interrupts a stuck retry. */
+  async apiCall(fn) {
+    const attempts = /* @__PURE__ */ new Map();
+    let refreshed = false;
+    const bump = (cls) => {
+      const n = (attempts.get(cls) ?? 0) + 1;
+      attempts.set(cls, n);
+      return n;
+    };
+    for (; ; ) {
+      try {
+        return await fn();
+      } catch (e) {
+        const cls = classifyApi(e);
+        if (cls === "network") {
+          this.setStatus("stalled");
+          const attempt = bump("network");
+          await this.waitOnline();
+          if (this.stopped) throw new Stopped();
+          await this.deps.clock.sleep(backoffMs(attempt, this.deps.rng));
+          if (this.stopped) throw new Stopped();
+          continue;
+        }
+        if (e instanceof ApiError && e.status === 401 && this.opts.onTokenExpired && !refreshed) {
+          refreshed = true;
+          const t = await this.opts.onTokenExpired(this.session.assetId);
+          this.session.uploadToken = t;
+          this.deps.api.setBearer(t);
+          await saveSession(this.deps.store, this.session);
+          continue;
+        }
+        if (cls === "transient") {
+          const attempt = bump("transient");
+          if (attempt <= RETRY_BUDGET) {
+            await this.deps.clock.sleep(backoffMs(attempt, this.deps.rng));
+            continue;
+          }
+        }
+        throw e;
+      }
+    }
+  }
+  async waitOnline() {
+    const net = this.deps.network;
+    if (!net || net.isOnline()) return;
+    if (this.stopped) return;
+    this.setStatus("stalled");
+    await new Promise((res) => {
+      let off = () => {
+      };
+      const finish = () => {
+        off();
+        this.stopWaiters.delete(finish);
+        res();
+      };
+      off = net.onChange((on) => {
+        if (on) finish();
+      });
+      this.stopWaiters.add(finish);
+    });
+    if (!this.stopped) this.setStatus("running");
+  }
+  /** Lazily starts the sha256 lane and remembers the in-flight promise so a
+   *  fast pause→resume can never spawn a second concurrent lane over the
+   *  same file. The promise carries its own no-op .catch so it can never
+   *  become an unhandledRejection while nothing is actively awaiting it
+   *  (e.g. during a paused window); a real failure still surfaces normally
+   *  to whoever does await it, and from there through run() to fail(). */
+  getHashLane() {
+    if (this.opts.checksum !== "sha256" || this.session.sha256) return Promise.resolve(this.session.sha256);
+    if (!this.hashLanePromise) {
+      const p = this.hashLane().finally(() => {
+        if (this.hashLanePromise === p) this.hashLanePromise = null;
+      });
+      this.hashLanePromise = p;
+      this.hashLanePromise.catch(() => {
+      });
+    }
+    return this.hashLanePromise;
+  }
+  async hashLane() {
+    const CHUNK = 1 << 20;
+    const h = new Sha256();
+    let off = 0;
+    if (this.session.hash) {
+      h.importState(this.session.hash.state);
+      off = this.session.hash.offset;
+    }
+    while (off < this.deps.file.size) {
+      if (this.stopped) {
+        this.hashLanePromise = null;
+        if (this.session.status === "aborted") return void 0;
+        this.session.hash = { offset: off, state: h.exportState() };
+        await saveSession(this.deps.store, this.session);
+        return void 0;
+      }
+      const b = await this.deps.file.read(off, Math.min(CHUNK, this.deps.file.size - off));
+      h.update(b);
+      off += b.length;
+      if (off % (8 * CHUNK) === 0) this.session.hash = { offset: off, state: h.exportState() };
+    }
+    this.session.hash = void 0;
+    return h.digestHex();
+  }
+  /** Feed every part-PUT outcome to the systemic-transport-failure detector.
+   *  Any outcome that isn't network-class — success, 403, 5xx, even corrupt
+   *  bytes — proves a request reached the server, so the streak resets. */
+  notePutOutcome(cls) {
+    if (cls !== "network") {
+      this.consecutiveNetworkFailures = 0;
+      this.diagnosticFired = false;
+      return;
+    }
+    this.consecutiveNetworkFailures++;
+    if (this.diagnosticFired) return;
+    if (this.consecutiveNetworkFailures < SYSTEMIC_TRANSPORT_FAILURE_THRESHOLD) return;
+    if (this.bytesConfirmed() > 0) return;
+    this.diagnosticFired = true;
+    this.emitter.emit("diagnostic", {
+      code: "systemic-transport-failure",
+      consecutiveNetworkFailures: this.consecutiveNetworkFailures,
+      bytesEverConfirmed: this.bytesConfirmed(),
+      hint: 'every part PUT is failing at the network layer and no bytes have ever been confirmed for this session \u2014 if this is a browser, check the source bucket CORS rules (preflight PUT from this origin, ExposeHeaders ETag); see README "Bucket CORS is a hard prerequisite for browser uploads"'
+    });
+  }
+  bytesConfirmed() {
+    let sum = 0;
+    for (const n of Object.keys(this.session.done)) sum += partSizeOf(this.session, Number(n));
+    return sum;
+  }
+  onPartProgress(n, sent) {
+    this.inflightSent.set(n, sent);
+    this.emitProgress(false);
+  }
+  emitProgress(force) {
+    const now = this.deps.clock.now();
+    if (!force && now - this.lastEmit < 200) return;
+    this.lastEmit = now;
+    let inflight = 0;
+    for (const v of this.inflightSent.values()) inflight += v;
+    const partStates = {};
+    for (const n of this.claimed) partStates[n] = "inflight";
+    for (const n of Object.keys(this.session.done)) partStates[Number(n)] = "done";
+    this.emitter.emit("progress", computeProgress({
+      confirmed: this.bytesConfirmed(),
+      inflight,
+      total: this.session.declaredSize,
+      partsDone: Object.keys(this.session.done).length,
+      partsTotal: this.session.expectedParts,
+      startedAtMs: this.startedAt,
+      nowMs: now,
+      confirmedAtStart: this.confirmedAtStart,
+      partStates
+    }));
+  }
+};
+
+// src/core/upload.ts
+var realClock = { now: () => Date.now(), sleep: (ms) => new Promise((res) => setTimeout(res, ms)) };
+async function buildUpload(opts) {
+  const clock = opts.clock ?? realClock;
+  const fetchFn = opts.fetchFn ?? fetch;
+  const api = new HostrApi(opts.endpoint, opts.uploadToken, fetchFn);
+  let session = await loadSession(opts.store, opts.file.id);
+  if (session) {
+    session.uploadToken = opts.uploadToken;
+    await saveSession(opts.store, session);
+  } else {
+    const remote = await api.getUpload(opts.assetId);
+    session = {
+      v: 1,
+      assetId: opts.assetId,
+      endpoint: opts.endpoint,
+      uploadToken: opts.uploadToken,
+      key: remote.key,
+      partSize: remote.partSize,
+      expectedParts: remote.expectedParts,
+      declaredSize: opts.file.size,
+      fileId: opts.file.id,
+      done: {},
+      status: "idle",
+      createdAt: (/* @__PURE__ */ new Date()).toISOString()
+    };
+    await saveSession(opts.store, session);
+  }
+  const deps = {
+    api,
+    file: opts.file,
+    transport: opts.transport,
+    store: opts.store,
+    hasher: opts.hasher,
+    clock,
+    network: opts.network
+  };
+  const engineOpts = {
+    concurrency: opts.concurrency ?? 4,
+    checksum: opts.checksum ?? "sha256",
+    presignBatch: 16,
+    presignTtlSec: opts.presignTtlSec ?? 3600,
+    onTokenExpired: opts.onTokenExpired
+  };
+  return new UploadEngine(deps, engineOpts, session);
+}
+
+// src/node/hasher.ts
+import { createHash } from "node:crypto";
+var NodeMd5 = class {
+  #hash = createHash("md5");
+  #digest = null;
+  update(data) {
+    if (!this.#hash) throw new Error("NodeMd5: cannot update after digest() has been called");
+    this.#hash.update(data);
+  }
+  digestBytes() {
+    if (this.#digest) return this.#digest;
+    if (!this.#hash) throw new Error("NodeMd5: cannot digest twice");
+    this.#digest = new Uint8Array(this.#hash.digest());
+    this.#hash = null;
+    return this.#digest;
+  }
+  digestHex() {
+    return Buffer.from(this.digestBytes()).toString("hex");
+  }
+};
+var nodeHasher = { md5: () => new NodeMd5() };
+
+// src/node/index.ts
+async function nodeFileSource(path) {
+  const handle = await open(path, "r");
+  const stat = await handle.stat();
+  const size = stat.size;
+  const id = `${path}:${size}:${Math.floor(stat.mtimeMs)}`;
+  return {
+    size,
+    id,
+    async read(offset, length) {
+      const want = Math.max(0, Math.min(length, size - offset));
+      if (want === 0) return new Uint8Array(0);
+      const buf = Buffer.alloc(want);
+      const { bytesRead } = await handle.read(buf, 0, want, offset);
+      return buf.subarray(0, bytesRead);
+    },
+    async close() {
+      await handle.close();
+    }
+  };
+}
+var sanitizeKey = (key) => key.replace(/[^A-Za-z0-9._-]/g, "_");
+function fileStateStore(dir) {
+  const fileFor = (key) => join(dir, sanitizeKey(key));
+  return {
+    async get(key) {
+      try {
+        return await readFile(fileFor(key), "utf8");
+      } catch (err) {
+        if (err?.code === "ENOENT") return null;
+        throw err;
+      }
+    },
+    async set(key, value) {
+      await mkdir(dir, { recursive: true });
+      await writeFile(fileFor(key), value, "utf8");
+    },
+    async delete(key) {
+      try {
+        await unlink(fileFor(key));
+      } catch (err) {
+        if (err?.code !== "ENOENT") throw err;
+      }
+    }
+  };
+}
+function nodeTransport(fetchFn = fetch) {
+  return {
+    async put(url, body, opts) {
+      const res = await fetchFn(url, {
+        method: "PUT",
+        body,
+        signal: opts?.signal
+      });
+      opts?.onProgress?.(body.length);
+      return { status: res.status, etag: res.headers.get("etag") };
+    }
+  };
+}
+async function createUpload(opts) {
+  const fetchFn = opts.fetchFn ?? fetch;
+  const file = await nodeFileSource(opts.file);
+  const stateDir = opts.stateDir ?? join(tmpdir(), "hostr-upload");
+  const store = fileStateStore(stateDir);
+  const transport = opts.transport ?? nodeTransport(fetchFn);
+  return buildUpload({
+    endpoint: opts.endpoint,
+    uploadToken: opts.uploadToken,
+    assetId: opts.assetId,
+    file,
+    transport,
+    store,
+    hasher: nodeHasher,
+    fetchFn,
+    concurrency: opts.concurrency,
+    checksum: opts.checksum,
+    onTokenExpired: opts.onTokenExpired
+  });
+}
+export {
+  ApiError,
+  IntegrityError,
+  NetworkError,
+  createUpload,
+  createUploadSession,
+  fileStateStore,
+  mintUploadToken,
+  nodeFileSource,
+  nodeHasher,
+  nodeTransport
+};