@shadow-js/realtime 0.0.0-stage → 1.0.0

package/dist/dev/cloudflare/core.js

@@ -0,0 +1,701 @@
+import { RealtimeError } from "../errors.js";
+import { historyKey, seqOfKey } from "./wire.js";
+//#region src/cloudflare/core.ts
+const META = "meta";
+const MESSAGES = "h:";
+const MEMBERS = "p:";
+const KEYS = "k:";
+const KEY_INDEX = "x:";
+/** `x:` + 16 digits + `:`; what follows is the idempotency key. */
+const KEY_INDEX_PREFIX = 19;
+/** The platform accepts at most 128 keys in one `delete`, `put` or `get`. */
+const BATCH = 128;
+/** The most messages one operation deletes; a larger backlog is finished by the next operation or alarm. */
+const TRIM_MAX = 1024;
+/** Waiting this long after the first idempotency key expires lets one alarm sweep many. */
+const SWEEP_SLACK_MS = 5e3;
+/** The same for retained messages. */
+const HISTORY_SLACK_MS = 1e3;
+const PAGE_MESSAGES = 512;
+const PAGE_BYTES = 4194304;
+const REPLAY_MESSAGES = 1e4;
+const REPLAY_BYTES = 8388608;
+function pad(value) {
+	return String(value).padStart(16, "0");
+}
+function chunks(items) {
+	const out = [];
+	for (let at = 0; at < items.length; at += BATCH) out.push(items.slice(at, at + BATCH));
+	return out;
+}
+function sizeOf(message) {
+	return message.data.length + message.event.length + 96;
+}
+/**
+* The single writer of one channel.
+* @internal
+*/
+var ChannelCore = class {
+	#storage;
+	#now;
+	#maxMembers;
+	#sockets = /* @__PURE__ */ new Set();
+	#tail = Promise.resolve();
+	#meta;
+	#members;
+	/** The alarm time the storage holds: `undefined` unknown, `null` none. */
+	#alarmAt;
+	constructor(options) {
+		this.#storage = options.storage;
+		this.#now = options.now ?? Date.now;
+		this.#maxMembers = options.maxMembers ?? 1e4;
+	}
+	/** Registers sockets that were open before this instance was created (the runtime kept them while the object slept). */
+	adopt(sockets) {
+		for (const socket of sockets) this.#sockets.add(socket);
+	}
+	/** Forgets a socket that closed. */
+	detach(socket) {
+		this.#sockets.delete(socket);
+	}
+	/** The number of sockets attached. */
+	get sockets() {
+		return this.#sockets.size;
+	}
+	/** Runs `task` after every earlier task finished. A failure drops the caches, so the next task reads the storage afresh. */
+	#run(task) {
+		const result = this.#tail.then(task).catch((error) => {
+			if (!(error instanceof RealtimeError)) {
+				this.#meta = void 0;
+				this.#members = void 0;
+				this.#alarmAt = void 0;
+			}
+			throw error;
+		});
+		this.#tail = result.then(() => void 0, () => void 0);
+		return result;
+	}
+	async #metaFor(channel) {
+		const meta = await this.#storedMeta();
+		if (meta !== void 0) {
+			if (meta.channel !== channel) throw new RealtimeError("conflict", "the object belongs to another channel");
+			return meta;
+		}
+		const fresh = {
+			v: 1,
+			channel,
+			head: 0,
+			oldest: 0,
+			oldestAt: 0,
+			keep: 0,
+			ttlMs: 0,
+			keysDue: 0,
+			presenceDue: 0,
+			graceMs: 0,
+			idleMs: 0,
+			touched: this.#now()
+		};
+		this.#meta = fresh;
+		return fresh;
+	}
+	async #storedMeta() {
+		if (this.#meta === void 0) this.#meta = await this.#storage.get(META);
+		return this.#meta;
+	}
+	async #loadMembers() {
+		if (this.#members === void 0) {
+			const rows = await this.#storage.list({ prefix: MEMBERS });
+			const members = /* @__PURE__ */ new Map();
+			for (const [key, record] of rows) members.set(key.slice(2), {
+				member: record.member,
+				expires: record.expires,
+				stored: record.expires
+			});
+			this.#members = members;
+		}
+		return this.#members;
+	}
+	/** Writes `puts` and `deletes` and the metadata in one transaction. */
+	async #commit(meta, puts, deletes) {
+		await this.#storage.transaction(async (transaction) => {
+			await transaction.put({
+				...puts,
+				[META]: meta
+			});
+			for (const batch of chunks(deletes)) await transaction.delete(batch);
+		});
+		this.#meta = meta;
+	}
+	#send(socket, text) {
+		try {
+			socket.send(text);
+			return true;
+		} catch {
+			this.#sockets.delete(socket);
+			try {
+				socket.close(1011, "write failed");
+			} catch {}
+			return false;
+		}
+	}
+	#broadcast(frame) {
+		if (this.#sockets.size === 0) return;
+		const text = JSON.stringify(frame);
+		for (const socket of [...this.#sockets]) this.#send(socket, text);
+	}
+	#emit(op, member) {
+		this.#broadcast({
+			t: "pres",
+			op,
+			member
+		});
+	}
+	/**
+	* Assigns the next seq, retains the message, remembers the key and sends the message to every attached socket.
+	*
+	* @param channel The channel name.
+	* @param entry The message.
+	* @param options Retention and the idempotency key.
+	* @param idleMs Forget the channel after this long without activity (0 keeps it).
+	* @returns The seq and whether the key was already accepted.
+	*/
+	publish(channel, entry, options, idleMs = 0) {
+		return this.#run(async () => {
+			const meta = await this.#metaFor(channel);
+			const now = this.#now();
+			if (options.key !== void 0) {
+				const known = await this.#storage.get(KEYS + options.key);
+				if (known !== void 0 && known.expires > now) return {
+					seq: known.seq,
+					duplicate: true
+				};
+			}
+			const seq = meta.head + 1;
+			const message = {
+				seq,
+				event: entry.event,
+				data: entry.data,
+				at: now,
+				...entry.publisher === void 0 ? {} : { publisher: entry.publisher },
+				...entry.user === void 0 ? {} : { user: entry.user }
+			};
+			const plan = await this.#planTrim(meta, now, options.history, options.historyTtlMs, 1);
+			const next = {
+				...meta,
+				head: seq,
+				keep: options.history,
+				ttlMs: options.historyTtlMs,
+				idleMs,
+				touched: now,
+				oldest: plan.oldest,
+				oldestAt: plan.oldestAt
+			};
+			const puts = {};
+			if (options.history > 0) {
+				puts[historyKey(seq)] = message;
+				if (next.oldest === 0) {
+					next.oldest = seq;
+					next.oldestAt = now;
+				}
+			}
+			if (options.key !== void 0) {
+				const expires = now + options.idempotencyTtlMs;
+				puts[KEYS + options.key] = {
+					seq,
+					expires
+				};
+				puts[`${KEY_INDEX}${pad(expires)}:${options.key}`] = 1;
+				const due = expires + SWEEP_SLACK_MS;
+				next.keysDue = next.keysDue === 0 ? due : Math.min(next.keysDue, due);
+			}
+			await this.#commit(next, puts, plan.deletes);
+			this.#broadcast({
+				t: "msg",
+				m: message
+			});
+			await this.#schedule(next);
+			return {
+				seq,
+				duplicate: false
+			};
+		});
+	}
+	/**
+	* Works out which retained messages to delete so that, after `extra` more messages are stored, at most `keep` remain and
+	* none is older than `ttlMs`. It reads at most a few pages and deletes at most {@link TRIM_MAX} messages.
+	*/
+	async #planTrim(meta, now, keep, ttlMs, extra) {
+		const deletes = [];
+		let oldest = meta.oldest;
+		let oldestAt = meta.oldestAt;
+		if (oldest === 0) return {
+			deletes,
+			oldest: 0,
+			oldestAt: 0
+		};
+		const target = meta.head + 1 + extra - keep;
+		if (oldest < target) {
+			const stop = Math.min(target, meta.head + 1, oldest + TRIM_MAX);
+			for (let seq = oldest; seq < stop; seq += 1) deletes.push(historyKey(seq));
+			oldest = stop;
+			if (oldest > meta.head) return {
+				deletes,
+				oldest: 0,
+				oldestAt: 0
+			};
+			const first = await this.#firstFrom(oldest);
+			if (first === void 0) return {
+				deletes,
+				oldest: 0,
+				oldestAt: 0
+			};
+			oldest = first.seq;
+			oldestAt = first.at;
+		}
+		const cutoff = now - ttlMs;
+		while (oldestAt < cutoff && deletes.length < TRIM_MAX) {
+			const page = await this.#storage.list({
+				prefix: MESSAGES,
+				start: historyKey(oldest),
+				limit: BATCH
+			});
+			let survivor;
+			for (const message of page.values()) {
+				if (message.at >= cutoff || deletes.length >= TRIM_MAX) {
+					survivor = message;
+					break;
+				}
+				deletes.push(historyKey(message.seq));
+			}
+			if (survivor !== void 0) {
+				oldest = survivor.seq;
+				oldestAt = survivor.at;
+				break;
+			}
+			if (page.size < BATCH) return {
+				deletes,
+				oldest: 0,
+				oldestAt: 0
+			};
+			const last = deletes.length === 0 ? void 0 : deletes[deletes.length - 1];
+			if (last === void 0) break;
+			oldest = seqOfKey(last) + 1;
+			const next = await this.#firstFrom(oldest);
+			if (next === void 0) return {
+				deletes,
+				oldest: 0,
+				oldestAt: 0
+			};
+			oldest = next.seq;
+			oldestAt = next.at;
+		}
+		return {
+			deletes,
+			oldest,
+			oldestAt
+		};
+	}
+	async #firstFrom(seq) {
+		const page = await this.#storage.list({
+			prefix: MESSAGES,
+			start: historyKey(seq),
+			limit: 1
+		});
+		for (const message of page.values()) return message;
+	}
+	/** Whether retained messages are past their time or above the count of the last publish. */
+	#retentionDue(meta, now) {
+		if (meta.oldest === 0) return false;
+		return meta.head - meta.oldest + 1 > meta.keep || meta.oldestAt + meta.ttlMs < now;
+	}
+	async #retain(meta, now) {
+		if (!this.#retentionDue(meta, now)) return false;
+		const plan = await this.#planTrim(meta, now, meta.keep, meta.ttlMs, 0);
+		if (plan.deletes.length === 0 && plan.oldest === meta.oldest) return false;
+		await this.#commit({
+			...meta,
+			oldest: plan.oldest,
+			oldestAt: plan.oldestAt
+		}, {}, plan.deletes);
+		return true;
+	}
+	/**
+	* Reads retained messages after a seq.
+	*
+	* @param channel The channel name.
+	* @param after The last seq the caller holds.
+	* @param limit The most messages to return (0 asks for the head only).
+	* @returns A page; `more` says retained messages remain after it.
+	*/
+	history(channel, after, limit) {
+		return this.#run(async () => {
+			let meta = await this.#metaFor(channel);
+			if (await this.#retain(meta, this.#now())) meta = this.#meta ?? meta;
+			if (limit <= 0 || after >= meta.head || meta.oldest === 0) return {
+				messages: [],
+				head: meta.head,
+				oldest: meta.oldest,
+				more: false
+			};
+			const cap = Math.min(limit, PAGE_MESSAGES);
+			const rows = await this.#storage.list({
+				prefix: MESSAGES,
+				start: historyKey(Math.max(after + 1, meta.oldest)),
+				limit: cap
+			});
+			const messages = [];
+			let bytes = 0;
+			for (const message of rows.values()) {
+				if (messages.length > 0 && bytes + sizeOf(message) > PAGE_BYTES) break;
+				messages.push(message);
+				bytes += sizeOf(message);
+			}
+			const last = messages[messages.length - 1];
+			return {
+				messages,
+				head: meta.head,
+				oldest: meta.oldest,
+				more: last !== void 0 && last.seq < meta.head
+			};
+		});
+	}
+	/**
+	* Starts sending a socket the channel's messages and presence events: the head, the live members, the messages after
+	* `after` that are retained, then every later event. Nothing can interleave, because it runs in the queue.
+	*
+	* @param socket The server end of the subscribe socket.
+	* @param channel The channel name.
+	* @param after The last seq the subscriber holds, when it is resuming.
+	*/
+	attach(socket, channel, after) {
+		return this.#run(async () => {
+			let meta = await this.#metaFor(channel);
+			const now = this.#now();
+			if (await this.#retain(meta, now)) meta = this.#meta ?? meta;
+			const members = await this.#loadMembers();
+			const live = [];
+			for (const state of members.values()) if (state.expires > now) live.push(state.member);
+			const frames = [JSON.stringify({
+				t: "ready",
+				head: meta.head,
+				oldest: meta.oldest
+			}), JSON.stringify({
+				t: "snap",
+				members: live
+			})];
+			let truncated = false;
+			if (after !== void 0 && after < meta.head && meta.oldest > 0) {
+				let cursor = Math.max(after, meta.oldest - 1);
+				let count = 0;
+				let bytes = 0;
+				replay: while (cursor < meta.head) {
+					const rows = await this.#storage.list({
+						prefix: MESSAGES,
+						start: historyKey(cursor + 1),
+						limit: BATCH
+					});
+					if (rows.size === 0) break;
+					for (const message of rows.values()) {
+						frames.push(JSON.stringify({
+							t: "msg",
+							m: message
+						}));
+						cursor = message.seq;
+						count += 1;
+						bytes += sizeOf(message);
+						if (count >= REPLAY_MESSAGES || bytes >= REPLAY_BYTES) {
+							truncated = cursor < meta.head;
+							break replay;
+						}
+					}
+					if (rows.size < BATCH) break;
+				}
+			}
+			if (truncated) frames.push(JSON.stringify({ t: "more" }));
+			for (const frame of frames) try {
+				socket.send(frame);
+			} catch {
+				return;
+			}
+			this.#sockets.add(socket);
+		});
+	}
+	/**
+	* Adds or updates a member. An older version is ignored; the first sighting is a `join`, a newer version a `set`.
+	*
+	* @param channel The channel name.
+	* @param member The member.
+	* @param ttlMs Milliseconds until it expires without a touch.
+	* @param graceMs Milliseconds after expiry that the alarm waits before it reaps (so the hub's own reap comes first).
+	*/
+	presenceSet(channel, member, ttlMs, graceMs) {
+		return this.#run(async () => {
+			const meta = await this.#metaFor(channel);
+			const members = await this.#loadMembers();
+			const known = members.get(member.id);
+			if (known !== void 0 && known.member.v > member.v) return;
+			if (known === void 0 && members.size >= this.#maxMembers) throw new RealtimeError("limit", "the channel has too many presence members");
+			const now = this.#now();
+			const expires = now + ttlMs;
+			const changed = known === void 0 || known.member.v < member.v;
+			const due = expires + graceMs;
+			const next = {
+				...meta,
+				graceMs,
+				touched: now,
+				presenceDue: meta.presenceDue === 0 ? due : Math.min(meta.presenceDue, due)
+			};
+			const persist = changed || known === void 0 || expires - known.stored >= ttlMs / 2;
+			if (persist || next.presenceDue !== meta.presenceDue || next.graceMs !== meta.graceMs) await this.#commit(next, persist ? { [MEMBERS + member.id]: {
+				member,
+				expires
+			} } : {}, []);
+			members.set(member.id, {
+				member,
+				expires,
+				stored: persist ? expires : known?.stored ?? expires
+			});
+			if (known === void 0) this.#emit("join", member);
+			else if (known.member.v < member.v) this.#emit("set", member);
+			await this.#schedule(next);
+		});
+	}
+	/**
+	* Removes a member.
+	*
+	* @param channel The channel name.
+	* @param id The member id.
+	* @returns True when the member existed (and a `leave` was sent); false otherwise.
+	*/
+	presenceRemove(channel, id) {
+		return this.#run(async () => {
+			const meta = await this.#metaFor(channel);
+			const members = await this.#loadMembers();
+			const known = members.get(id);
+			if (known === void 0) return false;
+			const next = members.size === 1 ? {
+				...meta,
+				presenceDue: 0
+			} : meta;
+			await this.#commit(next, {}, [MEMBERS + id]);
+			members.delete(id);
+			this.#emit("leave", known.member);
+			await this.#schedule(next);
+			return true;
+		});
+	}
+	/**
+	* The members that have not expired.
+	*
+	* @param channel The channel name.
+	* @returns The members.
+	*/
+	presenceList(channel) {
+		return this.#run(async () => {
+			await this.#metaFor(channel);
+			const members = await this.#loadMembers();
+			const now = this.#now();
+			const out = [];
+			for (const state of members.values()) if (state.expires > now) out.push(state.member);
+			return out;
+		});
+	}
+	/**
+	* Extends the expiry of members. The storage is written only when the new expiry is at least half a time to live beyond
+	* the stored one, so a heartbeat every few seconds costs a write every few beats; a restart in between loses at most
+	* that half, which a heartbeat repairs long before the member would expire.
+	*
+	* @param channel The channel name.
+	* @param ids The member ids.
+	* @param ttlMs Milliseconds until they expire without another touch.
+	* @returns The ids that no longer exist.
+	*/
+	presenceTouch(channel, ids, ttlMs) {
+		return this.#run(async () => {
+			const meta = await this.#metaFor(channel);
+			const members = await this.#loadMembers();
+			const expires = this.#now() + ttlMs;
+			const missing = [];
+			const puts = {};
+			const written = [];
+			let touched = 0;
+			for (const id of ids) {
+				const state = members.get(id);
+				if (state === void 0) {
+					missing.push(id);
+					continue;
+				}
+				state.expires = expires;
+				touched += 1;
+				if (state.expires - state.stored >= ttlMs / 2) {
+					puts[MEMBERS + id] = {
+						member: state.member,
+						expires: state.expires
+					};
+					written.push(state);
+				}
+			}
+			const keys = Object.keys(puts);
+			for (const batch of chunks(keys)) {
+				const part = {};
+				for (const key of batch) part[key] = puts[key];
+				await this.#storage.put(part);
+			}
+			for (const state of written) state.stored = state.expires;
+			const due = expires + meta.graceMs;
+			if (touched > 0 && (meta.presenceDue === 0 || due < meta.presenceDue)) {
+				const next = {
+					...meta,
+					presenceDue: due
+				};
+				await this.#commit(next, {}, []);
+				await this.#schedule(next);
+			}
+			return missing;
+		});
+	}
+	/**
+	* Removes every expired member and sends one `leave` for each.
+	*
+	* @param channel The channel name.
+	* @returns The members removed.
+	*/
+	presenceReap(channel) {
+		return this.#run(async () => {
+			const meta = await this.#metaFor(channel);
+			return this.#reap(meta, this.#now());
+		});
+	}
+	async #reap(meta, now) {
+		const members = await this.#loadMembers();
+		const gone = [];
+		for (const state of members.values()) if (state.expires <= now) gone.push(state);
+		if (gone.length === 0) return [];
+		let due = 0;
+		for (const state of members.values()) if (state.expires > now) {
+			const at = state.expires + meta.graceMs;
+			due = due === 0 ? at : Math.min(due, at);
+		}
+		const next = {
+			...meta,
+			presenceDue: due
+		};
+		await this.#commit(next, {}, gone.map((state) => MEMBERS + state.member.id));
+		for (const state of gone) {
+			members.delete(state.member.id);
+			this.#emit("leave", state.member);
+		}
+		return gone.map((state) => state.member);
+	}
+	/** The time the next alarm is due, `undefined` when nothing is pending. */
+	#nextDue(meta, now) {
+		let due = 0;
+		const consider = (at) => {
+			if (at > 0 && (due === 0 || at < due)) due = at;
+		};
+		consider(meta.presenceDue);
+		consider(meta.keysDue);
+		if (meta.oldest > 0) consider(meta.head - meta.oldest + 1 > meta.keep ? now : meta.oldestAt + meta.ttlMs + HISTORY_SLACK_MS);
+		if (meta.idleMs > 0) {
+			const idleAt = meta.touched + meta.idleMs;
+			consider(this.#sockets.size > 0 && idleAt <= now ? now + meta.idleMs : idleAt);
+		}
+		return due === 0 ? void 0 : Math.max(due, now);
+	}
+	/** Makes the storage's alarm fire no later than the next thing that is due. An earlier alarm is left alone: it wakes, finds nothing, and sets the right time. */
+	async #schedule(meta) {
+		const now = this.#now();
+		const due = this.#nextDue(meta, now);
+		if (this.#alarmAt === void 0) this.#alarmAt = await this.#storage.getAlarm();
+		if (due === void 0) {
+			if (this.#alarmAt !== null) {
+				await this.#storage.deleteAlarm();
+				this.#alarmAt = null;
+			}
+			return;
+		}
+		if (this.#alarmAt === null || this.#alarmAt > due) {
+			await this.#storage.setAlarm(due);
+			this.#alarmAt = due;
+		}
+	}
+	/** Deletes idempotency keys that expired, in batches. */
+	async #sweepKeys(meta, now) {
+		for (let pass = 0; pass < 32; pass += 1) {
+			const rows = await this.#storage.list({
+				prefix: KEY_INDEX,
+				end: KEY_INDEX + pad(now + 1),
+				limit: BATCH
+			});
+			if (rows.size === 0) break;
+			const indexKeys = [...rows.keys()];
+			const names = indexKeys.map((key) => key.slice(KEY_INDEX_PREFIX));
+			const records = await this.#storage.get(names.map((name) => KEYS + name));
+			const deletes = [...indexKeys];
+			for (const name of names) {
+				const record = records.get(KEYS + name);
+				if (record === void 0 || record.expires <= now) deletes.push(KEYS + name);
+			}
+			await this.#storage.transaction(async (transaction) => {
+				for (const batch of chunks(deletes)) await transaction.delete(batch);
+			});
+			if (rows.size < BATCH) break;
+		}
+		const first = await this.#storage.list({
+			prefix: KEY_INDEX,
+			limit: 1
+		});
+		let keysDue = 0;
+		for (const key of first.keys()) keysDue = Number(key.slice(2, 18)) + SWEEP_SLACK_MS;
+		return {
+			...meta,
+			keysDue
+		};
+	}
+	/**
+	* The alarm handler: reaps expired presence members (one `leave` each), sweeps expired idempotency keys, trims retained
+	* messages that expired, forgets a channel that has been idle for its `idleMs`, and sets the next alarm. It is safe to run
+	* more often than needed, and to run again after a failure.
+	*/
+	alarm() {
+		return this.#run(async () => {
+			this.#alarmAt = null;
+			let meta = await this.#storedMeta();
+			if (meta === void 0) return;
+			const now = this.#now();
+			if (meta.presenceDue > 0 && meta.presenceDue <= now) {
+				await this.#reap(meta, now);
+				meta = this.#meta ?? meta;
+				let due = 0;
+				for (const state of (await this.#loadMembers()).values()) {
+					const at = state.expires + meta.graceMs;
+					due = due === 0 ? at : Math.min(due, at);
+				}
+				if (due !== meta.presenceDue) {
+					meta = {
+						...meta,
+						presenceDue: due
+					};
+					await this.#commit(meta, {}, []);
+				}
+			}
+			if (meta.keysDue > 0 && meta.keysDue <= now) {
+				meta = await this.#sweepKeys(meta, now);
+				await this.#commit(meta, {}, []);
+			}
+			if (await this.#retain(meta, now)) meta = this.#meta ?? meta;
+			if (meta.idleMs > 0 && meta.touched + meta.idleMs <= now && meta.oldest === 0 && meta.presenceDue === 0 && meta.keysDue === 0 && this.#sockets.size === 0) {
+				await this.#storage.deleteAll();
+				this.#meta = void 0;
+				this.#members = void 0;
+				this.#alarmAt = null;
+				return;
+			}
+			await this.#schedule(meta);
+		});
+	}
+};
+//#endregion
+export { ChannelCore };
+
+//# sourceMappingURL=core.js.map