@bjornpagen/bumbledb-log 0.18.0 → 0.19.0

package/src/tenants.ts

@@ -2,19 +2,36 @@
  * Per-tenant replicas (50, case 4): an LRU of replicas keyed by tenant
  * id — a tenant is a prefix (`<root>/t/<tenant>`), eviction closes and
  * deletes the local dir (the disposable law), and `t/_shared` is
- * pinned. Braids shard within a tenant; tenants shard the world.
+ * pinned. Braids shard within a tenant; tenants shard the world. A
+ * tenant id is one StoreKey segment. `get` returns a live handle whose
+ * refcount pins it against eviction for the duration of the borrow
+ * (findings 38, 71) — the pin outlives `get` and drops only on
+ * `release`; a disposed handle is a distinct type. One fenced lease
+ * owns each replica directory and is CAS-renewed while the slot is
+ * open, so a second live replica on that dir is unrepresentable
+ * (findings 39, 48).
  */
 
 import * as fs from "node:fs/promises"
 import * as path from "node:path"
 import type { Schema, SchemaRelations } from "@bjornpagen/bumbledb"
 import * as errors from "@superbuilders/errors"
+import { regex } from "arkregex"
 import { tenantPrefix } from "#keys.ts"
 import type { Replica } from "#replica.ts"
 import { openReplica } from "#replica.ts"
-import type { ObjectStore } from "#store.ts"
+import type { FsLease, ObjectStore } from "#store.ts"
+import { acquireFsLease, releaseFsLease } from "#store.ts"
 
 const PINNED_TENANT = "_shared"
