@powerhousedao/reactor-attachments 6.1.0 → 6.2.0-dev.0

package/dist/index.js

@@ -1,3 +1,4 @@
+import { _ as SizeMismatch, a as RemoteAttachmentUpload, c as AttachmentService, d as AttachmentAlreadyExists, f as AttachmentNotFound, g as ReservationNotFound, h as InvalidAttachmentRef, i as RemoteAttachmentUploadFactory, l as createRef, m as HashMismatch, n as createRemoteAttachmentService, o as RemoteReservationStore, p as AttachmentPending, r as RemoteAttachmentStore, s as SwitchboardAttachmentTransport, t as NullAttachmentTransport, u as parseRef, v as UploadTooLarge } from "./null-attachment-transport-Drx03s02.js";
 import { dirname, join } from "node:path";
 import { Migrator, sql } from "kysely";
 import { mkdir, rename, rm } from "node:fs/promises";
@@ -16,83 +17,6 @@ var __exportAll = (all, no_symbols) => {
 	return target;
 };
 //#endregion
-//#region src/errors.ts
-/**
-* Thrown when an attachment ref or hash is not known to the store.
-*/
-var AttachmentNotFound = class extends Error {
-	constructor(identifier) {
-		super(`Attachment not found: ${identifier}`);
-		this.name = "AttachmentNotFound";
-	}
-};
-/**
-* Thrown when a reservation ID is not found in the reservation store.
-*/
-var ReservationNotFound = class extends Error {
-	constructor(reservationId) {
-		super(`Reservation not found: ${reservationId}`);
-		this.name = "ReservationNotFound";
-	}
-};
-/**
-* Thrown when an attachment ref string does not match the expected format.
-*/
-var InvalidAttachmentRef = class extends Error {
-	constructor(ref) {
-		super(`Invalid attachment ref: ${ref}`);
-		this.name = "InvalidAttachmentRef";
-	}
-};
-/**
-* Thrown when an upload exceeds the configured maximum byte cap.
-* Route handlers should map this to HTTP 413 Payload Too Large.
-*/
-var UploadTooLarge = class extends Error {
-	maxBytes;
-	constructor(maxBytes) {
-		super(`Upload exceeds maximum size of ${maxBytes} bytes`);
-		this.name = "UploadTooLarge";
-		this.maxBytes = maxBytes;
-	}
-};
-//#endregion
-//#region src/ref.ts
-const REF_PATTERN = /^attachment:\/\/v(\d+):(.+)$/;
-const DEFAULT_VERSION = 1;
-function parseRef(ref) {
-	const match = REF_PATTERN.exec(ref);
-	if (!match) throw new InvalidAttachmentRef(ref);
-	return {
-		version: Number(match[1]),
-		hash: match[2]
-	};
-}
-function createRef(hash, version = DEFAULT_VERSION) {
-	return `attachment://v${version}:${hash}`;
-}
-//#endregion
-//#region src/attachment-service.ts
-var AttachmentService = class {
-	constructor(store, reservations, uploadFactory) {
-		this.store = store;
-		this.reservations = reservations;
-		this.uploadFactory = uploadFactory;
-	}
-	async reserve(options) {
-		const reservation = await this.reservations.create(options);
-		return this.uploadFactory.createUpload(reservation.reservationId, options);
-	}
-	async stat(ref) {
-		const { hash } = parseRef(ref);
-		return this.store.stat(hash);
-	}
-	async get(ref, signal) {
-		const { hash } = parseRef(ref);
-		return this.store.get(hash, signal);
-	}
-};
-//#endregion
 //#region src/storage/fs/attachment-fs.ts
 /**
 * Compute the relative storage path for an attachment hash.
@@ -115,13 +39,24 @@ async function writeAttachmentBytes(path, data) {
 			const { done, value } = await reader.read();
 			if (done) break;
 			bytesWritten += value.byteLength;
-			if (!writer.write(value)) await new Promise((resolve) => writer.once("drain", resolve));
+			if (!writer.write(value)) await new Promise((resolve, reject) => {
+				const onDrain = () => {
+					writer.off("error", onError);
+					resolve();
+				};
+				const onError = (err) => {
+					writer.off("drain", onDrain);
+					reject(err);
+				};
+				writer.once("drain", onDrain);
+				writer.once("error", onError);
+			});
 		}
 	} finally {
 		reader.releaseLock();
 		await new Promise((resolve, reject) => {
 			writer.end(() => resolve());
-			writer.on("error", reject);
+			writer.once("error", reject);
 		});
 	}
 	return bytesWritten;
@@ -149,9 +84,16 @@ async function deleteAttachmentBytes(path) {
 *
 * If `maxBytes` is set and the input exceeds it, the temp file is removed and
 * `UploadTooLarge` is thrown.
+*
+* If `declaredSizeBytes` is set, the byte count is enforced as a contract:
+* mid-stream, the moment the count exceeds the declaration the reader is
+* released and `SizeMismatch` is thrown without consuming the rest of the
+* stream. At stream end, if the count does not equal the declaration,
+* `SizeMismatch` is thrown. Both the `maxBytes` and `declaredSizeBytes`
+* checks apply; `maxBytes` is evaluated first on each chunk.
 */
 async function streamHashAndWrite(basePath, data, options = {}) {
-	const { maxBytes } = options;
+	const { maxBytes, declaredSizeBytes } = options;
 	const tmpDir = join(basePath, ".tmp");
 	await mkdir(tmpDir, { recursive: true });
 	const tempPath = join(tmpDir, randomUUID());
@@ -166,6 +108,7 @@ async function streamHashAndWrite(basePath, data, options = {}) {
 			if (done) break;
 			sizeBytes += value.byteLength;
 			if (maxBytes !== void 0 && sizeBytes > maxBytes) throw new UploadTooLarge(maxBytes);
+			if (declaredSizeBytes !== void 0 && sizeBytes > declaredSizeBytes) throw new SizeMismatch(declaredSizeBytes, sizeBytes);
 			hasher.update(value);
 			if (!writer.write(value)) await new Promise((resolve, reject) => {
 				const onDrain = () => {
@@ -185,17 +128,30 @@ async function streamHashAndWrite(basePath, data, options = {}) {
 	} finally {
 		reader.releaseLock();
 	}
-	await new Promise((resolve, reject) => {
-		writer.end((err) => {
-			if (err) reject(err);
-			else resolve();
+	let endError;
+	try {
+		await new Promise((resolve, reject) => {
+			writer.end((err) => {
+				if (err) reject(err);
+				else resolve();
+			});
+			writer.once("error", reject);
 		});
-		writer.on("error", reject);
-	});
+	} catch (err) {
+		endError = err instanceof Error ? err : new Error(String(err));
+	}
 	if (caughtError) {
 		await rm(tempPath, { force: true });
 		throw caughtError;
 	}
+	if (endError) {
+		await rm(tempPath, { force: true });
+		throw endError;
+	}
+	if (declaredSizeBytes !== void 0 && sizeBytes !== declaredSizeBytes) {
+		await rm(tempPath, { force: true });
+		throw new SizeMismatch(declaredSizeBytes, sizeBytes);
+	}
 	return {
 		tempPath,
 		hash: hasher.digest("hex"),
@@ -214,7 +170,8 @@ function rowToHeader$1(row) {
 		status: row.status,
 		source: row.source,
 		createdAtUtc: row.created_at_utc,
-		lastAccessedAtUtc: row.last_accessed_at_utc
+		lastAccessedAtUtc: row.last_accessed_at_utc,
+		expiresAtUtc: null
 	};
 }
 function wrapStreamWithCleanup(source, cleanup) {
@@ -254,30 +211,62 @@ var KyselyAttachmentStore = class {
 	}
 	async stat(hash) {
 		const row = await this.db.selectFrom("attachment").selectAll().where("hash", "=", hash).executeTakeFirst();
-		if (!row) throw new AttachmentNotFound(hash);
-		return rowToHeader$1(row);
+		if (row) return rowToHeader$1(row);
+		const now = (/* @__PURE__ */ new Date()).toISOString();
+		const pending = await this.findPendingReservation(hash, now);
+		if (pending) return {
+			hash,
+			mimeType: pending.mime_type,
+			fileName: pending.file_name,
+			sizeBytes: Number(pending.size_bytes),
+			extension: pending.extension,
+			status: "pending",
+			source: "local",
+			createdAtUtc: pending.created_at_utc,
+			lastAccessedAtUtc: pending.created_at_utc,
+			expiresAtUtc: pending.expires_at_utc
+		};
+		throw new AttachmentNotFound(hash);
 	}
 	async has(hash) {
 		return (await this.db.selectFrom("attachment").select("status").where("hash", "=", hash).executeTakeFirst())?.status === "available";
 	}
 	async get(hash, signal) {
 		const row = await this.db.selectFrom("attachment").selectAll().where("hash", "=", hash).executeTakeFirst();
-		if (!row) throw new AttachmentNotFound(hash);
-		if (row.status === "evicted") {
-			const remote = await this.transport.fetch(hash, signal);
-			if (!remote) throw new AttachmentNotFound(hash);
-			await this.put(hash, remote.metadata, remote.body);
-			return this.get(hash, signal);
+		if (row) {
+			if (row.status === "evicted") {
+				const remote = await this.transport.fetch(hash, signal);
+				if (remote.kind === "data") {
+					await this.put(hash, remote.response.metadata, remote.response.body);
+					return this.get(hash, signal);
+				}
+				if (remote.kind === "pending") throw new AttachmentPending(hash, remote.expiresAtUtc);
+				throw new AttachmentNotFound(hash);
+			}
+			const now = (/* @__PURE__ */ new Date()).toISOString();
+			await this.db.updateTable("attachment").set({ last_accessed_at_utc: now }).where("hash", "=", hash).execute();
+			const header = rowToHeader$1(row);
+			header.lastAccessedAtUtc = now;
+			this.acquireReader(hash);
+			return {
+				header,
+				body: wrapStreamWithCleanup(readAttachmentStream(join(this.basePath, row.storage_path)), () => this.releaseReader(hash))
+			};
 		}
 		const now = (/* @__PURE__ */ new Date()).toISOString();
-		await this.db.updateTable("attachment").set({ last_accessed_at_utc: now }).where("hash", "=", hash).execute();
-		const header = rowToHeader$1(row);
-		header.lastAccessedAtUtc = now;
-		this.acquireReader(hash);
-		return {
-			header,
-			body: wrapStreamWithCleanup(readAttachmentStream(join(this.basePath, row.storage_path)), () => this.releaseReader(hash))
-		};
+		const pending = await this.findPendingReservation(hash, now);
+		if (pending) throw new AttachmentPending(hash, pending.expires_at_utc, {
+			mimeType: pending.mime_type,
+			fileName: pending.file_name,
+			sizeBytes: pending.size_bytes
+		});
+		const remote = await this.transport.fetch(hash, signal);
+		if (remote.kind === "data") {
+			await this.put(hash, remote.response.metadata, remote.response.body);
+			return this.get(hash, signal);
+		}
+		if (remote.kind === "pending") throw new AttachmentPending(hash, remote.expiresAtUtc);
+		throw new AttachmentNotFound(hash);
 	}
 	async put(hash, metadata, data) {
 		const existing = await this.db.selectFrom("attachment").select(["hash", "status"]).where("hash", "=", hash).executeTakeFirst();
@@ -317,6 +306,25 @@ var KyselyAttachmentStore = class {
 		const result = await this.db.selectFrom("attachment").select(sql`COALESCE(SUM(size_bytes), 0)`.as("total")).where("status", "=", "available").executeTakeFirst();
 		return Number(result?.total ?? 0);
 	}
+	async findPendingReservation(hash, now) {
+		const row = await this.db.selectFrom("attachment_reservation as r").leftJoin("attachment as a", "a.hash", "r.client_hash").select([
+			"r.mime_type",
+			"r.file_name",
+			"r.extension",
+			"r.size_bytes",
+			"r.created_at_utc",
+			"r.expires_at_utc"
+		]).where("r.client_hash", "=", hash).where("r.deleted_at_utc", "is", null).where("r.expires_at_utc", ">", now).where("r.size_bytes", "is not", null).where("a.hash", "is", null).orderBy("r.expires_at_utc", "desc").executeTakeFirst();
+		if (!row) return null;
+		return {
+			mime_type: row.mime_type,
+			file_name: row.file_name,
+			extension: row.extension,
+			size_bytes: Number(row.size_bytes),
+			created_at_utc: row.created_at_utc,
+			expires_at_utc: row.expires_at_utc
+		};
+	}
 	acquireReader(hash) {
 		this.activeReaders.set(hash, (this.activeReaders.get(hash) ?? 0) + 1);
 	}
@@ -339,7 +347,9 @@ function rowToReservation(row) {
 		fileName: row.file_name,
 		extension: row.extension,
 		createdAtUtc: row.created_at_utc,
-		expiresAtUtc: row.expires_at_utc
+		expiresAtUtc: row.expires_at_utc,
+		clientHash: row.client_hash,
+		sizeBytes: row.size_bytes !== null ? Number(row.size_bytes) : null
 	};
 }
 var KyselyReservationStore = class {
@@ -359,7 +369,9 @@ var KyselyReservationStore = class {
 			file_name: options.fileName,
 			extension: options.extension ?? null,
 			created_at_utc: now,
-			expires_at_utc: expiresAt
+			expires_at_utc: expiresAt,
+			client_hash: options.clientHash ?? null,
+			size_bytes: options.sizeBytes ?? null
 		}).returningAll().executeTakeFirstOrThrow());
 	}
 	async get(reservationId) {
@@ -379,72 +391,89 @@ var KyselyReservationStore = class {
 //#endregion
 //#region src/storage/migrations/001_create_attachment_table.ts
 var _001_create_attachment_table_exports = /* @__PURE__ */ __exportAll({
-	down: () => down$4,
-	up: () => up$4
+	down: () => down$5,
+	up: () => up$5
 });
-async function up$4(db) {
+async function up$5(db) {
 	await db.schema.createTable("attachment").addColumn("hash", "text", (col) => col.primaryKey()).addColumn("mime_type", "text", (col) => col.notNull()).addColumn("file_name", "text", (col) => col.notNull()).addColumn("size_bytes", "bigint", (col) => col.notNull()).addColumn("extension", "text").addColumn("status", "text", (col) => col.notNull().defaultTo("available")).addColumn("storage_path", "text", (col) => col.notNull()).addColumn("source", "text", (col) => col.notNull().defaultTo("local")).addColumn("created_at_utc", "text", (col) => col.notNull()).addColumn("last_accessed_at_utc", "text", (col) => col.notNull()).execute();
 	await db.schema.createIndex("idx_attachment_status").on("attachment").column("status").execute();
 	await db.schema.createIndex("idx_attachment_lru").on("attachment").columns(["status", "last_accessed_at_utc"]).execute();
 }
-async function down$4(db) {
+async function down$5(db) {
 	await db.schema.dropTable("attachment").ifExists().execute();
 }
 //#endregion
 //#region src/storage/migrations/002_create_reservation_table.ts
 var _002_create_reservation_table_exports = /* @__PURE__ */ __exportAll({
-	down: () => down$3,
-	up: () => up$3
+	down: () => down$4,
+	up: () => up$4
 });
-async function up$3(db) {
+async function up$4(db) {
 	await db.schema.createTable("attachment_reservation").addColumn("reservation_id", "text", (col) => col.primaryKey()).addColumn("mime_type", "text", (col) => col.notNull()).addColumn("file_name", "text", (col) => col.notNull()).addColumn("extension", "text").addColumn("created_at_utc", "text", (col) => col.notNull()).execute();
 }
-async function down$3(db) {
+async function down$4(db) {
 	await db.schema.dropTable("attachment_reservation").ifExists().execute();
 }
 //#endregion
 //#region src/storage/migrations/003_add_reservation_expires_at.ts
 var _003_add_reservation_expires_at_exports = /* @__PURE__ */ __exportAll({
-	down: () => down$2,
-	up: () => up$2
+	down: () => down$3,
+	up: () => up$3
 });
-async function up$2(db) {
+async function up$3(db) {
 	await db.schema.alterTable("attachment_reservation").addColumn("expires_at_utc", "text").execute();
 	await db.updateTable("attachment_reservation").set({ expires_at_utc: sql`created_at_utc` }).where("expires_at_utc", "is", null).execute();
 	await db.schema.alterTable("attachment_reservation").alterColumn("expires_at_utc", (col) => col.setNotNull()).execute();
 	await db.schema.createIndex("idx_reservation_expires_at").on("attachment_reservation").column("expires_at_utc").execute();
 }
-async function down$2(db) {
+async function down$3(db) {
 	await db.schema.dropIndex("idx_reservation_expires_at").ifExists().execute();
 	await db.schema.alterTable("attachment_reservation").dropColumn("expires_at_utc").execute();
 }
 //#endregion
 //#region src/storage/migrations/004_add_reservation_soft_delete.ts
 var _004_add_reservation_soft_delete_exports = /* @__PURE__ */ __exportAll({
-	down: () => down$1,
-	up: () => up$1
+	down: () => down$2,
+	up: () => up$2
 });
-async function up$1(db) {
+async function up$2(db) {
 	await db.schema.alterTable("attachment_reservation").addColumn("deleted_at_utc", "text").execute();
 }
-async function down$1(db) {
+async function down$2(db) {
 	await db.schema.alterTable("attachment_reservation").dropColumn("deleted_at_utc").execute();
 }
 //#endregion
 //#region src/storage/migrations/005_add_reservation_active_index.ts
 var _005_add_reservation_active_index_exports = /* @__PURE__ */ __exportAll({
-	down: () => down,
-	up: () => up
+	down: () => down$1,
+	up: () => up$1
 });
-async function up(db) {
+async function up$1(db) {
 	await db.schema.dropIndex("idx_reservation_expires_at").ifExists().execute();
 	await db.schema.createIndex("idx_reservation_expires_at_active").on("attachment_reservation").column("expires_at_utc").where(sql`deleted_at_utc IS NULL`).execute();
 }
-async function down(db) {
+async function down$1(db) {
 	await db.schema.dropIndex("idx_reservation_expires_at_active").ifExists().execute();
 	await db.schema.createIndex("idx_reservation_expires_at").on("attachment_reservation").column("expires_at_utc").execute();
 }
 //#endregion
+//#region src/storage/migrations/006_add_reservation_client_hash.ts
+var _006_add_reservation_client_hash_exports = /* @__PURE__ */ __exportAll({
+	down: () => down,
+	up: () => up
+});
+async function up(db) {
+	await db.schema.alterTable("attachment_reservation").addColumn("client_hash", "text").execute();
+	await db.schema.alterTable("attachment_reservation").addColumn("size_bytes", "bigint").execute();
+	await db.schema.alterTable("attachment_reservation").addCheckConstraint("attachment_reservation_hash_size_check", sql`client_hash is null or size_bytes is not null`).execute();
+	await db.schema.createIndex("idx_reservation_client_hash").on("attachment_reservation").column("client_hash").execute();
+}
+async function down(db) {
+	await db.schema.dropIndex("idx_reservation_client_hash").ifExists().execute();
+	await db.schema.alterTable("attachment_reservation").dropColumn("size_bytes").execute();
+	await db.schema.alterTable("attachment_reservation").dropColumn("client_hash").execute();
+}
+//#endregion
 //#region src/storage/migrations/migrator.ts
 const ATTACHMENT_SCHEMA = "attachments";
 const migrations = {
@@ -452,7 +481,8 @@ const migrations = {
 	"002_create_reservation_table": _002_create_reservation_table_exports,
 	"003_add_reservation_expires_at": _003_add_reservation_expires_at_exports,
 	"004_add_reservation_soft_delete": _004_add_reservation_soft_delete_exports,
-	"005_add_reservation_active_index": _005_add_reservation_active_index_exports
+	"005_add_reservation_active_index": _005_add_reservation_active_index_exports,
+	"006_add_reservation_client_hash": _006_add_reservation_client_hash_exports
 };
 var ProgrammaticMigrationProvider = class {
 	getMigrations() {
@@ -507,21 +537,35 @@ function rowToHeader(row) {
 		status: row.status,
 		source: row.source,
 		createdAtUtc: row.created_at_utc,
-		lastAccessedAtUtc: row.last_accessed_at_utc
+		lastAccessedAtUtc: row.last_accessed_at_utc,
+		expiresAtUtc: null
 	};
 }
 var DirectAttachmentUpload = class {
 	reservationId;
-	constructor(reservationId, options, db, basePath, reservations, maxBytes) {
-		this.options = options;
+	ref;
+	expiresAtUtc;
+	constructor(reservation, db, basePath, reservations, maxBytes) {
+		this.reservation = reservation;
 		this.db = db;
 		this.basePath = basePath;
 		this.reservations = reservations;
 		this.maxBytes = maxBytes;
-		this.reservationId = reservationId;
+		this.reservationId = reservation.reservationId;
+		this.ref = reservation.clientHash != null ? createRef(reservation.clientHash) : null;
+		this.expiresAtUtc = reservation.expiresAtUtc;
 	}
 	async send(data) {
-		const { tempPath, hash, sizeBytes } = await streamHashAndWrite(this.basePath, data, { maxBytes: this.maxBytes });
+		if (this.reservation.clientHash != null && this.reservation.sizeBytes == null) throw new Error("hash-first reservation missing sizeBytes");
+		const declaredSizeBytes = this.reservation.clientHash != null ? this.reservation.sizeBytes ?? void 0 : void 0;
+		const { tempPath, hash, sizeBytes } = await streamHashAndWrite(this.basePath, data, {
+			maxBytes: this.maxBytes,
+			declaredSizeBytes
+		});
+		if (this.reservation.clientHash != null && hash !== this.reservation.clientHash) {
+			await rm(tempPath, { force: true });
+			throw new HashMismatch(this.reservation.clientHash, hash);
+		}
 		try {
 			const existing = await this.db.selectFrom("attachment").select(["hash", "status"]).where("hash", "=", hash).executeTakeFirst();
 			if (existing?.status === "available") await rm(tempPath, { force: true });
@@ -533,10 +577,10 @@ var DirectAttachmentUpload = class {
 				const now = (/* @__PURE__ */ new Date()).toISOString();
 				if (!existing) await this.db.insertInto("attachment").values({
 					hash,
-					mime_type: this.options.mimeType,
-					file_name: this.options.fileName,
+					mime_type: this.reservation.mimeType,
+					file_name: this.reservation.fileName,
 					size_bytes: sizeBytes,
-					extension: this.options.extension ?? null,
+					extension: this.reservation.extension ?? null,
 					status: "available",
 					storage_path: relPath,
 					source: "local",
@@ -572,360 +616,8 @@ var DirectAttachmentUploadFactory = class {
 		this.reservations = reservations;
 		this.maxBytes = maxBytes;
 	}
-	createUpload(reservationId, options) {
-		return new DirectAttachmentUpload(reservationId, options, this.db, this.basePath, this.reservations, this.maxBytes);
-	}
-};
-//#endregion
-//#region src/switchboard/build-auth-headers.ts
-async function buildAuthHeaders(url, jwtHandler) {
-	const headers = {};
-	if (jwtHandler) {
-		const token = await jwtHandler(url);
-		if (token) headers["Authorization"] = `Bearer ${token}`;
-	}
-	return headers;
-}
-//#endregion
-//#region src/switchboard/switchboard-attachment-transport.ts
-var SwitchboardAttachmentTransport = class {
-	remoteUrl;
-	jwtHandler;
-	fetchFn;
-	constructor(config) {
-		this.remoteUrl = config.remoteUrl;
-		this.jwtHandler = config.jwtHandler;
-		this.fetchFn = (config.fetchFn ?? globalThis.fetch).bind(globalThis);
-	}
-	async fetch(hash, signal) {
-		const url = `${this.remoteUrl}/attachments/${hash}`;
-		const headers = await buildAuthHeaders(url, this.jwtHandler);
-		const response = await this.fetchFn(url, {
-			signal,
-			headers
-		});
-		if (response.status === 404) return null;
-		if (!response.ok) throw new Error(`Attachment fetch failed: ${response.status} ${response.statusText}`);
-		const metadata = this.parseMetadataHeaders(response);
-		const body = response.body;
-		if (!body) throw new Error("Response body is null");
-		return {
-			hash,
-			metadata,
-			body
-		};
-	}
-	async announce(_hash) {}
-	async push(hash, remote, data) {
-		const url = `${remote}/attachments/${hash}`;
-		const headers = await buildAuthHeaders(url, this.jwtHandler);
-		const response = await this.fetchFn(url, {
-			method: "PUT",
-			body: data,
-			headers,
-			duplex: "half"
-		});
-		if (!response.ok) throw new Error(`Attachment push failed: ${response.status} ${response.statusText}`);
-	}
-	parseMetadataHeaders(response) {
-		let fallbackCache;
-		const fallback = () => {
-			if (fallbackCache === void 0) fallbackCache = contentTypeFallback$1(response);
-			return fallbackCache;
-		};
-		const metaHeader = response.headers.get("Attachment-Metadata");
-		if (metaHeader) try {
-			const parsed = JSON.parse(metaHeader);
-			if (isRecord$2(parsed)) {
-				if (parsed.extension === void 0) parsed.extension = null;
-				if (parsed.createdAtUtc === void 0) parsed.createdAtUtc = fallback().createdAtUtc;
-				if (parsed.lastAccessedAtUtc === void 0) parsed.lastAccessedAtUtc = fallback().lastAccessedAtUtc;
-			}
-			if (isAttachmentMetadata$1(parsed)) return parsed;
-		} catch {}
-		return fallback();
-	}
-};
-function isRecord$2(value) {
-	return typeof value === "object" && value !== null && !Array.isArray(value);
-}
-function isAttachmentMetadata$1(value) {
-	if (!isRecord$2(value)) return false;
-	if (typeof value.mimeType !== "string") return false;
-	if (typeof value.fileName !== "string") return false;
-	if (typeof value.sizeBytes !== "number" || !Number.isFinite(value.sizeBytes) || value.sizeBytes < 0) return false;
-	if (value.extension !== null && typeof value.extension !== "string") return false;
-	if (typeof value.createdAtUtc !== "string") return false;
-	if (value.lastAccessedAtUtc !== void 0 && typeof value.lastAccessedAtUtc !== "string") return false;
-	return true;
-}
-function contentTypeFallback$1(response) {
-	const contentLength = response.headers.get("Content-Length");
-	if (contentLength === null) throw new Error("Switchboard response missing both Attachment-Metadata and Content-Length headers");
-	const sizeBytes = Number(contentLength);
-	if (!Number.isInteger(sizeBytes) || sizeBytes < 0) throw new Error(`Switchboard response has invalid Content-Length header: ${JSON.stringify(contentLength)}`);
-	const lastModified = response.headers.get("Last-Modified");
-	const dateHeader = response.headers.get("Date");
-	const createdAtUtc = lastModified ? new Date(lastModified).toISOString() : dateHeader ? new Date(dateHeader).toISOString() : (/* @__PURE__ */ new Date()).toISOString();
-	return {
-		mimeType: response.headers.get("Content-Type") ?? "application/octet-stream",
-		fileName: "unknown",
-		sizeBytes,
-		extension: null,
-		createdAtUtc,
-		lastAccessedAtUtc: createdAtUtc
-	};
-}
-//#endregion
-//#region src/switchboard/remote-reservation-store.ts
-function isRecord$1(value) {
-	return typeof value === "object" && value !== null && !Array.isArray(value);
-}
-function deriveExtension(fileName) {
-	const idx = fileName.lastIndexOf(".");
-	if (idx <= 0 || idx === fileName.length - 1) return null;
-	return fileName.slice(idx + 1).toLowerCase();
-}
-function isReservation(value) {
-	if (!isRecord$1(value)) return false;
-	if (typeof value.reservationId !== "string") return false;
-	if (typeof value.mimeType !== "string") return false;
-	if (typeof value.fileName !== "string") return false;
-	if (value.extension !== null && typeof value.extension !== "string") return false;
-	if (typeof value.createdAtUtc !== "string") return false;
-	if (typeof value.expiresAtUtc !== "string") return false;
-	return true;
-}
-var RemoteReservationStore = class {
-	remoteUrl;
-	jwtHandler;
-	fetchFn;
-	constructor(config) {
-		this.remoteUrl = config.remoteUrl;
-		this.jwtHandler = config.jwtHandler;
-		this.fetchFn = (config.fetchFn ?? globalThis.fetch).bind(globalThis);
-	}
-	async create(options) {
-		const url = `${this.remoteUrl}/attachments/reservations`;
-		const authHeaders = await buildAuthHeaders(url, this.jwtHandler);
-		const extension = options.extension ?? deriveExtension(options.fileName);
-		const response = await this.fetchFn(url, {
-			method: "POST",
-			headers: {
-				...authHeaders,
-				"Content-Type": "application/json"
-			},
-			body: JSON.stringify({
-				mimeType: options.mimeType,
-				fileName: options.fileName,
-				extension
-			})
-		});
-		if (!response.ok) throw new Error(`Reservation create failed: ${response.status} ${response.statusText}`);
-		const json = await response.json();
-		const now = /* @__PURE__ */ new Date();
-		return {
-			reservationId: json.reservationId,
-			mimeType: options.mimeType,
-			fileName: options.fileName,
-			extension,
-			createdAtUtc: json.createdAtUtc ?? now.toISOString(),
-			expiresAtUtc: json.expiresAtUtc ?? new Date(now.getTime() + 1440 * 60 * 1e3).toISOString()
-		};
-	}
-	async get(reservationId) {
-		const url = `${this.remoteUrl}/attachments/reservations/${encodeURIComponent(reservationId)}`;
-		const authHeaders = await buildAuthHeaders(url, this.jwtHandler);
-		const response = await this.fetchFn(url, { headers: authHeaders });
-		if (response.status === 404) throw new ReservationNotFound(reservationId);
-		if (!response.ok) throw new Error(`Reservation get failed: ${response.status} ${response.statusText}`);
-		let parsed;
-		try {
-			parsed = await response.json();
-		} catch {
-			throw new Error("Reservation get returned non-JSON response");
-		}
-		if (!isReservation(parsed)) throw new Error("Reservation get returned a payload that does not match the Reservation shape");
-		return parsed;
-	}
-	async delete(reservationId) {
-		const url = `${this.remoteUrl}/attachments/reservations/${encodeURIComponent(reservationId)}`;
-		const authHeaders = await buildAuthHeaders(url, this.jwtHandler);
-		const response = await this.fetchFn(url, {
-			method: "DELETE",
-			headers: authHeaders
-		});
-		if (!response.ok && response.status !== 404 && response.status !== 410) throw new Error(`Reservation delete failed: ${response.status} ${response.statusText}`);
-	}
-	deleteExpired() {
-		return Promise.reject(/* @__PURE__ */ new Error("RemoteReservationStore.deleteExpired is not supported"));
-	}
-};
-//#endregion
-//#region src/switchboard/remote-attachment-upload.ts
-var RemoteAttachmentUpload = class {
-	reservationId;
-	remoteUrl;
-	jwtHandler;
-	fetchFn;
-	options;
-	constructor(reservationId, options, config) {
-		this.reservationId = reservationId;
-		this.options = options;
-		this.remoteUrl = config.remoteUrl;
-		this.jwtHandler = config.jwtHandler;
-		this.fetchFn = (config.fetchFn ?? globalThis.fetch).bind(globalThis);
-	}
-	async send(data) {
-		const url = `${this.remoteUrl}/attachments/reservations/${this.reservationId}`;
-		const authHeaders = await buildAuthHeaders(url, this.jwtHandler);
-		const body = await new Response(data).blob();
-		const response = await this.fetchFn(url, {
-			method: "PUT",
-			headers: {
-				...authHeaders,
-				"Content-Type": "application/octet-stream"
-			},
-			body
-		});
-		if (!response.ok) throw new Error(`Attachment upload failed: ${response.status} ${response.statusText}`);
-		return await response.json();
-	}
-};
-//#endregion
-//#region src/switchboard/remote-attachment-upload-factory.ts
-var RemoteAttachmentUploadFactory = class {
-	constructor(config) {
-		this.config = config;
-	}
-	createUpload(reservationId, options) {
-		return new RemoteAttachmentUpload(reservationId, options, this.config);
-	}
-};
-//#endregion
-//#region src/switchboard/remote-attachment-store.ts
-function isRecord(value) {
-	return typeof value === "object" && value !== null && !Array.isArray(value);
-}
-function isAttachmentMetadata(value) {
-	if (!isRecord(value)) return false;
-	if (typeof value.mimeType !== "string") return false;
-	if (typeof value.fileName !== "string") return false;
-	if (typeof value.sizeBytes !== "number" || !Number.isFinite(value.sizeBytes) || value.sizeBytes < 0) return false;
-	if (value.extension !== null && typeof value.extension !== "string") return false;
-	if (typeof value.createdAtUtc !== "string") return false;
-	if (value.lastAccessedAtUtc !== void 0 && typeof value.lastAccessedAtUtc !== "string") return false;
-	return true;
-}
-function contentTypeFallback(response) {
-	const contentLength = response.headers.get("Content-Length");
-	if (contentLength === null) throw new Error("Switchboard response missing both Attachment-Metadata and Content-Length headers");
-	const sizeBytes = Number(contentLength);
-	if (!Number.isInteger(sizeBytes) || sizeBytes < 0) throw new Error(`Switchboard response has invalid Content-Length header: ${JSON.stringify(contentLength)}`);
-	const lastModified = response.headers.get("Last-Modified");
-	const dateHeader = response.headers.get("Date");
-	const createdAtUtc = lastModified ? new Date(lastModified).toISOString() : dateHeader ? new Date(dateHeader).toISOString() : (/* @__PURE__ */ new Date()).toISOString();
-	return {
-		mimeType: response.headers.get("Content-Type") ?? "application/octet-stream",
-		fileName: "unknown",
-		sizeBytes,
-		extension: null,
-		createdAtUtc,
-		lastAccessedAtUtc: createdAtUtc
-	};
-}
-function parseMetadata(response) {
-	let fallbackCache;
-	const fallback = () => {
-		if (fallbackCache === void 0) fallbackCache = contentTypeFallback(response);
-		return fallbackCache;
-	};
-	const metaHeader = response.headers.get("Attachment-Metadata");
-	if (metaHeader) try {
-		const parsed = JSON.parse(metaHeader);
-		if (isRecord(parsed)) {
-			if (parsed.extension === void 0) parsed.extension = null;
-			if (parsed.createdAtUtc === void 0) parsed.createdAtUtc = fallback().createdAtUtc;
-			if (parsed.lastAccessedAtUtc === void 0) parsed.lastAccessedAtUtc = fallback().lastAccessedAtUtc;
-		}
-		if (isAttachmentMetadata(parsed)) return parsed;
-	} catch {}
-	return fallback();
-}
-var RemoteAttachmentStore = class {
-	remoteUrl;
-	jwtHandler;
-	fetchFn;
-	constructor(config) {
-		this.remoteUrl = config.remoteUrl;
-		this.jwtHandler = config.jwtHandler;
-		this.fetchFn = (config.fetchFn ?? globalThis.fetch).bind(globalThis);
-	}
-	async stat(hash) {
-		const url = `${this.remoteUrl}/attachments/${hash}`;
-		const authHeaders = await buildAuthHeaders(url, this.jwtHandler);
-		const response = await this.fetchFn(url, {
-			method: "HEAD",
-			headers: authHeaders
-		});
-		if (response.status === 404) throw new AttachmentNotFound(hash);
-		if (!response.ok) throw new Error(`Attachment stat failed: ${response.status} ${response.statusText}`);
-		return buildHeader(hash, parseMetadata(response));
-	}
-	async get(hash, signal) {
-		return this.fetchAttachment(hash, signal);
-	}
-	async fetchAttachment(hash, signal) {
-		const url = `${this.remoteUrl}/attachments/${hash}`;
-		const headers = await buildAuthHeaders(url, this.jwtHandler);
-		const response = await this.fetchFn(url, {
-			signal,
-			headers
-		});
-		if (response.status === 404) throw new AttachmentNotFound(hash);
-		if (!response.ok) throw new Error(`Attachment fetch failed: ${response.status} ${response.statusText}`);
-		if (!response.body) throw new Error("Response body is null");
-		return {
-			header: buildHeader(hash, parseMetadata(response)),
-			body: response.body
-		};
-	}
-};
-function buildHeader(hash, metadata) {
-	return {
-		hash,
-		mimeType: metadata.mimeType,
-		fileName: metadata.fileName,
-		sizeBytes: metadata.sizeBytes,
-		extension: metadata.extension,
-		status: "available",
-		source: "sync",
-		createdAtUtc: metadata.createdAtUtc,
-		lastAccessedAtUtc: metadata.lastAccessedAtUtc ?? metadata.createdAtUtc
-	};
-}
-//#endregion
-//#region src/switchboard/create-remote-attachment-service.ts
-function createRemoteAttachmentService(config) {
-	const reservations = new RemoteReservationStore(config);
-	const uploadFactory = new RemoteAttachmentUploadFactory(config);
-	return new AttachmentService(new RemoteAttachmentStore(config), reservations, uploadFactory);
-}
-//#endregion
-//#region src/null-attachment-transport.ts
-/**
-* No-op transport for deployments without remote sync.
-* fetch() always returns null, announce() and push() are no-ops.
-*/
-var NullAttachmentTransport = class {
-	fetch() {
-		return Promise.resolve(null);
-	}
-	announce() {
-		return Promise.resolve();
-	}
-	push() {
-		return Promise.resolve();
+	createUpload(reservation) {
+		return new DirectAttachmentUpload(reservation, this.db, this.basePath, this.reservations, this.maxBytes);
 	}
 };
 //#endregion
@@ -934,6 +626,7 @@ var AttachmentBuilder = class {
 	transport = new NullAttachmentTransport();
 	customUploadFactory;
 	maxUploadBytes;
+	reservationSweepMs;
 	constructor(db, storagePath) {
 		this.db = db;
 		this.storagePath = storagePath;
@@ -950,6 +643,18 @@ var AttachmentBuilder = class {
 		this.maxUploadBytes = maxBytes;
 		return this;
 	}
+	/**
+	* Configure a recurring sweep that deletes expired reservations.
+	* The sweep calls reservations.deleteExpired() on the given interval.
+	* When set, the built result's destroy() clears the timer.
+	* Without this option no sweep runs -- deleteExpired() is never called
+	* automatically. Call withReservationSweepMs in production to prevent
+	* expired reservation rows from accumulating indefinitely.
+	*/
+	withReservationSweepMs(intervalMs) {
+		this.reservationSweepMs = intervalMs;
+		return this;
+	}
 	async build() {
 		const result = await runAttachmentMigrations(this.db, ATTACHMENT_SCHEMA);
 		if (!result.success && result.error) throw result.error;
@@ -957,15 +662,31 @@ var AttachmentBuilder = class {
 		const store = new KyselyAttachmentStore(scopedDb, this.transport, this.storagePath);
 		const reservations = new KyselyReservationStore(scopedDb);
 		const uploadFactory = this.customUploadFactory ?? new DirectAttachmentUploadFactory(scopedDb, this.storagePath, reservations, this.maxUploadBytes);
+		const service = new AttachmentService(store, reservations, uploadFactory);
+		let sweepTimer;
+		if (this.reservationSweepMs !== void 0) {
+			const intervalMs = this.reservationSweepMs;
+			sweepTimer = setInterval(() => {
+				reservations.deleteExpired().catch(() => {});
+			}, intervalMs);
+			if (typeof sweepTimer.unref === "function") sweepTimer.unref();
+		}
+		const destroy = () => {
+			if (sweepTimer !== void 0) {
+				clearInterval(sweepTimer);
+				sweepTimer = void 0;
+			}
+		};
 		return {
-			service: new AttachmentService(store, reservations, uploadFactory),
+			service,
 			store,
 			reservations,
-			uploadFactory
+			uploadFactory,
+			destroy
 		};
 	}
 };
 //#endregion
-export { ATTACHMENT_SCHEMA, AttachmentBuilder, AttachmentNotFound, AttachmentService, DirectAttachmentUpload, DirectAttachmentUploadFactory, InvalidAttachmentRef, KyselyAttachmentStore, KyselyReservationStore, NullAttachmentTransport, RemoteAttachmentStore, RemoteAttachmentUpload, RemoteAttachmentUploadFactory, RemoteReservationStore, ReservationNotFound, SwitchboardAttachmentTransport, createRef, createRemoteAttachmentService, parseRef, runAttachmentMigrations };
+export { ATTACHMENT_SCHEMA, AttachmentAlreadyExists, AttachmentBuilder, AttachmentNotFound, AttachmentPending, AttachmentService, DEFAULT_RESERVATION_TTL_MS, DirectAttachmentUpload, DirectAttachmentUploadFactory, HashMismatch, InvalidAttachmentRef, KyselyAttachmentStore, KyselyReservationStore, NullAttachmentTransport, RemoteAttachmentStore, RemoteAttachmentUpload, RemoteAttachmentUploadFactory, RemoteReservationStore, ReservationNotFound, SizeMismatch, SwitchboardAttachmentTransport, UploadTooLarge, createRef, createRemoteAttachmentService, parseRef, runAttachmentMigrations };
 
 //# sourceMappingURL=index.js.map