@narumitw/pi-webui 0.21.0 → 0.25.0

package/src/server.ts

@@ -4,23 +4,43 @@ import { createServer, type IncomingMessage, type Server, type ServerResponse }
 import type { Socket } from "node:net";
 import { join } from "node:path";
 import { fileURLToPath } from "node:url";
+import {
+	AttachmentError,
+	type AttachmentLimits,
+	AttachmentStore,
+	type PreparedAttachment,
+	type PublicAttachmentState,
+} from "./attachments.js";
 import type { ConversationEvent, ConversationProjection } from "./conversation.js";
+import { DraftError, DraftStore, type PublicDraftState } from "./drafts.js";
+import { type ImageLimits, imageLimits, PROVIDER_IMAGE_LIMITS } from "./image-limits.js";
 import type { BrowserImageInput } from "./images.js";
+import { SentImageError, type SentImageSettings, SentImageStore } from "./sent-images.js";
 
 const JSON_LIMIT = 64 * 1024 * 1024;
 const CLIENT_ID = /^[A-Za-z0-9_-]{1,80}$/;
 const REQUEST_ID = /^[A-Za-z0-9_-]{1,120}$/;
 const MAX_REQUESTS = 128;
+const DEFAULT_MAX_DRAFT_TEXT_BYTES = 1024 * 1024;
 const SSE_FLUSH_TIMEOUT_MS = 250;
 
 export interface WebSendRequest {
 	requestId: string;
 	text: string;
+	attachmentRevision?: number;
+	attachmentIds?: string[];
 	images: BrowserImageInput[];
+	retainedImageIds?: string[];
 	delivery: "next" | "steer";
 	signal?: AbortSignal;
 }
 
+interface ParsedSendRequest {
+	requestId: string;
+	draftRevision: number;
+	delivery: "next" | "steer";
+}
+
 export interface WebSendResult {
 	delivery: "immediate" | "followUp" | "steer";
 }