+const SIGNED_DECIMAL = regex("^-?\\d+$")
+const UNSIGNED_DECIMAL = regex("^\\d+$")
+const TENANT_ID = regex("^[A-Za-z0-9._-]+$")
+
+/** Directory-lease lifetime: one owner per replica directory. The pool
+ *  CAS-extends `expires` at one-third this TTL while the slot is open,
+ *  so expiry cannot mint a second owner under a live replica. */
+const DIR_LEASE_MS = 300_000
 
 interface OpenTenantsOptions<Rels extends SchemaRelations> {
 	readonly store: ObjectStore
@@ -26,17 +43,117 @@ interface OpenTenantsOptions<Rels extends SchemaRelations> {
 	 *  admission is not re-weighed until it is evicted and re-opened. */
 	readonly budgetBytes?: number
 	readonly maxOpen?: number
+	/** Directory-lease TTL. Renewed at one-third this value while the
+	 *  replica is open. Default 300_000. */
+	readonly dirLeaseMs?: number
+}
+
+const liveHandleBrand: unique symbol = Symbol("liveHandle")
+const disposedHandleBrand: unique symbol = Symbol("disposedHandle")
+
+type LiveHandle<Rels extends SchemaRelations> = Replica<Rels> & {
+	readonly [liveHandleBrand]: typeof liveHandleBrand
+	/** Drop one borrow. LRU and `evict` become legal only when `refs`
+	 *  reaches 0 — not when `get` returns. */
+	release(): void
+}
+
+/** A handle whose replica is gone. Every verb is a compile-time
+ *  refusal — there is no replica field to call, so `waitFor` into a
+ *  disposed replica is a type error. */
+type DisposedHandle = {
+	readonly [disposedHandleBrand]: typeof disposedHandleBrand
 }
 
 interface Tenants<Rels extends SchemaRelations> extends AsyncDisposable {
-	get(tenant: string): Promise<Replica<Rels>>
+	get(tenant: string): Promise<LiveHandle<Rels>>
+	/** Evicts one tenant: closes the replica and deletes its directory.
+	 *  `_shared` and a still-pinned borrow refuse by doing nothing. */
+	evict(tenant: string): Promise<DisposedHandle | null>
+	/** Drop one `get` borrow for `tenant`. */
+	release(tenant: string): void
 }
 
 interface TenantSlot<Rels extends SchemaRelations> {
-	readonly replica: Replica<Rels>
+	readonly replica: LiveHandle<Rels>
 	readonly dir: string
+	readonly lease: FsLease
 	bytes: number
 	lastUsed: number
+	refs: number
+	leaseLost?: Error
+}
+
+function codeOf(error: Error): string | undefined {
+	return (error as NodeJS.ErrnoException).code
+}
+
+function encodeLease(holder: bigint, token: bigint, expires: bigint): Uint8Array {
+	return new TextEncoder().encode(`${holder}\n${token}\n${expires}\n`)
+}
+
+function parseLease(raw: string): { holder: bigint; token: bigint; expires: bigint } | null {
+	const lines = raw.trim().split("\n")
+	if (lines.length !== 3) {
+		return null
+	}
+	const [holderLine, tokenLine, expiresLine] = lines
+	if (holderLine === undefined || tokenLine === undefined || expiresLine === undefined) {
+		return null
+	}
+	if (!SIGNED_DECIMAL.test(holderLine) || !UNSIGNED_DECIMAL.test(tokenLine) || !SIGNED_DECIMAL.test(expiresLine)) {
+		return null
+	}
+	return { holder: BigInt(holderLine), token: BigInt(tokenLine), expires: BigInt(expiresLine) }
+}
+
+async function fsyncDir(dir: string): Promise<void> {
+	const handle = await fs.open(dir, "r")
+	const synced = await errors.try(handle.sync())
+	await handle.close()
+	if (synced.error) {
+		throw errors.wrap(synced.error, `fsync directory ${dir}`)
+	}
+}
+
+/** CAS-extend `expires` of a token we already hold. A new token would
+ *  be a second owner; we rewrite the same path so identity does not
+ *  change. */
+async function renewDirLease(held: FsLease, ttlMs: number): Promise<void> {
+	const read = await errors.try(fs.readFile(held.path, "utf8"))
+	if (read.error) {
+		if (codeOf(read.error) === "ENOENT") {
+			return
+		}
+		throw read.error
+	}
+	const lease = parseLease(read.data)
+	if (lease === null || lease.holder !== held.holder || lease.token !== held.token) {
+		throw errors.new("directory lease is no longer ours")
+	}
+	const body = encodeLease(held.holder, held.token, BigInt(Date.now() + ttlMs))
+	const tmp = `${held.path}.renew.${process.pid}`
+	const file = await fs.open(tmp, "w")
+	const written = await errors.try(
+		(async function writeAll() {
+			await file.writeFile(body)
+			await file.sync()
+		})()
+	)
+	await file.close()
+	if (written.error) {
+		await fs.rm(tmp, { force: true })
+		throw written.error
+	}
+	const replaced = await errors.try(fs.rename(tmp, held.path))
+	if (replaced.error) {
+		await fs.rm(tmp, { force: true })
+		if (codeOf(replaced.error) === "ENOENT") {
+			return
+		}
+		throw replaced.error
+	}
+	await fsyncDir(held.dir)
 }
 
 async function directoryBytes(dir: string): Promise<number> {
@@ -57,19 +174,101 @@ async function directoryBytes(dir: string): Promise<number> {
 }
 
 function checkTenantId(tenant: string): void {
-	if (!/^[A-Za-z0-9._-]+$/.test(tenant)) {
+	if (!TENANT_ID.test(tenant)) {
 		throw errors.new(`tenant id is not a single path segment: ${tenant}`)
 	}
 }
 
+function asDisposed(): DisposedHandle {
+	return { [disposedHandleBrand]: disposedHandleBrand }
+}
+
+async function disposeSlot<Rels extends SchemaRelations>(slot: TenantSlot<Rels>): Promise<void> {
+	await slot.replica[Symbol.asyncDispose]()
+	await fs.rm(slot.dir, { recursive: true, force: true })
+	await releaseFsLease(slot.lease)
+}
+
 function openTenants<Rels extends SchemaRelations>(options: OpenTenantsOptions<Rels>): Tenants<Rels> {
 	const budgetBytes = options.budgetBytes ?? 400_000_000
 	const maxOpen = options.maxOpen ?? 32
+	const dirLeaseMs = options.dirLeaseMs ?? DIR_LEASE_MS
+	if (dirLeaseMs <= 0) {
+		throw errors.new("dirLeaseMs must be positive")
+	}
+	const renewEveryMs = Math.max(1, Math.floor(dirLeaseMs / 3))
 	const open = new Map<string, TenantSlot<Rels>>()
+	const opening = new Map<string, Promise<LiveHandle<Rels>>>()
 	let tick = 0
 	let closed = false
+	let renewTimer: ReturnType<typeof setInterval> | undefined
+	let leaseGate = Promise.resolve()
+
+	function withLeaseGate<T>(body: () => Promise<T>): Promise<T> {
+		const run = leaseGate.then(body, body)
+		leaseGate = run.then(
+			function absorb() {
+				return undefined
+			},
+			function absorbFailure() {
+				return undefined
+			}
+		)
+		return run
+	}
+
+	function dropBorrow(tenant: string): void {
+		if (closed) {
+			throw errors.new("tenants pool is disposed")
+		}
+		const slot = open.get(tenant)
+		if (slot === undefined || slot.refs <= 0) {
+			throw errors.new(`no live borrow for tenant ${tenant}`)
+		}
+		slot.refs -= 1
+	}
+
+	function brandLive(replica: Replica<Rels>, tenant: string): LiveHandle<Rels> {
+		const handle = replica as LiveHandle<Rels>
+		Object.defineProperty(handle, liveHandleBrand, { value: liveHandleBrand })
+		Object.defineProperty(handle, "release", {
+			value: function release() {
+				dropBorrow(tenant)
+			},
+			enumerable: false
+		})
+		return handle
+	}
 
-	async function evictUntilWithin(): Promise<void> {
+	function armRenew(): void {
+		if (renewTimer !== undefined) {
+			return
+		}
+		renewTimer = setInterval(function tickRenew() {
+			void errors.try(renewAllOpen())
+		}, renewEveryMs)
+	}
+
+	function disarmRenew(): void {
+		if (open.size > 0 || renewTimer === undefined) {
+			return
+		}
+		clearInterval(renewTimer)
+		renewTimer = undefined
+	}
+
+	async function renewAllOpen(): Promise<void> {
+		await withLeaseGate(async function renewHeld() {
+			for (const [tenant, slot] of open) {
+				const result = await errors.try(renewDirLease(slot.lease, dirLeaseMs))
+				if (result.error !== undefined && open.get(tenant) === slot) {
+					slot.leaseLost = result.error
+				}
+			}
+		})
+	}
+
+	async function evictUntilWithin(keep: string): Promise<void> {
 		for (;;) {
 			let bytes = 0
 			for (const slot of open.values()) {
@@ -81,7 +280,7 @@ function openTenants<Rels extends SchemaRelations>(options: OpenTenantsOptions<R
 			let victim: string | null = null
 			let oldest = Number.POSITIVE_INFINITY
 			for (const [tenant, slot] of open) {
-				if (tenant === PINNED_TENANT) {
+				if (tenant === PINNED_TENANT || tenant === keep || slot.refs > 0) {
 					continue
 				}
 				if (slot.lastUsed < oldest) {
@@ -95,12 +294,70 @@ function openTenants<Rels extends SchemaRelations>(options: OpenTenantsOptions<R
 			const slot = open.get(victim)
 			open.delete(victim)
 			if (slot !== undefined) {
-				await slot.replica[Symbol.asyncDispose]()
-				await fs.rm(slot.dir, { recursive: true, force: true })
+				await withLeaseGate(function disposeVictim() {
+					return disposeSlot(slot)
+				})
+			}
+		}
+	}
+
+	/** Increment the borrow. The pin outlives `get` — a `finally`
+	 *  decrement here would make LRU/`evict` legal while the caller
+	 *  still holds the LiveHandle (finding 38). Decrement only if this
+	 *  `get` fails before the handle is in the caller's hands. */
+	async function pin(slot: TenantSlot<Rels>, tenant: string): Promise<LiveHandle<Rels>> {
+		if (slot.leaseLost !== undefined) {
+			throw slot.leaseLost
+		}
+		slot.refs += 1
+		slot.lastUsed = tick
+		try {
+			await evictUntilWithin(tenant)
+			const kept = open.get(tenant)
+			if (kept === undefined) {
+				throw errors.new("tenants pool evicted the handle it is returning")
 			}
+			await withLeaseGate(function renewOnPin() {
+				return renewDirLease(kept.lease, dirLeaseMs)
+			})
+			return kept.replica
+		} catch (error) {
+			slot.refs -= 1
+			throw error
 		}
 	}
 
+	async function openOne(tenant: string): Promise<LiveHandle<Rels>> {
+		const dir = path.join(options.dir, tenant)
+		const lease = await acquireFsLease(dir, "dir", dirLeaseMs, "refuse")
+		let replica: LiveHandle<Rels>
+		try {
+			replica = brandLive(
+				await openReplica({
+					store: options.store,
+					prefix: tenantPrefix(options.root, tenant),
+					dir,
+					theory: options.theory
+				}),
+				tenant
+			)
+		} catch (error) {
+			await releaseFsLease(lease)
+			throw error
+		}
+		const slot: TenantSlot<Rels> = {
+			replica,
+			dir,
+			lease,
+			bytes: await directoryBytes(dir),
+			lastUsed: tick,
+			refs: 0
+		}
+		open.set(tenant, slot)
+		armRenew()
+		return await pin(slot, tenant)
+	}
+
 	return {
 		async get(tenant) {
 			if (closed) {
@@ -110,31 +367,70 @@ function openTenants<Rels extends SchemaRelations>(options: OpenTenantsOptions<R
 			tick += 1
 			const hit = open.get(tenant)
 			if (hit !== undefined) {
-				hit.lastUsed = tick
-				return hit.replica
-			}
-			const dir = path.join(options.dir, tenant)
-			const replica = await openReplica({
-				store: options.store,
-				prefix: tenantPrefix(options.root, tenant),
-				dir,
-				theory: options.theory
+				return await pin(hit, tenant)
+			}
+			const inflight = opening.get(tenant)
+			if (inflight !== undefined) {
+				const ran = await errors.try(inflight)
+				if (ran.error) {
+					throw ran.error
+				}
+				const slot = open.get(tenant)
+				if (slot === undefined) {
+					throw errors.new("tenants pool dropped the tenant during open")
+				}
+				return await pin(slot, tenant)
+			}
+			const pending = openOne(tenant)
+			opening.set(tenant, pending)
+			const ran = await errors.try(pending)
+			opening.delete(tenant)
+			if (ran.error) {
+				throw ran.error
+			}
+			return ran.data
+		},
+
+		async evict(tenant) {
+			if (closed) {
+				throw errors.new("tenants pool is disposed")
+			}
+			checkTenantId(tenant)
+			if (tenant === PINNED_TENANT) {
+				return null
+			}
+			const slot = open.get(tenant)
+			if (slot === undefined || slot.refs > 0) {
+				return null
+			}
+			open.delete(tenant)
+			await withLeaseGate(function disposeEvicted() {
+				return disposeSlot(slot)
 			})
-			const slot: TenantSlot<Rels> = { replica, dir, bytes: await directoryBytes(dir), lastUsed: tick }
-			open.set(tenant, slot)
-			await evictUntilWithin()
-			return replica
+			disarmRenew()
+			return asDisposed()
+		},
+
+		release(tenant) {
+			dropBorrow(tenant)
 		},
 
 		async [Symbol.asyncDispose]() {
 			closed = true
-			for (const slot of open.values()) {
-				await slot.replica[Symbol.asyncDispose]()
+			if (renewTimer !== undefined) {
+				clearInterval(renewTimer)
+				renewTimer = undefined
 			}
-			open.clear()
+			await withLeaseGate(async function disposePool() {
+				for (const slot of open.values()) {
+					await releaseFsLease(slot.lease)
+					await slot.replica[Symbol.asyncDispose]()
+				}
+				open.clear()
+			})
 		}
 	}
 }
 
-export type { OpenTenantsOptions, Tenants }
+export type { DisposedHandle, LiveHandle, OpenTenantsOptions, Tenants }
 export { openTenants }

package/src/value.ts

@@ -19,6 +19,41 @@ interface Interval {
 
 type Value = boolean | bigint | string | Uint8Array | Interval
 
+/** A string cell: well-formed UTF-8 by construction. A lone surrogate cannot enter. */
+declare const wellFormedUtf8Brand: unique symbol
+type WellFormedUtf8 = string & { readonly [wellFormedUtf8Brand]: typeof wellFormedUtf8Brand }
+
+/** Fatal encoder: refuses lone surrogates rather than emitting U+FFFD. */
+function wellFormedUtf8(text: string): WellFormedUtf8 {
+	if (!text.isWellFormed()) {
+		throw errors.new("string cell is not well-formed UTF-8")
+	}
+	return text as WellFormedUtf8
+}
+
+function parseWellFormedUtf8(raw: Uint8Array): WellFormedUtf8 | undefined {
+	const decoded = errors.trySync(function decodeUtf8() {
+		return utf8StrictDecoder.decode(raw)
+	})
+	if (decoded.error) {
+		return undefined
+	}
+	return decoded.data as WellFormedUtf8
+}
+
+function domainCeiling(element: "u64" | "i64"): bigint {
+	return element === "u64" ? U64_MAX : I64_MAX
+}
+
+/** Fixed-width `[start, start + width)`; the domain ceiling is not a value. */
+function fixedInterval(start: bigint, width: bigint, element: "u64" | "i64"): Interval | undefined {
+	const end = start + width
+	if (end <= start || end >= domainCeiling(element)) {
+		return undefined
+	}
+	return { start, end }
+}
+
 /** 20's tag table: the codec's own numbering, normative to the byte. */
 const TAG = {
 	bool: 0,
@@ -72,9 +107,10 @@ function checkAgainst(context: string, type: ValueTypeSpec, value: Value): void
 			return
 		}
 		case "string": {
-			if (typeof value !== "string" || !value.isWellFormed()) {
+			if (typeof value !== "string") {
 				throw errors.new(`${context}: expected well-formed string`)
 			}
+			wellFormedUtf8(value)
 			return
 		}
 		case "fixedBytes": {
@@ -92,8 +128,14 @@ function checkAgainst(context: string, type: ValueTypeSpec, value: Value): void
 			if (value.start < lo || value.end > hi || value.start >= value.end) {
 				throw errors.new(`${context}: interval bounds out of range or empty`)
 			}
-			if (type.width !== undefined && value.end - value.start !== type.width) {
-				throw errors.new(`${context}: interval width must be ${type.width}`)
+			if (type.width !== undefined) {
+				const parsed = fixedInterval(value.start, type.width, type.element)
+				if (parsed === undefined) {
+					throw errors.new(`${context}: fixed interval end is the domain ceiling`)
+				}
+				if (parsed.end !== value.end) {
+					throw errors.new(`${context}: interval width must be ${type.width}`)
+				}
 			}
 			return
 		}
@@ -119,7 +161,8 @@ function writeTagged(out: ByteWriter, type: ValueTypeSpec, value: Value): void {
 			return
 		}
 		case "string": {
-			const raw = utf8Encoder.encode(value as string)
+			const text = wellFormedUtf8(value as string)
+			const raw = utf8Encoder.encode(text)
 			out.u8(TAG.string)
 			out.u32le(raw.length)
 			out.bytes(raw)
@@ -186,13 +229,11 @@ function readTagged(reader: ByteReader, type: ValueTypeSpec, refusal: TaggedRefu
 		case "string": {
 			const len = reader.u32le("string length")
 			const raw = reader.bytes(len, "string payload")
-			const decoded = errors.trySync(function decodeUtf8() {
-				return utf8StrictDecoder.decode(raw)
-			})
-			if (decoded.error) {
+			const text = parseWellFormedUtf8(raw)
+			if (text === undefined) {
 				refusal.invalidUtf8()
 			}
-			return decoded.data
+			return text
 		}
 		case "fixedBytes":
 			return reader.bytes(type.len, "fixedBytes payload")
@@ -206,11 +247,11 @@ function readTagged(reader: ByteReader, type: ValueTypeSpec, refusal: TaggedRefu
 				return { start, end }
 			}
 			const start = type.element === "u64" ? reader.u64le("interval start") : reader.i64le("interval start")
-			const end = start + type.width
-			if (type.element === "u64" ? end > U64_MAX : end > I64_MAX) {
+			const parsed = fixedInterval(start, type.width, type.element)
+			if (parsed === undefined) {
 				refusal.intervalOverflow()
 			}
-			return { start, end }
+			return parsed
 		}
 	}
 }
@@ -281,5 +322,15 @@ function writeCanonicalLiteral(out: ByteWriter, type: ValueTypeSpec, value: Valu
 	}
 }
 
-export type { Interval, TaggedRefusal, Value }
-export { checkAgainst, isInterval, readTagged, TAG, valuesEqual, wireTagOf, writeCanonicalLiteral, writeTagged }
+export type { Interval, TaggedRefusal, Value, WellFormedUtf8 }
+export {
+	checkAgainst,
+	isInterval,
+	readTagged,
+	TAG,
+	valuesEqual,
+	wellFormedUtf8,
+	wireTagOf,
+	writeCanonicalLiteral,
+	writeTagged
+}