pi-roundtable-line 0.9.13 → 0.10.0

package/src/consumer.ts

@@ -0,0 +1,503 @@
+import type { SQL } from "bun";
+import type { InboundMessage, Logger } from "pi-roundtable";
+import { errorCode, LineError } from "./errors.ts";
+import type { InboxEvent, InboxProcessor, InboxResult } from "./inbox.ts";
+import type { JoinNotifier } from "./join.ts";
+import {
+	type LineContext,
+	type LineEditedEvent,
+	type LineMessageEvent,
+	type LineSubscriber,
+	type LineUnsentEvent,
+	messageOf,
+	nonEmpty,
+	readBody,
+	readMembers,
+	senderOf,
+} from "./messages.ts";
+import { inboundOf } from "./route.ts";
+
+/** The most references a subscriber may return for one message, and the longest one. */
+const MAX_REFS = 100;
+const MAX_REF_CHARS = 512;
+
+export interface ConsumerDeps {
+	sql: SQL;
+	logger: Logger;
+	now: () => Date;
+	/** Answers a `join` with the notice and says how it went; absent, a join's notice is `"unconfirmed"`. */
+	joins?: Pick<JoinNotifier, "send">;
+	/**
+	 * Hands a text message of an allowed chat to the host's router, once the subscriber has mirrored
+	 * it. Throwing fails the event, which is retried. Absent: nothing is routed.
+	 */
+	route?: (message: InboundMessage) => void;
+}
+
+const checkRef = (ref: unknown): string => {
+	if (
+		typeof ref !== "string" ||
+		ref === "" ||
+		ref.length > MAX_REF_CHARS ||
+		ref.includes("\u0000")
+	)
+		throw new LineError(
+			"bad_refs",
+			`line: a ref is a non-empty string of at most ${MAX_REF_CHARS} characters`,
+		);
+	return ref;
+};
+
+const tooManyRefs = (): LineError =>
+	new LineError(
+		"bad_refs",
+		`line: a message may have at most ${MAX_REFS} refs`,
+	);
+
+/**
+ * The references a subscriber answered, checked: strings that PostgreSQL can store, once each, in
+ * order. Nothing is a message with no references to add; anything else than `{ refs }` is refused,
+ * so an answer meant as something else (a retry request, say) is not taken for a mirror.
+ */
+function cleanRefs(answer: unknown): string[] {
+	if (answer === undefined) return [];
+	if (typeof answer !== "object" || answer === null || !("refs" in answer))
+		throw new LineError(
+			"bad_refs",
+			"line: a subscriber answers a message with { refs } or nothing; to give up, throw",
+		);
+	const refs: unknown = answer.refs;
+	if (!Array.isArray(refs) || refs.length > MAX_REFS) throw tooManyRefs();
+	return [...new Set(refs.map(checkRef))];
+}
+
+/** The context of an event that keeps nothing. */
+export const NO_KEEP: LineContext = {
+	keep: async () => {
+		throw new LineError(
+			"keep_unavailable",
+			"line: references are kept only while a message is being mirrored",
+		);
+	},
+};
+
+/** A token PostgreSQL can store, or null. */
+const storable = (value: unknown): string | null => {
+	const text = nonEmpty(value);
+	return text && !text.includes("\u0000") ? text : null;
+};
+
+/** The lock that orders everything that decides the fate of one message. */
+const lockOf = (sourceKey: string, messageId: string): string =>
+	`${sourceKey} ${messageId}`;
+
+/**
+ * Turns inbox events into the typed events of the one subscriber and keeps what is needed to take a
+ * mirror back: the references the subscriber returned, and a tombstone for every unsent message.
+ *
+ * Everything that decides what happens to one message (storing its references, writing its
+ * tombstone) runs under one advisory lock, so an unsend and a mirror in flight cannot both miss each
+ * other: either the references are stored first and the unsend hands them over, or the tombstone is
+ * written first and the mirror finds it and is taken back at once.
+ *
+ * Delivery is at least once, so every step is safe to repeat. The references of an unsent message
+ * stay stored until the subscriber has taken them back, so a subscriber that failed halfway is handed
+ * the same references again.
+ */
+export class LineConsumer {
+	readonly #sql: SQL;
+	readonly #logger: Logger;
+	readonly #now: () => Date;
+	readonly #joins: Pick<JoinNotifier, "send"> | undefined;
+	readonly #route: ((message: InboundMessage) => void) | undefined;
+
+	constructor(deps: ConsumerDeps) {
+		this.#sql = deps.sql;
+		this.#logger = deps.logger;
+		this.#now = deps.now;
+		this.#joins = deps.joins;
+		this.#route = deps.route;
+	}
+
+	/** An inbox processor that hands typed events to `handler`. */
+	processorFor(handler: LineSubscriber): InboxProcessor {
+		return async (event, signal) => this.#process(handler, event, signal);
+	}
+
+	async #process(
+		handler: LineSubscriber,
+		event: InboxEvent,
+		signal: AbortSignal,
+	): Promise<InboxResult> {
+		const sourceKey = event.sourceKey;
+		if (!sourceKey) {
+			this.#logger.warn(
+				{ event: event.id, type: event.type },
+				"a LINE event names no chat and was skipped",
+			);
+			return undefined;
+		}
+		const base = {
+			eventId: event.id,
+			sourceKey,
+			timestamp: event.timestamp,
+		};
+		switch (event.type) {
+			case "message":
+				await this.#message(handler, event, sourceKey, signal);
+				return undefined;
+			case "messageEdited":
+				await this.#edited(handler, event, sourceKey, signal);
+				return undefined;
+			case "unsend":
+				await this.#unsent(handler, event, sourceKey, signal);
+				return undefined;
+			case "join": {
+				// The notice goes first, on the event's own reply token, which lapses within minutes; the
+				// subscriber hears how it went.
+				const notice = this.#joins
+					? await this.#joins.send(event)
+					: "unconfirmed";
+				await handler({ type: "joined", ...base, notice }, signal, NO_KEEP);
+				return undefined;
+			}
+			case "leave":
+				await handler({ type: "left", ...base }, signal, NO_KEEP);
+				return undefined;
+			case "memberJoined":
+			case "memberLeft": {
+				const joined = event.type === "memberJoined";
+				const userIds = readMembers(event.payload, joined ? "joined" : "left");
+				if (userIds.length > 0)
+					await handler(
+						{ type: event.type, ...base, userIds },
+						signal,
+						NO_KEEP,
+					);
+				return undefined;
+			}
+			default:
+				// follow, postback, beacon and the like carry nothing a mirror shows.
+				return undefined;
+		}
+	}
+
+	async #message(
+		handler: LineSubscriber,
+		event: InboxEvent,
+		sourceKey: string,
+		signal: AbortSignal,
+	): Promise<void> {
+		const messageId = event.messageId;
+		if (!messageId)
+			throw new LineError("bad_message", "line: a message event has no id");
+		if (await this.#tombstoned(sourceKey, messageId)) {
+			// An unsent message is not mirrored. References left over from a mirror that was cut short
+			// are still handed back, so the post they name is taken down.
+			await this.#retract(handler, event, sourceKey, messageId, signal, false);
+			this.#logger.info(
+				{ event: event.id },
+				"a LINE message that was unsent is not mirrored",
+			);
+			return;
+		}
+		if (await this.#mirrored(sourceKey, messageId)) return;
+		const message = messageOf(event.payload);
+		const userId = senderOf(event.payload);
+		const quoted = nonEmpty(message.quotedMessageId);
+		const typed: LineMessageEvent = {
+			type: "message",
+			eventId: event.id,
+			sourceKey,
+			timestamp: event.timestamp,
+			messageId,
+			...(userId ? { userId } : {}),
+			body: readBody(message),
+			...(quoted ? { quotedMessageId: quoted } : {}),
+		};
+		// Every ref `keep` has stored: whether it stayed stored or an unsend took it back, the answer at
+		// the end does not offer it again, so a ref is never handed back twice for the same take-back.
+		const kept = new Set<string>();
+		const context: LineContext = {
+			keep: async (ref) => {
+				const unsent = await this.#keep(sourceKey, messageId, checkRef(ref));
+				kept.add(ref);
+				if (unsent) {
+					await this.#retract(
+						handler,
+						event,
+						sourceKey,
+						messageId,
+						signal,
+						false,
+					);
+				}
+				return { unsent };
+			},
+		};
+		const refs = cleanRefs(await handler(typed, signal, context)).filter(
+			(ref) => !kept.has(ref),
+		);
+		// The router gets the text only inside the store, once the message is known not to be unsent:
+		// a router that throws rolls the store back for a retry, and a store that fails routes nothing.
+		const route = this.#route;
+		const inbound = route ? inboundOf(typed, message) : undefined;
+		if (route && !inbound)
+			this.#logger.info(
+				{ event: event.id },
+				"a LINE message was not routed: it is not text from a named sender",
+			);
+		const late = await this.#store(
+			event,
+			sourceKey,
+			messageId,
+			typed,
+			refs,
+			route && inbound ? () => route(inbound) : undefined,
+		);
+		if (late) {
+			// An unsend landed while the subscriber was mirroring: take the new mirror back at once.
+			await this.#retract(handler, event, sourceKey, messageId, signal, false);
+			this.#logger.info(
+				{ event: event.id },
+				"a LINE message was unsent while it was mirrored and was taken back",
+			);
+		}
+	}
+
+	/**
+	 * Stores one reference the subscriber has just made, under the message's lock. True when the
+	 * message has been unsent: the reference is stored all the same, so it can be handed back.
+	 */
+	async #keep(
+		sourceKey: string,
+		messageId: string,
+		ref: string,
+	): Promise<boolean> {
+		const now = this.#now();
+		return this.#sql.begin(async (tx) => {
+			await tx`SELECT pg_advisory_xact_lock(hashtextextended(${lockOf(sourceKey, messageId)}, 11))`;
+			await this.#addRefs(tx, sourceKey, messageId, [ref], now);
+			return this.#tombstonedIn(tx, sourceKey, messageId);
+		});
+	}
+
+	/** Adds references after the ones stored, in order; one already stored keeps its place. The lock is held. */
+	async #addRefs(
+		tx: SQL,
+		sourceKey: string,
+		messageId: string,
+		refs: readonly string[],
+		now: Date,
+	): Promise<void> {
+		for (const ref of refs)
+			await tx`INSERT INTO line_message_refs (source_key, message_id, ref, position, created_at)
+				SELECT ${sourceKey}, ${messageId}, ${ref}, COALESCE(MAX(position) + 1, 0), ${now}
+				FROM line_message_refs WHERE source_key = ${sourceKey} AND message_id = ${messageId}
+				ON CONFLICT (source_key, message_id, ref) DO NOTHING`;
+		const [count] = (await tx`SELECT count(*)::int AS n FROM line_message_refs
+			WHERE source_key = ${sourceKey} AND message_id = ${messageId}`) as {
+			n: number;
+		}[];
+		if ((count?.n ?? 0) > MAX_REFS) throw tooManyRefs();
+	}
+
+	/**
+	 * Keeps the message and the references it answered, unless it has been unsent meanwhile, in which
+	 * case only the references are kept (so they can be handed back) and true is returned. `deliver`
+	 * runs under the message's lock after the rows are written, only when the message is not unsent;
+	 * if it throws nothing is stored.
+	 */
+	async #store(
+		event: InboxEvent,
+		sourceKey: string,
+		messageId: string,
+		typed: LineMessageEvent,
+		refs: readonly string[],
+		deliver?: () => void,
+	): Promise<boolean> {
+		const now = this.#now();
+		const message = messageOf(event.payload);
+		const replyToken = storable(event.payload.replyToken);
+		const quoteToken = storable(message.quoteToken);
+		return this.#sql.begin(async (tx) => {
+			await tx`SELECT pg_advisory_xact_lock(hashtextextended(${lockOf(sourceKey, messageId)}, 11))`;
+			const unsent = await this.#tombstonedIn(tx, sourceKey, messageId);
+			if (!unsent)
+				await tx`INSERT INTO line_messages
+					(source_key, message_id, message_type, event_ts, reply_token, reply_token_at, quote_token, created_at)
+					VALUES (${sourceKey}, ${messageId}, ${typed.body.kind}, ${event.timestamp},
+						${replyToken}, ${replyToken ? new Date(event.timestamp) : null}, ${quoteToken}, ${now})
+					ON CONFLICT (source_key, message_id) DO NOTHING`;
+			await this.#addRefs(tx, sourceKey, messageId, refs, now);
+			if (!unsent) deliver?.();
+			return unsent;
+		});
+	}
+
+	async #edited(
+		handler: LineSubscriber,
+		event: InboxEvent,
+		sourceKey: string,
+		signal: AbortSignal,
+	): Promise<void> {
+		const messageId = event.messageId;
+		if (!messageId)
+			throw new LineError("bad_message", "line: an edit event has no id");
+		if (await this.#tombstoned(sourceKey, messageId)) return;
+		const [row] = (await this.#sql`SELECT edit_ts FROM line_messages
+			WHERE source_key = ${sourceKey} AND message_id = ${messageId}`) as {
+			edit_ts: string | number;
+		}[];
+		if (!row) {
+			// The original was never mirrored (it died, or it is older than retention): nothing to edit.
+			this.#logger.info(
+				{ event: event.id },
+				"a LINE edit of a message that is not mirrored was skipped",
+			);
+			return;
+		}
+		// Edits may arrive out of order; the one with the largest time is the latest state.
+		if (Number(row.edit_ts) >= event.timestamp) return;
+		const message = messageOf(event.payload);
+		if (message.type !== "text" || typeof message.text !== "string") return;
+		const typed: LineEditedEvent = {
+			type: "edited",
+			eventId: event.id,
+			sourceKey,
+			timestamp: event.timestamp,
+			messageId,
+			text: message.text,
+			refs: await this.#refs(sourceKey, messageId),
+		};
+		await handler(typed, signal, NO_KEEP);
+		await this
+			.#sql`UPDATE line_messages SET edit_ts = GREATEST(edit_ts, ${event.timestamp})
+			WHERE source_key = ${sourceKey} AND message_id = ${messageId}`;
+	}
+
+	async #unsent(
+		handler: LineSubscriber,
+		event: InboxEvent,
+		sourceKey: string,
+		signal: AbortSignal,
+	): Promise<void> {
+		const messageId = event.messageId;
+		if (!messageId)
+			throw new LineError("bad_message", "line: an unsend event has no id");
+		const now = this.#now();
+		await this.#sql.begin(async (tx) => {
+			await tx`SELECT pg_advisory_xact_lock(hashtextextended(${lockOf(sourceKey, messageId)}, 11))`;
+			await tx`INSERT INTO line_tombstones (source_key, message_id, created_at)
+				VALUES (${sourceKey}, ${messageId}, ${now})
+				ON CONFLICT (source_key, message_id) DO NOTHING`;
+			// Whatever the message said is gone, wherever a copy waits: the event itself, edits of it.
+			await tx`UPDATE line_inbox SET payload = NULL
+				WHERE source_key = ${sourceKey} AND message_id = ${messageId} AND payload IS NOT NULL`;
+			// Its metadata (tokens, type) goes too; the references stay until they have been handed back.
+			await tx`DELETE FROM line_messages WHERE source_key = ${sourceKey} AND message_id = ${messageId}`;
+		});
+		await this.#retract(handler, event, sourceKey, messageId, signal, true);
+	}
+
+	/**
+	 * Hands the stored references of a message to the subscriber as `unsent`, then forgets them.
+	 * Without `always` nothing is handed over when there are no references: the subscriber has the
+	 * unsend event itself, and has nothing of this message to take back.
+	 */
+	async #retract(
+		handler: LineSubscriber,
+		event: Pick<InboxEvent, "id" | "timestamp">,
+		sourceKey: string,
+		messageId: string,
+		signal: AbortSignal,
+		always: boolean,
+	): Promise<void> {
+		const refs = await this.#refs(sourceKey, messageId);
+		if (refs.length === 0 && !always) return;
+		const typed: LineUnsentEvent = {
+			type: "unsent",
+			eventId: event.id,
+			sourceKey,
+			timestamp: event.timestamp,
+			messageId,
+			refs,
+		};
+		await handler(typed, signal, NO_KEEP);
+		if (refs.length > 0)
+			await this.#sql`DELETE FROM line_message_refs
+				WHERE source_key = ${sourceKey} AND message_id = ${messageId} AND ref IN ${this.#sql([...refs])}`;
+	}
+
+	/**
+	 * Hands back, as `unsent`, the refs that are still stored for a message that has a tombstone and
+	 * that were stored before `before`, the message having been unsent before `before` too. They are strays: a handler that outlived its lease kept a ref
+	 * after the unsend had taken the message back, and nobody was left to hand it over. The pass leaves
+	 * a ref alone until both it and the unsend are old enough that no unsend or `keep` in flight
+	 * can still be taking it back. A message whose take-back fails keeps its refs for the next pass. Returns how many
+	 * messages were handed back.
+	 */
+	async handBackStrays(
+		handler: LineSubscriber,
+		signal: AbortSignal,
+		before: Date,
+	): Promise<number> {
+		const strays: { source_key: string; message_id: string }[] = await this
+			.#sql`SELECT DISTINCT r.source_key, r.message_id
+			FROM line_message_refs r
+			JOIN line_tombstones t ON t.source_key = r.source_key AND t.message_id = r.message_id
+			WHERE r.created_at < ${before} AND t.created_at < ${before} LIMIT 100`;
+		let handed = 0;
+		for (const stray of strays) {
+			signal.throwIfAborted();
+			try {
+				await this.#retract(
+					handler,
+					{
+						id: `stray:${stray.source_key}:${stray.message_id}`,
+						timestamp: this.#now().getTime(),
+					},
+					stray.source_key,
+					stray.message_id,
+					signal,
+					false,
+				);
+				handed++;
+			} catch (error) {
+				if (signal.aborted) throw error;
+				this.#logger.warn(
+					{ code: errorCode(error) },
+					"refs of an unsent LINE message could not be handed back",
+				);
+			}
+		}
+		return handed;
+	}
+
+	async #refs(sourceKey: string, messageId: string): Promise<string[]> {
+		const rows: { ref: string }[] = await this
+			.#sql`SELECT ref FROM line_message_refs
+			WHERE source_key = ${sourceKey} AND message_id = ${messageId} ORDER BY position, ref`;
+		return rows.map((row) => row.ref);
+	}
+
+	async #tombstoned(sourceKey: string, messageId: string): Promise<boolean> {
+		return this.#tombstonedIn(this.#sql, sourceKey, messageId);
+	}
+
+	async #tombstonedIn(
+		sql: SQL,
+		sourceKey: string,
+		messageId: string,
+	): Promise<boolean> {
+		const rows = await sql`SELECT 1 FROM line_tombstones
+			WHERE source_key = ${sourceKey} AND message_id = ${messageId}`;
+		return rows.length > 0;
+	}
+
+	async #mirrored(sourceKey: string, messageId: string): Promise<boolean> {
+		const rows = await this.#sql`SELECT 1 FROM line_messages
+			WHERE source_key = ${sourceKey} AND message_id = ${messageId}`;
+		return rows.length > 0;
+	}
+}

package/src/content.ts

@@ -0,0 +1,210 @@
+import type { SQL } from "bun";
+import type { LineApi } from "./api.ts";
+import { LineApiError, LineError } from "./errors.ts";
+
+export interface MediaOptions {
+	/** The most bytes of one message's content held in memory; default 10 MiB. Past it the result is `{ tooLarge }`. */
+	maxBytes: number;
+	/** How long to wait between looks at a video or audio that LINE is still transcoding; default 2 seconds. */
+	transcodingPollMs: number;
+	/**
+	 * How long to wait for it altogether, requests included; default 60 seconds. Past it the call
+	 * fails with `transcoding_timeout`.
+	 */
+	transcodingMaxMs: number;
+}
+
+export const MEDIA_DEFAULTS: MediaOptions = {
+	maxBytes: 10 * 1024 * 1024,
+	transcodingPollMs: 2_000,
+	transcodingMaxMs: 60_000,
+};
+
+/** What the content of a message can be, or why it cannot. */
+export type LineContentResult =
+	| { bytes: Uint8Array; contentType: string }
+	/** The content is bigger than `media.maxBytes`; none of it is kept. */
+	| { tooLarge: true }
+	/** LINE no longer has it (it expires), the message was unsent, or LINE could not transcode it. */
+	| { expired: true; reason: "expired" | "unsent" | "transcoding_failed" };
+
+export interface LineContentRequest {
+	/**
+	 * The message's kind, as the `message` event gave it. A `"video"` or `"audio"` is waited for until
+	 * LINE has transcoded it; without a kind the content is fetched at once.
+	 */
+	kind?: "image" | "video" | "audio" | "file";
+	signal?: AbortSignal;
+}
+
+/** The longest a download of content may take, body included. */
+const DOWNLOAD_TIMEOUT_MS = 60_000;
+/** The longest one look at the transcoding status may take, when the wait has more time than that left. */
+const STATUS_TIMEOUT_MS = 15_000;
+const MESSAGE_ID = /^[A-Za-z0-9_-]{1,64}$/;
+
+function sleep(ms: number, signal: AbortSignal | undefined): Promise<void> {
+	return new Promise((resolve, reject) => {
+		if (signal?.aborted) return reject(signal.reason);
+		const onAbort = () => {
+			clearTimeout(timer);
+			reject(signal?.reason);
+		};
+		const timer = setTimeout(() => {
+			signal?.removeEventListener("abort", onAbort);
+			resolve();
+		}, ms);
+		signal?.addEventListener("abort", onAbort, { once: true });
+	});
+}
+
+/** LINE answers 404 (and 410) for content it no longer holds or never had. */
+function isGone(error: unknown): boolean {
+	return (
+		error instanceof LineApiError &&
+		(error.status === 404 || error.status === 410)
+	);
+}
+
+/**
+ * Fetches the content of a message into memory. Nothing is written to disk or to a log, and no URL
+ * is made public: the bytes go to the caller and nowhere else. A message that was unsent is not
+ * fetched at all.
+ */
+export class MessageContent {
+	readonly #sql: SQL;
+	readonly #api: LineApi;
+	readonly options: MediaOptions;
+
+	constructor(sql: SQL, api: LineApi, options: Partial<MediaOptions> = {}) {
+		this.#sql = sql;
+		this.#api = api;
+		this.options = { ...MEDIA_DEFAULTS, ...options };
+	}
+
+	async fetch(
+		messageId: string,
+		request: LineContentRequest = {},
+	): Promise<LineContentResult> {
+		if (!MESSAGE_ID.test(messageId))
+			throw new LineError(
+				"bad_message_id",
+				"line: a message id is up to 64 letters, digits, - and _",
+			);
+		const { signal } = request;
+		const unsent = await this
+			.#sql`SELECT 1 FROM line_tombstones WHERE message_id = ${messageId} LIMIT 1`;
+		if (unsent.length > 0) return { expired: true, reason: "unsent" };
+		const path = `/v2/bot/message/${messageId}/content`;
+		if (request.kind === "video" || request.kind === "audio") {
+			const state = await this.#transcoded(path, signal);
+			if (state) return state;
+		}
+		let response: Response;
+		try {
+			response = await this.#api.request(path, {
+				host: "data",
+				timeoutMs: DOWNLOAD_TIMEOUT_MS,
+				...(signal ? { signal } : {}),
+			});
+		} catch (error) {
+			if (isGone(error)) return { expired: true, reason: "expired" };
+			throw error;
+		}
+		return this.#read(response, signal);
+	}
+
+	/** Waits until LINE has transcoded a video or audio; undefined when it is ready, else the result to answer. */
+	async #transcoded(
+		path: string,
+		signal: AbortSignal | undefined,
+	): Promise<LineContentResult | undefined> {
+		const deadline = Date.now() + this.options.transcodingMaxMs;
+		for (let first = true; ; first = false) {
+			const remaining = deadline - Date.now();
+			// At least one look, however short the wait is.
+			if (remaining <= 0 && !first) break;
+			let status: unknown;
+			try {
+				const body = (await this.#api.json(`${path}/transcoding`, {
+					host: "data",
+					// A slow answer cannot outlast the wait: each request gets what is left of it.
+					timeoutMs: Math.max(1, Math.min(remaining, STATUS_TIMEOUT_MS)),
+					...(signal ? { signal } : {}),
+				})) as { status?: unknown };
+				status = body?.status;
+			} catch (error) {
+				if (isGone(error)) return { expired: true, reason: "expired" };
+				if (
+					error instanceof LineError &&
+					error.code === "api_unreachable" &&
+					remaining <= STATUS_TIMEOUT_MS
+				)
+					break;
+				throw error;
+			}
+			if (status === "succeeded") return undefined;
+			if (status === "failed")
+				return { expired: true, reason: "transcoding_failed" };
+			await sleep(
+				Math.max(
+					0,
+					Math.min(this.options.transcodingPollMs, deadline - Date.now()),
+				),
+				signal,
+			);
+		}
+		throw new LineError(
+			"transcoding_timeout",
+			"line: LINE did not finish transcoding the content in time",
+		);
+	}
+
+	/** Reads the body up to the cap; past it nothing is kept. */
+	async #read(
+		response: Response,
+		signal: AbortSignal | undefined,
+	): Promise<LineContentResult> {
+		const max = this.options.maxBytes;
+		const declared = Number(response.headers.get("content-length"));
+		if (declared > max) {
+			await response.body?.cancel().catch(() => undefined);
+			return { tooLarge: true };
+		}
+		const contentType =
+			response.headers
+				.get("content-type")
+				?.split(";")[0]
+				?.trim()
+				.toLowerCase() || "application/octet-stream";
+		const reader = response.body?.getReader();
+		if (!reader) return { bytes: new Uint8Array(0), contentType };
+		const chunks: Uint8Array[] = [];
+		let total = 0;
+		try {
+			for (;;) {
+				const { done, value } = await reader.read();
+				if (done) break;
+				total += value.byteLength;
+				if (total > max) {
+					await reader.cancel().catch(() => undefined);
+					return { tooLarge: true };
+				}
+				chunks.push(value);
+			}
+		} catch {
+			if (signal?.aborted) throw signal.reason;
+			throw new LineError(
+				"content_interrupted",
+				"line: the content download was cut short",
+			);
+		}
+		const bytes = new Uint8Array(total);
+		let offset = 0;
+		for (const chunk of chunks) {
+			bytes.set(chunk, offset);
+			offset += chunk.byteLength;
+		}
+		return { bytes, contentType };
+	}
+}