@@ -28,6 +48,11 @@ export interface WebSendResult {
 export interface WebUIServerOptions {
 	conversation: ConversationProjection;
 	send: (request: WebSendRequest) => Promise<WebSendResult>;
+	processAttachment?: (source: Uint8Array, signal?: AbortSignal) => Promise<PreparedAttachment>;
+	attachmentLimits?: AttachmentLimits;
+	imageLimits?: Readonly<ImageLimits>;
+	sentImageSettings?: SentImageSettings;
+	maxDraftTextBytes?: number;
 	maxRequestBytes?: number;
 }
 
@@ -60,6 +85,13 @@ export class WebUIServer {
 	private readonly sseClients = new Set<SseClient>();
 	private readonly requests = new Map<string, RequestRecord>();
 	private readonly activeSendControllers = new Set<AbortController>();
+	private readonly activeAttachmentControllers = new Set<AbortController>();
+	private readonly attachments: AttachmentStore;
+	private readonly attachmentLimits: AttachmentLimits;
+	private readonly imageLimits: Readonly<ImageLimits>;
+	private readonly draft: DraftStore;
+	private readonly sentImages: SentImageStore;
+	private readonly imageResidentBudget: number;
 	private activeClientId?: string;
 	private leaseGeneration = 0;
 	private closed = false;
@@ -72,6 +104,49 @@ export class WebUIServer {
 		port: number,
 	) {
 		this.origin = `http://127.0.0.1:${port}`;
+		this.imageLimits = options.imageLimits
+			? imageLimits(options.imageLimits)
+			: imageLimits({
+					maxImages: options.attachmentLimits?.maxImages,
+					maxImageBytes: options.attachmentLimits?.maxImageBytes,
+					maxBatchBytes: options.attachmentLimits?.maxPromptBytes,
+				});
+		this.attachmentLimits = {
+			maxImages: this.imageLimits.maxImages,
+			maxImageBytes: this.imageLimits.maxImageBytes,
+			maxPromptBytes: this.imageLimits.maxBatchBytes,
+			maxPreparedImageBytes: PROVIDER_IMAGE_LIMITS.maxBase64Bytes,
+		};
+		this.draft = new DraftStore({
+			maxTextBytes: options.maxDraftTextBytes ?? DEFAULT_MAX_DRAFT_TEXT_BYTES,
+		});
+		const sentImageSettings = options.sentImageSettings ?? {
+			enabled: false,
+			maxImages: 32,
+			maxBytes: 128 * 1024 * 1024,
+		};
+		this.sentImages = new SentImageStore(sentImageSettings);
+		this.imageResidentBudget = Math.max(
+			sentImageSettings.maxBytes,
+			this.attachmentLimits.maxPromptBytes +
+				Math.max(
+					this.attachmentLimits.maxImageBytes,
+					this.attachmentLimits.maxPreparedImageBytes ?? 0,
+				) *
+					2,
+		);
+		this.attachments = new AttachmentStore({
+			limits: this.attachmentLimits,
+			process:
+				options.processAttachment ??
+				(async () => {
+					throw new Error("Image processing is unavailable.");
+				}),
+			onChange: (state) => {
+				this.reconcileSentImageBytes(state);
+				this.broadcastControl("attachments", state);
+			},
+		});
 		server.on("connection", (socket) => {
 			this.sockets.add(socket);
 			socket.once("close", () => this.sockets.delete(socket));
@@ -123,7 +198,12 @@ export class WebUIServer {
 		this.bootstrapToken = undefined;
 		this.unsubscribe();
 		for (const controller of this.activeSendControllers) controller.abort();
+		for (const controller of this.activeAttachmentControllers) controller.abort();
 		this.activeSendControllers.clear();
+		this.activeAttachmentControllers.clear();
+		this.attachments.close();
+		this.draft.close();
+		this.sentImages.close();
 		this.requests.clear();
 		const responses = [...this.sseClients].map((client) => client.response);
 		this.broadcastControl("session-ended", { message: "Pi session ended" });
@@ -153,7 +233,9 @@ export class WebUIServer {
 			}
 			if (
 				request.method === "GET" &&
-				["/app.js", "/state.js", "/markdown.js", "/transcript.js"].includes(url.pathname)
+				["/app.js", "/state.js", "/markdown.js", "/transcript.js", "/image-drag.js"].includes(
+					url.pathname,
+				)
 			) {
 				await this.asset(response, url.pathname.slice(1), "text/javascript; charset=utf-8");
 				return;
@@ -166,7 +248,31 @@ export class WebUIServer {
 				this.json(response, 200, {
 					...this.options.conversation.snapshot(),
 					lease: this.leaseSnapshot(),
+					draft: this.draft.publicState(),
+					attachments: this.attachments.publicState(),
+					imageLimits: this.imageLimits,
+					sentImages: this.sentImages.publicState(),
+				});
+				return;
+			}
+			const sentPreviewId = sentImagePathId(url.pathname, "preview");
+			if (request.method === "GET" && sentPreviewId) {
+				const preview = this.sentImages.preview(sentPreviewId);
+				response.writeHead(200, {
+					"Content-Type": preview.mimeType,
+					"Content-Length": preview.bytes.byteLength,
 				});
+				response.end(preview.bytes);
+				return;
+			}
+			const previewId = attachmentPathId(url.pathname, "preview");
+			if (request.method === "GET" && previewId) {
+				const preview = this.attachments.preview(previewId);
+				response.writeHead(200, {
+					"Content-Type": preview.mimeType,
+					"Content-Length": preview.bytes.byteLength,
+				});
+				response.end(preview.bytes);
 				return;
 			}
 			if (request.method === "GET" && url.pathname === "/api/events") {
@@ -184,6 +290,8 @@ export class WebUIServer {
 				this.activeClientId = clientId;
 				this.leaseGeneration += 1;
 				for (const controller of this.activeSendControllers) controller.abort();
+				for (const controller of this.activeAttachmentControllers) controller.abort();
+				this.attachments.cancelInFlight("Editing moved to another browser tab.");
 				this.broadcastControl("lease", {
 					activeClientId: clientId,
 					generation: this.leaseGeneration,
@@ -195,17 +303,162 @@ export class WebUIServer {
 				return;
 			}
 			const lease = this.assertActiveClient(request);
+			if (request.method === "POST" && url.pathname === "/api/draft") {
+				const body = requireRecord(
+					await readJson(
+						request,
+						(this.options.maxDraftTextBytes ?? DEFAULT_MAX_DRAFT_TEXT_BYTES) + 8192,
+					),
+					"draft mutation",
+				);
+				this.assertLease(lease);
+				const state = this.draft.setText(
+					stringField(body, "text"),
+					numberField(body, "revision"),
+					stringField(body, "requestId"),
+				);
+				this.assertLease(lease);
+				this.broadcastDraft(state);
+				this.json(response, 200, state);
+				return;
+			}
+			if (request.method === "POST" && url.pathname === "/api/sent-images/reattach") {
+				const body = requireRecord(await readJson(request, 64 * 1024), "sent-image reattach");
+				this.assertLease(lease);
+				const items = parseSentImageReattachments(body.items);
+				const clones = this.sentImages.clone(items.map((item) => item.retainedId));
+				const attachments = this.attachments.attachPrepared(
+					clones.map((clone, index) => ({
+						id: items[index]?.id ?? "",
+						name: clone.name,
+						prepared: { bytes: clone.bytes, mimeType: clone.mimeType, notes: [] },
+					})),
+					numberField(body, "revision"),
+				);
+				this.assertLease(lease);
+				const draft = this.syncDraftAttachments(attachments);
+				this.json(response, 200, {
+					attachments,
+					draft,
+					sentImages: this.sentImages.publicState(),
+				});
+				return;
+			}
+			const sentDeleteId = sentImagePathId(url.pathname);
+			if (request.method === "DELETE" && sentDeleteId) {
+				const state = this.sentImages.remove(sentDeleteId, revisionParameter(url));
+				this.assertLease(lease);
+				this.broadcastSentImages(state);
+				this.json(response, 200, state);
+				return;
+			}
+			if (request.method === "POST" && url.pathname === "/api/sent-images/clear") {
+				const body = requireRecord(await readJson(request, 8 * 1024), "sent-image clear");
+				const state = this.sentImages.clear(numberField(body, "revision"));
+				this.assertLease(lease);
+				this.broadcastSentImages(state);
+				this.json(response, 200, state);
+				return;
+			}
+			if (request.method === "POST" && url.pathname === "/api/attachments/reserve") {
+				const body = requireRecord(await readJson(request, 64 * 1024), "attachment reservation");
+				this.assertLease(lease);
+				const state = this.attachments.reserve(
+					parseAttachmentReservations(body.items),
+					numberField(body, "revision"),
+				);
+				this.assertLease(lease);
+				this.syncDraftAttachments(state);
+				this.json(response, 201, state);
+				return;
+			}
+			const uploadId = attachmentPathId(url.pathname, "upload");
+			if (request.method === "POST" && uploadId) {
+				const revision = revisionParameter(url);
+				let source: Buffer;
+				try {
+					source = await readBytes(request, this.attachmentLimits.maxImageBytes);
+				} catch (error) {
+					this.assertLease(lease);
+					try {
+						this.attachments.failUpload(uploadId, `Upload failed: ${formatError(error)}`);
+					} catch (failure) {
+						if (!(failure instanceof AttachmentError) || failure.status !== 409) throw failure;
+					}
+					throw error;
+				}
+				this.assertLease(lease);
+				const state = await this.runAttachmentOperation(request, response, (signal) =>
+					this.attachments.upload(uploadId, source, revision, signal),
+				);
+				this.assertLease(lease);
+				this.json(response, 200, state);
+				return;
+			}
+			const retryId = attachmentPathId(url.pathname, "retry");
+			if (request.method === "POST" && retryId) {
+				const body = requireRecord(await readJson(request, 8 * 1024), "attachment retry");
+				this.assertLease(lease);
+				const state = await this.runAttachmentOperation(request, response, (signal) =>
+					this.attachments.retry(retryId, numberField(body, "revision"), signal),
+				);
+				this.assertLease(lease);
+				this.json(response, 200, state);
+				return;
+			}
+			const deleteId = attachmentPathId(url.pathname);
+			if (request.method === "DELETE" && deleteId) {
+				const state = this.attachments.remove(deleteId, revisionParameter(url));
+				this.assertLease(lease);
+				this.syncDraftAttachments(state);
+				this.json(response, 200, state);
+				return;
+			}
+			if (request.method === "POST" && url.pathname === "/api/attachments/reorder") {
+				const body = requireRecord(await readJson(request, 64 * 1024), "attachment reorder");
+				this.assertLease(lease);
+				const state = this.attachments.reorder(
+					stringArrayField(body, "ids"),
+					numberField(body, "revision"),
+				);
+				this.assertLease(lease);
+				this.syncDraftAttachments(state);
+				this.json(response, 200, state);
+				return;
+			}
+			if (request.method === "POST" && url.pathname === "/api/attachments/clear") {
+				const body = requireRecord(await readJson(request, 8 * 1024), "attachment clear");
+				this.assertLease(lease);
+				const state = this.attachments.clear(numberField(body, "revision"));
+				this.assertLease(lease);
+				this.syncDraftAttachments(state);
+				this.json(response, 200, state);
+				return;
+			}
 			if (request.method === "POST" && url.pathname === "/api/messages") {
 				const body = await readJson(request, this.options.maxRequestBytes ?? JSON_LIMIT);
 				this.assertLease(lease);
 				const message = parseSendRequest(body);
 				const result = await this.sendDeduplicated(message, request, response);
-				this.json(response, 202, { accepted: true, requestId: message.requestId, ...result });
+				this.json(response, 202, {
+					accepted: true,
+					requestId: message.requestId,
+					...result,
+					draft: this.draft.publicState(),
+					attachments: this.attachments.publicState(),
+					sentImages: this.sentImages.publicState(),
+				});
 				return;
 			}
 			throw new HttpError(404, "Not found");
 		} catch (error) {
-			const status = error instanceof HttpError ? error.status : 500;
+			const status =
+				error instanceof HttpError ||
+				error instanceof AttachmentError ||
+				error instanceof DraftError ||
+				error instanceof SentImageError
+					? error.status
+					: 500;
 			if (error instanceof HttpError && error.closeConnection)
 				response.setHeader("Connection", "close");
 			this.json(response, status, { error: formatError(error) });
@@ -253,8 +506,27 @@ export class WebUIServer {
 		}
 	}
 
+	private async runAttachmentOperation(
+		request: IncomingMessage,
+		response: ServerResponse,
+		operation: (signal: AbortSignal) => PublicAttachmentState | Promise<PublicAttachmentState>,
+	): Promise<PublicAttachmentState> {
+		const controller = new AbortController();
+		this.activeAttachmentControllers.add(controller);
+		const abort = () => controller.abort();
+		request.once("aborted", abort);
+		response.once("close", abort);
+		try {
+			return await operation(controller.signal);
+		} finally {
+			request.off("aborted", abort);
+			response.off("close", abort);
+			this.activeAttachmentControllers.delete(controller);
+		}
+	}
+
 	private async sendDeduplicated(
-		message: WebSendRequest,
+		message: ParsedSendRequest,
 		request: IncomingMessage,
 		response: ServerResponse,
 	): Promise<WebSendResult> {
@@ -265,14 +537,75 @@ export class WebUIServer {
 				throw new HttpError(409, "Request id was reused with different content");
 			return current.promise;
 		}
+		const draftReservation = this.draft.beginSend(message.draftRevision);
+		const attachmentState = this.attachments.publicState();
+		if (
+			!sameIds(
+				draftReservation.attachmentIds,
+				attachmentState.items.map((item) => item.id),
+			)
+		) {
+			this.draft.finishSend(draftReservation.token, false);
+			throw new HttpError(409, "Draft attachment references are stale");
+		}
+		let attachmentReservation: ReturnType<AttachmentStore["beginSend"]> | undefined;
+		try {
+			attachmentReservation =
+				draftReservation.attachmentIds.length > 0
+					? this.attachments.beginSend(draftReservation.attachmentIds, attachmentState.revision)
+					: undefined;
+		} catch (error) {
+			this.draft.finishSend(draftReservation.token, false);
+			throw error;
+		}
+		const retainedImageIds = this.sentImages.referencesFor(
+			message.requestId,
+			attachmentReservation?.images ?? [],
+		);
 		const controller = new AbortController();
 		this.activeSendControllers.add(controller);
 		const abort = () => controller.abort();
 		request.once("aborted", abort);
 		response.once("close", abort);
+		let reservationsSettled = false;
 		const promise = this.options
-			.send({ ...message, signal: controller.signal })
+			.send({
+				requestId: message.requestId,
+				text: draftReservation.text,
+				attachmentRevision: attachmentState.revision,
+				attachmentIds: draftReservation.attachmentIds,
+				images: attachmentReservation?.images ?? [],
+				retainedImageIds,
+				delivery: message.delivery,
+				signal: controller.signal,
+			})
 			.then((result) => {
+				if (retainedImageIds.length > 0) {
+					try {
+						const before = this.sentImages.publicState().revision;
+						this.sentImages.commit(
+							message.requestId,
+							attachmentReservation?.images ?? [],
+							retainedImageIds,
+						);
+						const retained = this.sentImages.reconcile(
+							attachmentState.totalResidentBytes,
+							this.imageResidentBudget,
+						);
+						if (retained.revision !== before) this.broadcastSentImages(retained);
+					} catch {
+						// Retention is optional and must not turn an accepted Pi message into a failure.
+					}
+				}
+				const nextAttachments = attachmentReservation
+					? this.attachments.finishSend(attachmentReservation.token, true)
+					: this.attachments.publicState();
+				const nextDraft = this.draft.finishSend(draftReservation.token, true, {
+					revision: nextAttachments.revision,
+					ids: nextAttachments.items.map((item) => item.id),
+				});
+				this.broadcastDraft(nextDraft);
+				reservationsSettled = true;
 				const record = this.requests.get(message.requestId);
 				if (record?.promise === promise) {
 					record.settled = true;
@@ -281,6 +614,17 @@ export class WebUIServer {
 				return result;
 			})
 			.catch((error) => {
+				if (!reservationsSettled) {
+					try {
+						if (attachmentReservation) {
+							this.attachments.finishSend(attachmentReservation.token, false);
+						}
+						this.draft.finishSend(draftReservation.token, false);
+					} catch {
+						// Session shutdown may already have released the reservations.
+					}
+					reservationsSettled = true;
+				}
 				if (this.requests.get(message.requestId)?.promise === promise) {
 					this.requests.delete(message.requestId);
 				}
@@ -326,6 +670,10 @@ export class WebUIServer {
 			return;
 		}
 		this.writeSse(client, "lease", this.leaseSnapshot());
+		this.writeSse(client, "draft", this.draft.publicState());
+		this.writeSse(client, "attachments", this.attachments.publicState());
+		this.writeSse(client, "image-limits", this.imageLimits);
+		this.writeSse(client, "sent-images", this.sentImages.publicState());
 		const replay = this.options.conversation.eventsAfter(since);
 		if (replay === undefined) {
 			this.writeSse(client, "snapshot", this.options.conversation.snapshot());
@@ -342,6 +690,40 @@ export class WebUIServer {
 		};
 	}
 
+	private syncDraftAttachments(attachments: PublicAttachmentState): PublicDraftState {
+		const before = this.draft.publicState().revision;
+		const next = this.draft.syncAttachments(
+			attachments.items.map((item) => item.id),
+			attachments.revision,
+		);
+		if (next.revision !== before) this.broadcastDraft(next);
+		return next;
+	}
+
+	private broadcastDraft(state: PublicDraftState): void {
+		this.broadcastControl("draft", state);
+	}
+
+	private broadcastSentImages(state: ReturnType<SentImageStore["publicState"]>): void {
+		this.broadcastControl("sent-images", state);
+	}
+
+	private reconcileSentImageBytes(attachments = this.attachments.publicState()): void {
+		const processingReserve =
+			attachments.phase === "processing"
+				? Math.max(
+						this.attachmentLimits.maxImageBytes,
+						this.attachmentLimits.maxPreparedImageBytes ?? 0,
+					) * 2
+				: 0;
+		const before = this.sentImages.publicState().revision;
+		const retained = this.sentImages.reconcile(
+			attachments.totalResidentBytes + processingReserve,
+			this.imageResidentBudget,
+		);
+		if (retained.revision !== before) this.broadcastSentImages(retained);
+	}
+
 	private broadcastEvent(event: ConversationEvent): void {
 		for (const client of [...this.sseClients]) this.writeSse(client, "conversation", event);
 	}
@@ -421,46 +803,42 @@ async function readAsset(name: string): Promise<Buffer> {
 	}
 }
 
-function messageDigest(message: WebSendRequest): string {
+function messageDigest(message: ParsedSendRequest): string {
 	const hash = createHash("sha256");
-	for (const value of [message.requestId, message.delivery, message.text]) {
+	for (const value of [message.requestId, message.delivery, String(message.draftRevision)]) {
 		hash
 			.update(String(Buffer.byteLength(value)))
 			.update(":")
 			.update(value);
 	}
-	for (const image of message.images) {
-		for (const value of [image.name ?? "", image.mimeType ?? "", image.data]) {
-			hash
-				.update(String(Buffer.byteLength(value)))
-				.update(":")
-				.update(value);
-		}
-	}
 	return hash.digest("hex");
 }
 
-function parseSendRequest(value: unknown): WebSendRequest {
+function parseSendRequest(value: unknown): ParsedSendRequest {
 	if (!isRecord(value)) throw new HttpError(400, "Invalid message request");
 	const requestId = stringField(value, "requestId");
 	if (!REQUEST_ID.test(requestId)) throw new HttpError(400, "Invalid request id");
-	const text = stringField(value, "text");
-	const imagesValue = value.images;
-	if (!Array.isArray(imagesValue)) throw new HttpError(400, "Invalid image list");
-	if (!text.trim() && imagesValue.length === 0) throw new HttpError(400, "Message cannot be empty");
+	const draftRevision = numberField(value, "draftRevision");
 	const delivery = value.delivery;
 	if (delivery !== "next" && delivery !== "steer")
 		throw new HttpError(400, "Invalid delivery mode");
-	const images = imagesValue.map((image) => {
-		if (!isRecord(image) || typeof image.data !== "string")
-			throw new HttpError(400, "Invalid image");
-		return {
-			data: image.data,
-			...(typeof image.name === "string" ? { name: image.name } : {}),
-			...(typeof image.mimeType === "string" ? { mimeType: image.mimeType } : {}),
-		};
-	});
-	return { requestId, text, images, delivery };
+	return { requestId, draftRevision, delivery };
+}
+
+async function readBytes(request: IncomingMessage, limit: number): Promise<Buffer> {
+	const length = Number(request.headers["content-length"] ?? "0");
+	if (Number.isFinite(length) && length > limit) {
+		throw new HttpError(413, "Request body is too large", true);
+	}
+	const chunks: Buffer[] = [];
+	let total = 0;
+	for await (const chunk of request) {
+		const bytes = Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk);
+		total += bytes.byteLength;
+		if (total > limit) throw new HttpError(413, "Request body is too large", true);
+		chunks.push(bytes);
+	}
+	return Buffer.concat(chunks);
 }
 
 async function readJson(request: IncomingMessage, limit: number): Promise<unknown> {
@@ -479,12 +857,94 @@ async function readJson(request: IncomingMessage, limit: number): Promise<unknow
 	}
 }
 
+function requireRecord(value: unknown, label: string): Record<string, unknown> {
+	if (!isRecord(value)) throw new HttpError(400, `Invalid ${label}`);
+	return value;
+}
+
 function stringField(value: Record<string, unknown>, key: string): string {
 	const field = value[key];
 	if (typeof field !== "string") throw new HttpError(400, `Invalid ${key}`);
 	return field;
 }
 
+function numberField(value: Record<string, unknown>, key: string): number {
+	const field = value[key];
+	if (!Number.isSafeInteger(field) || (field as number) < 0) {
+		throw new HttpError(400, `Invalid ${key}`);
+	}
+	return field as number;
+}
+
+function stringArrayField(value: Record<string, unknown>, key: string): string[] {
+	const field = value[key];
+	if (!Array.isArray(field) || field.some((item) => typeof item !== "string")) {
+		throw new HttpError(400, `Invalid ${key}`);
+	}
+	return field;
+}
+
+function parseAttachmentReservations(value: unknown): Array<{
+	id: string;
+	name: string;
+	size: number;
+	mimeType?: string;
+}> {
+	if (!Array.isArray(value)) throw new HttpError(400, "Invalid attachment list");
+	return value.map((entry) => {
+		const item = requireRecord(entry, "attachment");
+		return {
+			id: stringField(item, "id"),
+			name: stringField(item, "name"),
+			size: numberField(item, "size"),
+			...(typeof item.mimeType === "string" ? { mimeType: item.mimeType } : {}),
+		};
+	});
+}
+
+function parseSentImageReattachments(value: unknown): Array<{
+	retainedId: string;
+	id: string;
+}> {
+	if (!Array.isArray(value) || value.length === 0) {
+		throw new HttpError(400, "Invalid sent-image reattach list");
+	}
+	return value.map((entry) => {
+		const item = requireRecord(entry, "sent-image reattach item");
+		return {
+			retainedId: stringField(item, "retainedId"),
+			id: stringField(item, "id"),
+		};
+	});
+}
+
+function revisionParameter(url: URL): number {
+	const value = url.searchParams.get("revision");
+	if (!value || !/^\d+$/.test(value)) throw new HttpError(400, "Invalid attachment revision");
+	const revision = Number(value);
+	if (!Number.isSafeInteger(revision)) throw new HttpError(400, "Invalid attachment revision");
+	return revision;
+}
+
+function attachmentPathId(
+	pathname: string,
+	action?: "upload" | "retry" | "preview",
+): string | undefined {
+	const suffix = action ? `/${action}` : "";
+	const match = new RegExp(`^/api/attachments/([A-Za-z0-9_-]{1,128})${suffix}$`).exec(pathname);
+	return match?.[1];
+}
+
+function sentImagePathId(pathname: string, action?: "preview"): string | undefined {
+	const suffix = action ? `/${action}` : "";
+	const match = new RegExp(`^/api/sent-images/([A-Za-z0-9_-]{1,128})${suffix}$`).exec(pathname);
+	return match?.[1];
+}
+
+function sameIds(left: readonly string[], right: readonly string[]): boolean {
+	return left.length === right.length && left.every((id, index) => id === right[index]);
+}
+
 function token(): string {
 	return randomBytes(32).toString("base64url");
 }