samva 0.10.0 → 0.11.0

package/dist/mailbox-events-CcWm8lO4.js

@@ -0,0 +1,617 @@
+//#region src/mailbox-events.ts
+/**
+* The mailbox event stream: the `mailbox.*` events a webhook endpoint receives, delivered over a
+* WebSocket to a program that has no public URL for webhooks to reach.
+*
+* {@link MailboxEventStream} is an async iterable. The loop body handling an event is the
+* acknowledgement: asking for the next event marks the previous one handled, and the stream
+* resumes from the last handled event whenever it reconnects. Transient closes reconnect by
+* themselves; a close the caller has to act on ends the loop with a {@link MailboxEventStreamError}.
+*
+* This module has no runtime dependencies so the Promise and Effect clients share it.
+*/
+/** The WebSocket path on the events host. */
+const MAILBOX_EVENT_STREAM_PATH = "/v1/mailboxes/events";
+/** Close codes the events host ends an accepted connection with. */
+const MailboxEventStreamCloseCode = {
+	/** The client sent a frame that is not an acknowledgement of a cursor it was sent. */
+	invalidFrame: 4400,
+	/** The credential stopped authenticating: revoked, rotated, or expired. */
+	unauthorized: 4401,
+	/** The credential authenticates but may no longer read mailboxes. */
+	forbidden: 4403,
+	/** Mailboxes are unavailable to the organization. */
+	gone: 4404,
+	/** Too many events went unacknowledged. Reconnecting from the last handled cursor recovers. */
+	slowConsumer: 4408,
+	/** Events after the cursor are no longer retained. Read current state and start without one. */
+	cursorExpired: 4410,
+	/** Access could not be confirmed for a while. Reconnecting from the last cursor recovers. */
+	accessUnavailable: 4503
+};
+/** The refusal tags the events host answers with, keyed by the status that carries them. */
+const REFUSAL_TAG_BY_STATUS = {
+	401: "UnauthorizedError",
+	403: "ForbiddenError",
+	404: "ResourceNotFoundError",
+	405: "MethodNotAllowedError",
+	410: "CursorExpiredError",
+	422: "ValidationError",
+	426: "UpgradeRequiredError",
+	429: "RateLimitedError",
+	503: "ServiceUnavailableError"
+};
+const REFUSAL_TAGS = new Set(Object.values(REFUSAL_TAG_BY_STATUS));
+/**
+* A stream that ended. `_tag` names the cause and `message` says what to do next, as the host
+* wrote it when the host refused. Branch on `_tag`; in the Effect client the stream fails with
+* {@link MailboxEventStreamFailure}, which `Effect.catchTag` narrows by `_tag`.
+*
+* The stream retries by itself only where retrying can help: a transient close, an unreachable
+* host, a `408`, a `429`, or a `5xx`. Every other refusal ends it, so a caller never loops on a
+* request the host will keep refusing.
+*/
+var MailboxEventStreamError = class extends Error {
+	name = "MailboxEventStreamError";
+	_tag;
+	/** The HTTP status, when the host refused the connection before accepting it. */
+	status;
+	/** The WebSocket close code, when the host closed an accepted connection. */
+	closeCode;
+	/** The last handled cursor; reconnect with it unless `_tag` is `CursorExpiredError`. */
+	cursor;
+	/** A `ValidationError`'s field messages, such as `fields.cursor` or `fields.mailboxId`. */
+	fields;
+	/** How long a `RateLimitedError` or `ServiceUnavailableError` asked the caller to wait. */
+	retryAfterSeconds;
+	/** The tag the host sent, when it is not one this client maps. */
+	serverTag;
+	constructor(input) {
+		super(input.message);
+		this._tag = input._tag;
+		this.status = input.status;
+		this.closeCode = input.closeCode;
+		this.cursor = input.cursor;
+		this.fields = input.fields;
+		this.retryAfterSeconds = input.retryAfterSeconds;
+		this.serverTag = input.serverTag;
+	}
+};
+const OPEN = 1;
+/** Acknowledge after this many handled events, well inside the server's window of 256. */
+const ACK_EVERY = 32;
+const RETRY_BASE_MILLIS = 500;
+const RETRY_MAX_MILLIS = 3e4;
+/** The longest wait a host's `retryAfterSeconds` is honored for. */
+const RETRY_AFTER_MAX_MILLIS = 3e5;
+/** The largest refusal body read; the host's error bodies are a few hundred bytes. */
+const REFUSAL_BODY_LIMIT = 65536;
+/** The longest the diagnosing request and its body may take before the refusal is treated as retryable. */
+const DIAGNOSE_TIMEOUT_MILLIS = 1e4;
+/**
+* How long a connection may stay silent before it is treated as dropped: three heartbeat
+* intervals, so one late or lost heartbeat does not reconnect. A socket that died without a close
+* event is otherwise indistinguishable from a quiet mailbox.
+*/
+const MAILBOX_EVENT_STREAM_IDLE_MILLIS = 9e4;
+const isRecord = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
+const frameText = (raw) => {
+	if (typeof raw === "string") return raw;
+	if (raw instanceof ArrayBuffer || ArrayBuffer.isView(raw)) return new TextDecoder().decode(raw);
+};
+const decodeFrame = (raw) => {
+	const text = frameText(raw);
+	if (text === void 0) return void 0;
+	let parsed;
+	try {
+		parsed = JSON.parse(text);
+	} catch {
+		return;
+	}
+	if (!isRecord(parsed) || typeof parsed.cursor !== "string") return void 0;
+	if (parsed.kind === "live" || parsed.kind === "heartbeat") return {
+		kind: parsed.kind,
+		cursor: parsed.cursor
+	};
+	if (parsed.kind !== "event" || typeof parsed.id !== "string" || !isRecord(parsed.event)) return;
+	const { type, timestamp, data } = parsed.event;
+	if (typeof type !== "string" || typeof timestamp !== "string") return void 0;
+	return {
+		kind: "event",
+		cursor: parsed.cursor,
+		id: parsed.id,
+		event: {
+			type,
+			timestamp,
+			data
+		}
+	};
+};
+/** The events URL for an API origin: `https://api.samva.dev` → `wss://events.samva.dev/v1/…`. */
+const mailboxEventsUrl = (connection, options) => {
+	const invalid = (message) => new MailboxEventStreamError({
+		_tag: "StreamClientError",
+		message
+	});
+	const url = URL.parse(options.eventsUrl ?? connection.baseUrl);
+	if (url === null) throw invalid("The events origin is not a valid URL.");
+	if (url.username !== "" || url.password !== "") throw invalid("The events origin must not contain credentials.");
+	if (options.eventsUrl === void 0) {
+		const labels = url.hostname.split(".");
+		const api = labels.indexOf("api");
+		if (api === -1) throw invalid("The API origin has no `api` host label; pass `eventsUrl`.");
+		labels[api] = "events";
+		url.hostname = labels.join(".");
+	}
+	if (url.protocol === "https:") url.protocol = "wss:";
+	else if (url.protocol === "http:") url.protocol = "ws:";
+	if (url.protocol !== "wss:" && url.protocol !== "ws:") throw invalid("The events origin must be an http, https, ws, or wss URL.");
+	url.pathname = MAILBOX_EVENT_STREAM_PATH;
+	url.search = "";
+	url.hash = "";
+	if (options.cursor !== void 0) url.searchParams.set("cursor", options.cursor);
+	for (const id of options.mailboxIds ?? []) url.searchParams.append("mailboxId", id);
+	return url;
+};
+const DESCRIPTION = {
+	UnauthorizedError: "The credential is not valid. Sign in again or use an active API key.",
+	ForbiddenError: "The credential may not read mailbox events.",
+	ResourceNotFoundError: "The mailbox event stream or a requested mailbox was not found; mailboxes may not be enabled for the organization.",
+	CursorExpiredError: "Events after the cursor are no longer retained. Read current state from the API and start without a cursor.",
+	ValidationError: "The stream request was not valid.",
+	UpgradeRequiredError: "The events host expects a WebSocket upgrade.",
+	RateLimitedError: "Too many streams are open. Close one or wait before connecting.",
+	ServiceUnavailableError: "The events host could not confirm access. Retry shortly.",
+	MethodNotAllowedError: "The events host accepts GET with a WebSocket upgrade.",
+	StreamDisconnectedError: "The mailbox event stream disconnected.",
+	StreamClientError: "The stream request could not be made.",
+	StreamProtocolError: "The events host sent a frame this client does not understand.",
+	StreamRefusedError: "The events host refused the connection."
+};
+const outcomeOf = (_tag, retry, detail = {}) => {
+	const { message, ...rest } = detail;
+	return {
+		retry,
+		retryAfterMillis: detail.retryAfterSeconds === void 0 ? void 0 : Math.min(RETRY_AFTER_MAX_MILLIS, detail.retryAfterSeconds * 1e3),
+		error: new MailboxEventStreamError({
+			_tag,
+			message: message ?? DESCRIPTION[_tag],
+			...rest
+		})
+	};
+};
+/** What a close means for the stream: the error it ends with, and whether to retry first. */
+const closeOutcome = (closeCode) => {
+	switch (closeCode) {
+		case MailboxEventStreamCloseCode.invalidFrame: return outcomeOf("StreamClientError", false, {
+			closeCode,
+			message: "The events host rejected a frame this client sent."
+		});
+		case MailboxEventStreamCloseCode.unauthorized: return outcomeOf("UnauthorizedError", false, { closeCode });
+		case MailboxEventStreamCloseCode.forbidden: return outcomeOf("ForbiddenError", false, { closeCode });
+		case MailboxEventStreamCloseCode.gone: return outcomeOf("ResourceNotFoundError", false, { closeCode });
+		case MailboxEventStreamCloseCode.cursorExpired: return outcomeOf("CursorExpiredError", false, { closeCode });
+		case MailboxEventStreamCloseCode.accessUnavailable: return outcomeOf("ServiceUnavailableError", true, { closeCode });
+		default: return outcomeOf("StreamDisconnectedError", true, { closeCode });
+	}
+};
+const fieldsOf = (value) => {
+	if (!isRecord(value)) return void 0;
+	const fields = {};
+	for (const [path, messages] of Object.entries(value)) if (Array.isArray(messages)) fields[path] = messages.filter((message) => typeof message === "string");
+	return fields;
+};
+/**
+* What a refusal means for the stream. Every 4xx except `408` and `429` ends it: the host will
+* keep refusing the same request. `5xx`, `408`, and `429` retry, after the delay the host asked
+* for when it asked for one.
+*/
+const refusalOutcome = (refusal) => {
+	const body = isRecord(refusal.body) ? refusal.body : {};
+	const serverTag = typeof body._tag === "string" ? body._tag : void 0;
+	const known = serverTag !== void 0 && REFUSAL_TAGS.has(serverTag);
+	const _tag = known ? serverTag : REFUSAL_TAG_BY_STATUS[refusal.status] ?? "StreamRefusedError";
+	const retryAfterSeconds = typeof body.retryAfterSeconds === "number" && body.retryAfterSeconds > 0 ? body.retryAfterSeconds : refusal.retryAfterSeconds;
+	const retry = refusal.status >= 500 || refusal.status === 408 || refusal.status === 429;
+	return outcomeOf(_tag, retry, {
+		status: refusal.status,
+		message: typeof body.message === "string" ? body.message : void 0,
+		fields: fieldsOf(body.fields),
+		retryAfterSeconds,
+		serverTag: known ? void 0 : serverTag
+	});
+};
+/**
+* The runtime's WebSocket. The standard constructor's type omits the headers option Node and Bun
+* accept, so it is read as the narrower constructor the stream calls.
+*/
+const globalWebSocket = () => {
+	const candidate = Reflect.get(globalThis, "WebSocket");
+	return typeof candidate === "function" ? candidate : void 0;
+};
+const sleep = (millis, signal) => new Promise((resolve) => {
+	if (signal.aborted) return resolve();
+	const timer = setTimeout(done, millis);
+	function done() {
+		clearTimeout(timer);
+		signal.removeEventListener("abort", done);
+		resolve();
+	}
+	signal.addEventListener("abort", done, { once: true });
+});
+/**
+* A resumable stream of mailbox events. Iterate it with `for await`; break out of the loop or call
+* {@link close} to end it.
+*/
+var MailboxEventStream = class {
+	#connection;
+	#options;
+	#stop = new AbortController();
+	#queue = [];
+	#waiting;
+	/** A reconnect waiting for the caller to drain what the last connection buffered. */
+	#draining;
+	#socket;
+	#error;
+	#ended = false;
+	/** The caller ended the stream: nothing more is handed out, buffered or not. */
+	#closed = false;
+	#started = false;
+	/** The caller's signal and the listener on it, detached once the stream ends. */
+	#callerSignal;
+	#onCallerAbort = () => this.close();
+	/** The last event handed to the caller, handled once the caller asks for the next one. */
+	#inHand;
+	#cursor;
+	#unacked = 0;
+	constructor(connection, options = {}) {
+		this.#connection = connection;
+		this.#options = options;
+		this.#cursor = options.cursor;
+		mailboxEventsUrl(connection, options);
+		if (options.signal?.aborted) this.close();
+		else {
+			this.#callerSignal = options.signal;
+			options.signal?.addEventListener("abort", this.#onCallerAbort, { once: true });
+		}
+	}
+	/**
+	* The position to resume from: the last handled event's cursor, or a later position the
+	* server confirmed with nothing in between for this stream. Undefined until there is one.
+	*/
+	get cursor() {
+		return this.#cursor;
+	}
+	/**
+	* Mark the event in hand handled now, before asking for the next one: for a caller that stops
+	* after handling it, so {@link close} acknowledges it and {@link cursor} moves past it.
+	*/
+	markHandled() {
+		this.#settleInHand();
+	}
+	/**
+	* End the stream. Handled events are acknowledged; the event in hand is not, unless
+	* {@link markHandled} was called, so a resume repeats it. A pending iteration finishes.
+	*/
+	close() {
+		if (this.#ended) return;
+		this.#ack();
+		this.#ended = true;
+		this.#closed = true;
+		this.#callerSignal?.removeEventListener("abort", this.#onCallerAbort);
+		this.#socket?.close(1e3);
+		this.#stop.abort();
+		this.#wake();
+	}
+	[Symbol.asyncIterator]() {
+		return {
+			next: () => this.#next(),
+			return: async () => {
+				this.close();
+				return {
+					done: true,
+					value: void 0
+				};
+			}
+		};
+	}
+	async #next() {
+		this.#settleInHand();
+		if (!this.#started) {
+			this.#started = true;
+			this.#run().catch((cause) => this.#fail(new MailboxEventStreamError({
+				_tag: "StreamDisconnectedError",
+				message: `The mailbox event stream failed: ${String(cause)}`,
+				cursor: this.#cursor
+			})));
+		}
+		for (;;) {
+			if (this.#closed) return {
+				done: true,
+				value: void 0
+			};
+			const event = this.#queue.shift();
+			if (event !== void 0) {
+				this.#inHand = event;
+				return {
+					done: false,
+					value: event
+				};
+			}
+			const draining = this.#draining;
+			this.#draining = void 0;
+			draining?.resolve();
+			this.#ack();
+			if (this.#error !== void 0) throw this.#errorAtCursor(this.#error);
+			if (this.#ended) return {
+				done: true,
+				value: void 0
+			};
+			await new Promise((resolve) => {
+				this.#waiting = { resolve };
+			});
+		}
+	}
+	/**
+	* The failure as of the last handled event. Events buffered before the failure are still handed
+	* out, so the cursor recorded when the connection ended can trail the one to resume from.
+	*/
+	#errorAtCursor(error) {
+		if (error.cursor === this.#cursor) return error;
+		return this.#withCursor(error);
+	}
+	#settleInHand() {
+		if (this.#inHand === void 0) return;
+		this.#cursor = this.#inHand.cursor;
+		this.#inHand = void 0;
+		this.#unacked += 1;
+		if (this.#unacked >= ACK_EVERY) this.#ack();
+	}
+	#ack() {
+		const socket = this.#socket;
+		if (this.#unacked === 0 || this.#cursor === void 0 || socket?.readyState !== OPEN) return;
+		socket.send(JSON.stringify({
+			kind: "ack",
+			cursor: this.#cursor
+		}));
+		this.#unacked = 0;
+	}
+	/** Where a new connection starts: after every event this stream already holds. */
+	#resumeCursor() {
+		return this.#queue.at(-1)?.cursor ?? this.#inHand?.cursor ?? this.#cursor;
+	}
+	#wake() {
+		const waiting = this.#waiting;
+		this.#waiting = void 0;
+		waiting?.resolve();
+	}
+	#fail(error) {
+		if (this.#ended) return;
+		this.#error = error;
+		this.#ended = true;
+		this.#callerSignal?.removeEventListener("abort", this.#onCallerAbort);
+		this.#socket?.close(1e3);
+		this.#stop.abort();
+		this.#wake();
+	}
+	async #run() {
+		let attempt = 0;
+		while (!this.#ended) {
+			if (this.#queue.length > 0) {
+				await new Promise((resolve) => {
+					const done = () => {
+						this.#stop.signal.removeEventListener("abort", done);
+						resolve();
+					};
+					this.#draining = { resolve: done };
+					this.#stop.signal.addEventListener("abort", done, { once: true });
+				});
+				if (this.#ended) return;
+			}
+			const outcome = await this.#connect(() => {
+				attempt = 0;
+			});
+			if (this.#ended || outcome.kind === "stopped") return;
+			let result;
+			if (outcome.kind === "closed") result = closeOutcome(outcome.code);
+			else {
+				const refusal = await this.#diagnose();
+				result = refusal === void 0 ? outcomeOf("StreamDisconnectedError", true) : refusalOutcome(refusal);
+			}
+			if (!result.retry || this.#options.reconnect === false) {
+				this.#fail(this.#withCursor(result.error));
+				return;
+			}
+			const backoff = Math.min(RETRY_MAX_MILLIS, RETRY_BASE_MILLIS * 2 ** attempt);
+			attempt += 1;
+			await sleep(result.retryAfterMillis ?? backoff / 2 + Math.random() * (backoff / 2), this.#stop.signal);
+		}
+	}
+	#withCursor(error) {
+		return new MailboxEventStreamError({
+			...error,
+			message: error.message,
+			cursor: this.#cursor
+		});
+	}
+	/** One connection, from upgrade to close. `onLive` runs once replay has caught up. */
+	#connect(onLive) {
+		return new Promise((resolve) => {
+			const WebSocketImplementation = this.#options.WebSocket ?? globalWebSocket();
+			if (WebSocketImplementation === void 0) {
+				this.#fail(new MailboxEventStreamError({
+					_tag: "StreamClientError",
+					message: "This runtime has no WebSocket; pass one as the `WebSocket` option."
+				}));
+				return resolve({ kind: "stopped" });
+			}
+			const url = mailboxEventsUrl(this.#connection, {
+				...this.#options,
+				cursor: this.#resumeCursor()
+			});
+			let opened = false;
+			let settled = false;
+			let idleTimer;
+			const armIdle = () => {
+				clearTimeout(idleTimer);
+				idleTimer = setTimeout(() => {
+					settle(opened ? {
+						kind: "closed",
+						code: 1006
+					} : { kind: "refused" });
+					socket.close(1e3);
+				}, MAILBOX_EVENT_STREAM_IDLE_MILLIS);
+			};
+			const settle = (result) => {
+				if (settled) return;
+				settled = true;
+				clearTimeout(idleTimer);
+				this.#stop.signal.removeEventListener("abort", onStop);
+				if (this.#socket === socket) this.#socket = void 0;
+				resolve(result);
+			};
+			const onStop = () => settle({ kind: "stopped" });
+			let socket;
+			try {
+				socket = new WebSocketImplementation(url.toString(), { headers: this.#connection.headers });
+			} catch (cause) {
+				this.#fail(new MailboxEventStreamError({
+					_tag: "StreamClientError",
+					message: `This runtime's WebSocket cannot send request headers; pass one that can as the \`WebSocket\` option. ${String(cause)}`,
+					cursor: this.#cursor
+				}));
+				return resolve({ kind: "stopped" });
+			}
+			this.#socket = socket;
+			this.#stop.signal.addEventListener("abort", onStop, { once: true });
+			armIdle();
+			socket.addEventListener("open", () => {
+				opened = true;
+			});
+			socket.addEventListener("message", (message) => {
+				if (this.#ended) return;
+				if (!settled) armIdle();
+				const frame = decodeFrame(message.data);
+				if (frame === void 0) {
+					this.#fail(new MailboxEventStreamError({
+						_tag: "StreamProtocolError",
+						message: DESCRIPTION.StreamProtocolError,
+						cursor: this.#cursor
+					}));
+					socket.close(1e3);
+					return;
+				}
+				if (frame.kind === "event") {
+					this.#queue.push({
+						cursor: frame.cursor,
+						id: frame.id,
+						type: frame.event.type,
+						timestamp: frame.event.timestamp,
+						data: isRecord(frame.event.data) ? frame.event.data : {}
+					});
+					this.#wake();
+					return;
+				}
+				if (frame.kind === "live") {
+					onLive();
+					this.#options.onLive?.();
+				}
+				if (this.#queue.length === 0 && this.#inHand === void 0) {
+					if (this.#cursor !== frame.cursor) this.#unacked += 1;
+					this.#cursor = frame.cursor;
+					this.#ack();
+				}
+			});
+			socket.addEventListener("error", () => {});
+			socket.addEventListener("close", (close) => {
+				settle(opened ? {
+					kind: "closed",
+					code: close.code
+				} : { kind: "refused" });
+			});
+		});
+	}
+	/**
+	* Why an upgrade was refused. The events host answers a plain GET with the same refusal an
+	* upgrade gets, so the status and the error body are readable even where the WebSocket API
+	* hides them. Undefined when the host would have accepted (426) or could not be reached: both
+	* are worth a retry.
+	*/
+	async #diagnose() {
+		const url = mailboxEventsUrl(this.#connection, {
+			...this.#options,
+			cursor: this.#resumeCursor()
+		});
+		url.protocol = url.protocol === "wss:" ? "https:" : "http:";
+		const deadline = new AbortController();
+		const onStop = () => deadline.abort();
+		this.#stop.signal.addEventListener("abort", onStop, { once: true });
+		let timer;
+		const expired = new Promise((resolve) => {
+			timer = setTimeout(() => {
+				deadline.abort();
+				resolve(void 0);
+			}, DIAGNOSE_TIMEOUT_MILLIS);
+		});
+		const diagnosis = (async () => {
+			try {
+				const response = await (this.#connection.fetch ?? fetch)(url, {
+					headers: this.#connection.headers,
+					signal: deadline.signal
+				});
+				if (response.status === 426) {
+					await response.body?.cancel();
+					return;
+				}
+				const retryAfter = Number(response.headers.get("retry-after"));
+				return {
+					status: response.status,
+					body: await readRefusalBody(response),
+					retryAfterSeconds: Number.isFinite(retryAfter) && retryAfter > 0 ? retryAfter : void 0
+				};
+			} catch {
+				return;
+			}
+		})();
+		try {
+			return await Promise.race([diagnosis, expired]);
+		} finally {
+			clearTimeout(timer);
+			this.#stop.signal.removeEventListener("abort", onStop);
+		}
+	}
+};
+/** The refusal's JSON body, or undefined when it is not JSON; reads at most {@link REFUSAL_BODY_LIMIT}. */
+const readRefusalBody = async (response) => {
+	const reader = response.body?.getReader();
+	if (reader === void 0) return void 0;
+	const chunks = [];
+	let size = 0;
+	try {
+		while (size < REFUSAL_BODY_LIMIT) {
+			const { done, value } = await reader.read();
+			if (done) break;
+			chunks.push(value);
+			size += value.byteLength;
+		}
+	} finally {
+		await reader.cancel().catch(() => void 0);
+	}
+	const bytes = new Uint8Array(Math.min(size, REFUSAL_BODY_LIMIT));
+	let offset = 0;
+	for (const chunk of chunks) {
+		const room = bytes.length - offset;
+		if (room <= 0) break;
+		bytes.set(chunk.subarray(0, room), offset);
+		offset += Math.min(chunk.byteLength, room);
+	}
+	try {
+		return JSON.parse(new TextDecoder().decode(bytes));
+	} catch {
+		return;
+	}
+};
+//#endregion
+export { MailboxEventStreamError as n, MailboxEventStream as t };
+
+//# sourceMappingURL=mailbox-events-CcWm8lO4.js.map