@cloudbitmaps/core 0.16.0 → 0.18.0

package/dist/{chunk-LFUNPMXZ.js → chunk-CCP4U32U.js}

@@ -17,6 +17,31 @@ var IntegrityError = class extends CloudRoaringError {
 };
 var NotFoundError = class extends CloudRoaringError {
 };
+var LeaseExpiredError = class extends CloudRoaringError {
+  /** Epoch-ms the lease was taken until. */
+  until;
+  /** `'expired'` when the clock reached `until`, `'released'` after `release()`. */
+  reason;
+  constructor(message, until, reason) {
+    super(message);
+    this.until = until;
+    this.reason = reason;
+  }
+};
+var LeaseLimitError = class extends CloudRoaringError {
+};
+var StaleOperandError = class extends CloudRoaringError {
+  code = "stale-operand";
+  /** The operand's name in the call that found it stale. */
+  operand;
+  /** Why it is stale. */
+  reason;
+  constructor(message, operand, reason) {
+    super(message);
+    this.operand = operand;
+    this.reason = reason;
+  }
+};
 var UnsupportedError = class extends CloudRoaringError {
 };
 var CapabilityError = class extends CloudRoaringError {
@@ -45,6 +70,15 @@ function isWriteConflictError(err) {
 function isTransientError(err) {
   return hasBrand(err, TRANSIENT_BRAND);
 }
+function isLeaseExpiredError(err) {
+  return isCloudRoaringError(err) && err.name === "LeaseExpiredError";
+}
+function isStaleOperandError(err) {
+  return isCloudRoaringError(err) && err.name === "StaleOperandError";
+}
+function isLeaseLimitError(err) {
+  return isCloudRoaringError(err) && err.name === "LeaseLimitError";
+}
 function isNotFoundError(err) {
   return isCloudRoaringError(err) && err.name === "NotFoundError";
 }
@@ -112,6 +146,183 @@ function decodeNameFromPath(encoded) {
   return decodePercent(encoded);
 }
 
+// src/core/token.ts
+var INCARNATION_TOKEN = /^([0-9a-f]{32})\.(0|[1-9]\d*)\.([0-9a-f]{16})$/;
+function incarnationOf(token) {
+  return INCARNATION_TOKEN.exec(token)?.[1];
+}
+function sameIncarnation(a, b) {
+  const ia = incarnationOf(a.token);
+  const ib = incarnationOf(b.token);
+  if (ia !== void 0 || ib !== void 0) return ia === ib;
+  return a.createdAt === b.createdAt;
+}
+
+// src/core/leases.ts
+var MAX_LEASE_MS = 14 * 864e5;
+var LEASE_SKEW_MS = 6e4;
+var MAX_LEASES_PER_SEGMENT = 64;
+var MAX_STORED_LEASES = 256;
+var LEASE_CAS_ATTEMPTS = MAX_LEASES_PER_SEGMENT + 8;
+var UNANSWERED_RESENDS = 3;
+var UNANSWERED_BASE_MS = 500;
+var CONFLICT_BASE_MS = 25;
+var CONFLICT_CAP_MS = 400;
+function isLive(entry, now) {
+  return now < entry.until + LEASE_SKEW_MS && entry.until <= now + MAX_LEASE_MS + LEASE_SKEW_MS;
+}
+function heldGenerations(record, now) {
+  const out = /* @__PURE__ */ new Set();
+  for (const e of record?.leases ?? []) if (isLive(e, now)) out.add(e.generation);
+  return out;
+}
+function liveLeases(record, now) {
+  return (record?.leases ?? []).filter((e) => isLive(e, now));
+}
+var LEASE_ONLY_RETRIES = 2 * MAX_LEASES_PER_SEGMENT + 8;
+var BOOKKEEPING = /* @__PURE__ */ new Set(["token", "updatedAt", "leases"]);
+function stable(value) {
+  if (value === void 0) return "u";
+  if (value === null || typeof value !== "object") return JSON.stringify(value);
+  if (Array.isArray(value)) return `[${value.map(stable).join(",")}]`;
+  const o = value;
+  const keys = Object.keys(o).filter((k) => o[k] !== void 0).sort();
+  return `{${keys.map((k) => `${JSON.stringify(k)}:${stable(o[k])}`).join(",")}}`;
+}
+function onlyLeasesDiffer(held, now, alsoIgnore = []) {
+  if (!sameIncarnation(held, now)) return false;
+  const skip = /* @__PURE__ */ new Set([...BOOKKEEPING, ...alsoIgnore]);
+  const keys = /* @__PURE__ */ new Set([...Object.keys(held), ...Object.keys(now)]);
+  for (const k of keys) {
+    if (skip.has(k)) continue;
+    if (stable(held[k]) !== stable(now[k])) {
+      return false;
+    }
+  }
+  return true;
+}
+function leaseChurn(deps) {
+  let used = 0;
+  return {
+    async settle(held, now, reread, alsoIgnore) {
+      if (held === null || held === void 0 || now === null) return void 0;
+      if (used >= LEASE_ONLY_RETRIES || !onlyLeasesDiffer(held, now, alsoIgnore)) return void 0;
+      const bound = Math.min(CONFLICT_BASE_MS * 2 ** Math.min(used, 4), CONFLICT_CAP_MS);
+      used += 1;
+      const sleep = deps.clock?.sleep;
+      if (sleep !== void 0) {
+        await sleep.call(deps.clock, Math.floor((deps.rng?.next() ?? 1) * bound));
+      }
+      return { row: await reread() };
+    }
+  };
+}
+function listOf(entries) {
+  if (entries.length === 0) return void 0;
+  return [...entries].sort(
+    (a, b) => a.generation !== b.generation ? a.generation - b.generation : a.holder < b.holder ? -1 : a.holder > b.holder ? 1 : 0
+  );
+}
+var wait = (deps, bound) => deps.clock.sleep(Math.floor((deps.rng?.next() ?? 1) * bound));
+var heldBy = (row, take) => (row?.leases ?? []).some(
+  (e) => e.holder === take.holder && e.generation === take.generation && e.until === take.until
+);
+async function takeLease(ref, deps, take) {
+  let row = take.row;
+  let held = true;
+  let resends = 0;
+  let unanswered;
+  for (let attempt = 0; attempt < LEASE_CAS_ATTEMPTS; attempt++) {
+    if (row === null) row = await deps.registry.get(ref);
+    if (row === null || row.status === "destroyed" || row.currentGen === null) {
+      throw new NotFoundError(`segment "${ref.segment}" has no generation to lease`);
+    }
+    if (take.generation > row.currentGen) {
+      throw new NotFoundError(
+        `segment "${ref.segment}" generation ${take.generation} cannot be leased: it is not a published generation`
+      );
+    }
+    if (take.current && row.currentGen !== take.generation) return "moved";
+    if (heldBy(row, take)) return { token: row.token, row };
+    const live = liveLeases(row, deps.clock.now()).filter((e) => e.holder !== take.holder);
+    if (live.length >= MAX_LEASES_PER_SEGMENT) {
+      throw new LeaseLimitError(
+        `segment "${ref.segment}" already has ${live.length} live leases, the most one segment records`
+      );
+    }
+    const leases = listOf([
+      ...live,
+      { holder: take.holder, generation: take.generation, until: take.until }
+    ]);
+    const against = row;
+    try {
+      const { token } = await deps.registry.compareAndSwap(
+        ref,
+        against.token,
+        { leases },
+        held ? { held: against } : void 0
+      );
+      return { token, row: against };
+    } catch (err) {
+      if (isWriteConflictError(err)) {
+        row = null;
+        held = false;
+        await wait(deps, Math.min(CONFLICT_BASE_MS * 2 ** attempt, CONFLICT_CAP_MS));
+        continue;
+      }
+      if (!isTransientError(err)) throw err;
+      const now = await deps.registry.get(ref);
+      if (heldBy(now, take)) return { token: now.token, row: against };
+      if (now !== null && now.token === against.token) {
+        if (resends >= UNANSWERED_RESENDS) throw err;
+        await wait(deps, UNANSWERED_BASE_MS * 2 ** resends);
+        resends += 1;
+        unanswered = err;
+      }
+      row = now;
+      held = false;
+      if (row === null)
+        throw new NotFoundError(`segment "${ref.segment}" has no generation to lease`);
+    }
+  }
+  if (unanswered !== void 0) throw unanswered;
+  throw new WriteConflictError(`lease: contention taking a lease on segment "${ref.segment}"`);
+}
+async function releaseLease(ref, deps, holder) {
+  let resends = 0;
+  let unanswered;
+  let row;
+  for (let attempt = 0; attempt < LEASE_CAS_ATTEMPTS; attempt++) {
+    if (row === void 0) row = await deps.registry.get(ref);
+    if (row === null || row.status === "destroyed") return;
+    if (!(row.leases ?? []).some((e) => e.holder === holder)) return;
+    const against = row;
+    const keep = liveLeases(against, deps.clock.now()).filter((e) => e.holder !== holder);
+    try {
+      await deps.registry.compareAndSwap(ref, against.token, { leases: listOf(keep) });
+      return;
+    } catch (err) {
+      if (isWriteConflictError(err)) {
+        row = void 0;
+        await wait(deps, Math.min(CONFLICT_BASE_MS * 2 ** attempt, CONFLICT_CAP_MS));
+        continue;
+      }
+      if (!isTransientError(err)) throw err;
+      const now = await deps.registry.get(ref);
+      if (now === null || !(now.leases ?? []).some((e) => e.holder === holder)) return;
+      if (now.token === against.token) {
+        if (resends >= UNANSWERED_RESENDS) throw err;
+        await wait(deps, UNANSWERED_BASE_MS * 2 ** resends);
+        resends += 1;
+        unanswered = err;
+      }
+      row = now;
+    }
+  }
+  if (unanswered !== void 0) throw unanswered;
+  throw new WriteConflictError(`lease: contention releasing a lease on segment "${ref.segment}"`);
+}
+
 // src/core/validate.ts
 var CHUNK_KEY_MAX = 65535;
 var MAX_NAME_LENGTH = 256;
@@ -263,6 +474,27 @@ function namespacePathPart(namespace) {
   return namespace === void 0 ? DEFAULT_NAMESPACE : encodeNameForPath(namespace);
 }
 
+// src/core/kept-generations.ts
+var MAX_KEPT_GENERATIONS = 64;
+var MAX_STORED_KEPT_GENERATIONS = 256;
+function usableKeptGens(record) {
+  const list = record?.keptGens;
+  if (record === null || list === void 0 || record.currentGen === null) return void 0;
+  for (const g of list) if (g >= record.currentGen) return void 0;
+  return list;
+}
+function nextKept(prev, generation, keep) {
+  const none = { list: void 0, evict: [] };
+  if (keep === void 0 || keep > MAX_KEPT_GENERATIONS) return none;
+  if (generation === 0) return { list: [], evict: [] };
+  const previous = prev?.currentGen ?? null;
+  const known = usableKeptGens(prev);
+  if (previous === null || known === void 0) return none;
+  const all = [...known, previous];
+  const cut = Math.max(0, all.length - keep);
+  return { list: all.slice(cut), evict: all.slice(0, cut) };
+}
+
 // src/core/metadata.ts
 var MAX_METADATA_BYTES = 1024;
 var MAX_METADATA_KEY_BYTES = 128;
@@ -341,21 +573,9 @@ function metadataFromBytes(bytes, fail) {
   return Object.freeze(parsed);
 }
 
-// src/core/token.ts
-var INCARNATION_TOKEN = /^([0-9a-f]{32})\.(0|[1-9]\d*)\.([0-9a-f]{16})$/;
-function incarnationOf(token) {
-  return INCARNATION_TOKEN.exec(token)?.[1];
-}
-function sameIncarnation(a, b) {
-  const ia = incarnationOf(a.token);
-  const ib = incarnationOf(b.token);
-  if (ia !== void 0 || ib !== void 0) return ia === ib;
-  return a.createdAt === b.createdAt;
-}
-
 // src/drivers/_shared/registry.ts
 var STATUSES = ["active", "destroyed"];
-var RECORD_FIELDS = [
+var BASE_FIELDS = [
   "namespace",
   "segment",
   "currentGen",
@@ -369,7 +589,13 @@ var RECORD_FIELDS = [
   "updatedAt",
   "token"
 ];
-var SCHEMA_1_RECORD_FIELDS = RECORD_FIELDS.filter((f) => f !== "summary");
+var SCHEMA_3_FIELDS = ["keptGens", "leases"];
+var RECORD_FIELDS = [...BASE_FIELDS, ...SCHEMA_3_FIELDS];
+function fieldsOf(schemaVersion) {
+  if (schemaVersion >= 3) return RECORD_FIELDS;
+  const base = BASE_FIELDS;
+  return schemaVersion === 2 ? base : base.filter((f) => f !== "summary");
+}
 var ENVELOPE_FIELDS = ["schemaVersion", "deleted", "record"];
 var MAX_GOVERNANCE_BYTES = 64 * 1024;
 var MAX_WRAPPED_DEKS = 8;
@@ -514,17 +740,103 @@ function validateSummaryKeys(summary, wrappedDeks) {
     );
   }
 }
+function validateKeptGens(value, isStored, ctx) {
+  if (value === void 0) return void 0;
+  const fail = (msg) => {
+    const where = ctx === void 0 ? "" : `: ${ctx}`;
+    throw isStored ? new IntegrityError(`registry record keptGens: ${msg}${where}`) : new ValidationError(`keptGens: ${msg}`);
+  };
+  if (!Array.isArray(value)) fail("must be an array");
+  const list = value;
+  const max = isStored ? MAX_STORED_KEPT_GENERATIONS : MAX_KEPT_GENERATIONS;
+  if (list.length > max) fail(`has ${list.length} entries, cap ${max}`);
+  let last = -1;
+  for (const g of list) {
+    if (!Number.isSafeInteger(g) || g < 0) {
+      fail(`entries must be non-negative safe integers (got ${String(g)})`);
+    }
+    if (g <= last) fail("entries must be strictly ascending");
+    last = g;
+  }
+  return isStored ? list : Object.freeze([...list]);
+}
+var HOLDER = /^[0-9a-f]{16}$/;
+var LEASE_ENTRY_KEYS = ["holder", "generation", "until"];
+function validateLeases(value, isStored, ctx) {
+  if (value === void 0) return void 0;
+  const fail = (msg) => {
+    const where = ctx === void 0 ? "" : `: ${ctx}`;
+    throw isStored ? new IntegrityError(`registry record leases: ${msg}${where}`) : new ValidationError(`leases: ${msg}`);
+  };
+  if (!Array.isArray(value)) fail("must be an array");
+  const list = value;
+  const max = MAX_STORED_LEASES;
+  if (list.length > max) fail(`has ${list.length} entries, cap ${max}`);
+  const seen = /* @__PURE__ */ new Set();
+  const out = [];
+  for (const e of list) {
+    if (typeof e !== "object" || e === null || Array.isArray(e)) fail("an entry must be an object");
+    const entry = e;
+    const extra = Object.keys(entry).filter((k) => !LEASE_ENTRY_KEYS.includes(k));
+    if (extra.length > 0) fail(`an entry carries an undeclared field (${extra.join(", ")})`);
+    const { holder, generation, until } = entry;
+    if (typeof holder !== "string" || !HOLDER.test(holder)) {
+      fail("a holder must be 16 lowercase hex digits");
+    }
+    if (seen.has(holder)) fail("holders must be unique");
+    seen.add(holder);
+    for (const [name, n] of [
+      ["generation", generation],
+      ["until", until]
+    ]) {
+      if (!Number.isSafeInteger(n) || n < 0) {
+        fail(`${name} must be a non-negative safe integer (got ${String(n)})`);
+      }
+    }
+    out.push(
+      isStored ? entry : Object.freeze({
+        holder,
+        generation,
+        until
+      })
+    );
+  }
+  if (isStored) return out;
+  return out.length === 0 ? void 0 : Object.freeze(out);
+}
+function validateLeasesPointer(leases, currentGen) {
+  if (leases !== void 0 && leases.length > 0 && currentGen === null) {
+    throw new ValidationError("leases: a row with no pointer has no generation to lease");
+  }
+}
+function validateKeptGensBelow(keptGens, currentGen) {
+  if (keptGens === void 0) return;
+  if (currentGen === null) {
+    throw new ValidationError(
+      "keptGens: a row with no pointer has no generations below it to keep"
+    );
+  }
+  const top = keptGens[keptGens.length - 1];
+  if (top !== void 0 && top >= currentGen) {
+    throw new ValidationError(
+      `keptGens names generation ${top}, which is not below the row's pointer ${currentGen}`
+    );
+  }
+}
 function validateNewRegistryRecord(rec) {
   validateGeneration(rec.currentGen);
   if (rec.status !== void 0) validateStatus(rec.status);
   validateWrappedDeks(rec.wrappedDeks, false);
   validateGovernance(rec.retention, "retention");
   validateGovernance(rec.residency, "residency");
-  if (!("summary" in rec)) return rec;
+  const keptGens = validateKeptGens(rec.keptGens, false);
+  validateKeptGensBelow(keptGens, rec.currentGen);
+  const withKept = keptGens === void 0 ? rec : { ...rec, keptGens };
+  if (!("summary" in rec)) return withKept;
   const summary = validateSummary(rec.summary, false);
   validateSummaryNames(summary, rec.currentGen);
   validateSummaryKeys(summary, rec.wrappedDeks);
-  return { ...rec, summary };
+  return { ...withKept, summary };
 }
 function validateRegistryPatch(patch) {
   validatePatchGeneration(patch);
@@ -532,10 +844,12 @@ function validateRegistryPatch(patch) {
   if ("wrappedDeks" in patch) validateWrappedDeks(patch.wrappedDeks, false);
   if ("retention" in patch) validateGovernance(patch.retention, "retention");
   if ("residency" in patch) validateGovernance(patch.residency, "residency");
-  if (!("summary" in patch)) return patch;
-  return { ...patch, summary: validateSummary(patch.summary, false) };
+  const withKept = patch.keptGens === void 0 ? patch : { ...patch, keptGens: validateKeptGens(patch.keptGens, false) };
+  const withLeases = "leases" in withKept ? { ...withKept, leases: validateLeases(withKept.leases, false) } : withKept;
+  if (!("summary" in patch)) return withLeases;
+  return { ...withLeases, summary: validateSummary(patch.summary, false) };
 }
-var REGISTRY_SCHEMA_VERSION = 2;
+var REGISTRY_SCHEMA_VERSION = 3;
 var OLDEST_REGISTRY_SCHEMA_VERSION = 1;
 function assertRegistrySchemaVersion(raw, ctx) {
   if (raw === void 0) {
@@ -644,6 +958,9 @@ function recordFromNew(ref, rec, now, token) {
     retention: rec.retention,
     residency: rec.residency,
     summary: rec.summary,
+    keptGens: rec.keptGens,
+    // A new row has no holder: a lease is written only against a row that already exists.
+    leases: void 0,
     createdAt: now,
     updatedAt: now,
     token
@@ -659,7 +976,7 @@ function assertStoredRecordShape(r, ctx, schemaVersion = REGISTRY_SCHEMA_VERSION
   if (!STATUSES.includes(r.status)) {
     throw new IntegrityError(`registry record has an unknown status (${r.status}): ${ctx}`);
   }
-  const declared = schemaVersion >= 2 ? RECORD_FIELDS : SCHEMA_1_RECORD_FIELDS;
+  const declared = fieldsOf(schemaVersion);
   const extra = Object.keys(r).filter((k) => !declared.includes(k));
   if (extra.length > 0) {
     throw new IntegrityError(
@@ -677,6 +994,8 @@ function assertStoredRecordShape(r, ctx, schemaVersion = REGISTRY_SCHEMA_VERSION
     }
   }
   validateSummary(r.summary, true, ctx);
+  validateKeptGens(r.keptGens, true, ctx);
+  validateLeases(r.leases, true, ctx);
 }
 function applyRegistryPatch(prev, patch, now, token) {
   const currentGen = "currentGen" in patch ? patch.currentGen ?? null : prev.currentGen;
@@ -690,6 +1009,24 @@ function applyRegistryPatch(prev, patch, now, token) {
     const kept = currentGen === prev.currentGen ? prev.summary : void 0;
     summary = kept !== void 0 && summaryAgreesWithKeys(kept, wrappedDeks) ? kept : void 0;
   }
+  let keptGens;
+  if ("keptGens" in patch) {
+    validateKeptGensBelow(patch.keptGens, currentGen);
+    keptGens = patch.keptGens;
+  } else {
+    keptGens = currentGen === prev.currentGen ? prev.keptGens : void 0;
+  }
+  let leases;
+  if ("leases" in patch) {
+    leases = patch.leases;
+    validateLeasesPointer(leases, currentGen);
+    const most = Math.max(MAX_LEASES_PER_SEGMENT, prev.leases?.length ?? 0);
+    if (leases !== void 0 && leases.length > most) {
+      throw new ValidationError(`leases: has ${leases.length} entries, cap ${most}`);
+    }
+  } else {
+    leases = prev.leases;
+  }
   return {
     namespace: prev.namespace,
     segment: prev.segment,
@@ -700,6 +1037,8 @@ function applyRegistryPatch(prev, patch, now, token) {
     retention: "retention" in patch ? patch.retention : prev.retention,
     residency: "residency" in patch ? patch.residency : prev.residency,
     summary,
+    keptGens,
+    leases,
     createdAt: prev.createdAt,
     updatedAt: now,
     token
@@ -730,6 +1069,9 @@ export {
   WriteConflictError,
   IntegrityError,
   NotFoundError,
+  LeaseExpiredError,
+  LeaseLimitError,
+  StaleOperandError,
   UnsupportedError,
   CapabilityError,
   BudgetExceededError,
@@ -738,6 +1080,9 @@ export {
   isCloudRoaringError,
   isWriteConflictError,
   isTransientError,
+  isLeaseExpiredError,
+  isStaleOperandError,
+  isLeaseLimitError,
   isNotFoundError,
   isIntegrityError,
   isValidationError,
@@ -745,6 +1090,20 @@ export {
   decodeNameFromKey,
   encodeNameForPath,
   decodeNameFromPath,
+  MAX_KEPT_GENERATIONS,
+  usableKeptGens,
+  nextKept,
+  incarnationOf,
+  sameIncarnation,
+  MAX_LEASE_MS,
+  LEASE_SKEW_MS,
+  MAX_LEASES_PER_SEGMENT,
+  isLive,
+  heldGenerations,
+  onlyLeasesDiffer,
+  leaseChurn,
+  takeLease,
+  releaseLease,
   MAX_NAME_LENGTH,
   encodedNameLength,
   validateSegmentRef,
@@ -764,8 +1123,6 @@ export {
   metadataBytes,
   copiedMetadata,
   metadataFromBytes,
-  incarnationOf,
-  sameIncarnation,
   validateNewRegistryRecord,
   validateRegistryPatch,
   serializeRegistryEnvelope,
@@ -782,4 +1139,4 @@ export {
   namespaceKeyPart,
   namespacePathPart
 };
-//# sourceMappingURL=chunk-LFUNPMXZ.js.map
+//# sourceMappingURL=chunk-CCP4U32U.js.map