@headless-lms/core 0.3.0 → 0.5.0

package/dist/discussion/live.js

@@ -0,0 +1,642 @@
+import { describeError, noopLogger } from "../shared/logger.js";
+import { discussionEvents } from "./events.js";
+import { z } from "zod";
+//#region src/discussion/live.ts
+const CHAT_CHANNEL = "discussion.chats";
+const TYPING = "typing";
+const HEARTBEAT_MS = 25e3;
+const PUBLISH_TIMEOUT_MS = 2e3;
+const FLUSH_MS = 1e3;
+const CLOSE_TIMEOUT_MS = 2e3;
+const MAX_CHATS = 16;
+const MAX_PENDING = 5e3;
+const STREAM_QUEUE = 256;
+const SENT = discussionEvents.messageSent.type;
+const UPDATED = discussionEvents.messageUpdated.type;
+const DELETED = discussionEvents.messageDeleted.type;
+const REACTIONS = discussionEvents.messageReactionsChanged.type;
+const CREATED = discussionEvents.chatCreated.type;
+const CHAT_UPDATED = discussionEvents.chatUpdated.type;
+const ADDED = discussionEvents.chatParticipantAdded.type;
+const READ = discussionEvents.chatRead.type;
+const MUTED = discussionEvents.chatMuted.type;
+const chatChangeSchema = z.object({
+	event: z.string(),
+	orgId: z.string(),
+	communityId: z.string(),
+	chatId: z.string(),
+	messageId: z.string().optional(),
+	orgUserId: z.string().optional(),
+	members: z.array(z.string()).optional(),
+	reaction: z.string().nullable().optional(),
+	until: z.string().optional()
+});
+/** Publishes a change, logging and dropping it when the publish fails or has
+*  not finished within 2 s. Never throws. */
+async function publishChange(pubsub, change, logger, timeoutMs = PUBLISH_TIMEOUT_MS) {
+	let timer;
+	try {
+		await Promise.race([pubsub.publish(CHAT_CHANNEL, change), new Promise((_, reject) => {
+			timer = setTimeout(() => reject(/* @__PURE__ */ new Error("publish timed out")), timeoutMs);
+		})]);
+	} catch (error) {
+		logger.warn("live publish failed", {
+			orgId: change.orgId,
+			chatId: change.chatId,
+			event: change.event,
+			error: describeError(error)
+		});
+	} finally {
+		clearTimeout(timer);
+	}
+}
+function actorOf(event) {
+	const actor = event.metadata?.actorId;
+	return typeof actor === "string" ? [actor] : [];
+}
+function union(...lists) {
+	return [...new Set(lists.flat())].sort();
+}
+/** Publishes every chat change committed through the outbox to every instance. */
+var ChatLiveForwarder = class {
+	pubsub;
+	logger;
+	timeoutMs;
+	constructor(params) {
+		this.pubsub = params.pubsub;
+		this.logger = params.logger ?? noopLogger;
+		this.timeoutMs = params.timeoutMs ?? PUBLISH_TIMEOUT_MS;
+	}
+	attach(bus) {
+		const forward = (change) => publishChange(this.pubsub, change, this.logger, this.timeoutMs);
+		const chat = (event) => forward({
+			event: event.type,
+			orgId: event.orgId,
+			communityId: event.data.communityId,
+			chatId: event.data.id,
+			members: union(event.data.participantIds, actorOf(event))
+		});
+		const message = (event) => forward({
+			event: event.type,
+			orgId: event.orgId,
+			communityId: event.data.communityId,
+			chatId: event.data.chatId,
+			messageId: event.data.id
+		});
+		const member = (event) => forward({
+			event: event.type,
+			orgId: event.orgId,
+			communityId: event.data.communityId,
+			chatId: event.data.chatId,
+			orgUserId: event.data.orgUserId
+		});
+		bus.subscribe(discussionEvents.chatCreated, chat);
+		bus.subscribe(discussionEvents.chatUpdated, chat);
+		bus.subscribe(discussionEvents.chatParticipantAdded, (event) => forward({
+			event: event.type,
+			orgId: event.orgId,
+			communityId: event.data.communityId,
+			chatId: event.data.chatId,
+			orgUserId: event.data.orgUserId,
+			members: union([event.data.orgUserId], actorOf(event))
+		}));
+		bus.subscribe(discussionEvents.messageSent, message);
+		bus.subscribe(discussionEvents.messageUpdated, message);
+		bus.subscribe(discussionEvents.messageDeleted, message);
+		bus.subscribe(discussionEvents.messageReactionsChanged, (event) => forward({
+			event: event.type,
+			orgId: event.orgId,
+			communityId: event.data.communityId,
+			chatId: event.data.chatId,
+			messageId: event.data.messageId,
+			orgUserId: event.data.orgUserId,
+			reaction: event.data.reaction
+		}));
+		bus.subscribe(discussionEvents.chatRead, member);
+		bus.subscribe(discussionEvents.chatMuted, member);
+	}
+};
+var LiveStream = class {
+	orgId;
+	communityId;
+	orgUserId;
+	onEnd;
+	onOverflow;
+	done;
+	queue = [];
+	waiter = null;
+	ending = false;
+	finished = false;
+	resolveDone;
+	constructor(orgId, communityId, orgUserId, onEnd, onOverflow) {
+		this.orgId = orgId;
+		this.communityId = communityId;
+		this.orgUserId = orgUserId;
+		this.onEnd = onEnd;
+		this.onOverflow = onOverflow;
+		this.done = new Promise((resolve) => {
+			this.resolveDone = resolve;
+		});
+	}
+	get ended() {
+		return this.ending;
+	}
+	push(event) {
+		if (this.ending) return;
+		const waiter = this.waiter;
+		if (waiter) {
+			this.waiter = null;
+			waiter({
+				value: event,
+				done: false
+			});
+			return;
+		}
+		if (this.queue.length >= STREAM_QUEUE) {
+			this.queue = [{ type: "resync" }];
+			this.onOverflow(this);
+			return;
+		}
+		this.queue.push(event);
+	}
+	end(last) {
+		if (this.ending) return;
+		if (last) this.push(last);
+		this.ending = true;
+		this.onEnd(this);
+		const waiter = this.waiter;
+		if (waiter && this.queue.length === 0) {
+			this.waiter = null;
+			this.finish();
+			waiter({
+				value: void 0,
+				done: true
+			});
+		}
+	}
+	next() {
+		const event = this.queue.shift();
+		if (event) return Promise.resolve({
+			value: event,
+			done: false
+		});
+		if (this.ending) {
+			this.finish();
+			return Promise.resolve({
+				value: void 0,
+				done: true
+			});
+		}
+		return new Promise((resolve) => {
+			this.waiter = resolve;
+		});
+	}
+	return() {
+		this.queue = [];
+		this.end();
+		const waiter = this.waiter;
+		if (waiter) {
+			this.waiter = null;
+			waiter({
+				value: void 0,
+				done: true
+			});
+		}
+		this.finish();
+		return Promise.resolve({
+			value: void 0,
+			done: true
+		});
+	}
+	[Symbol.asyncIterator]() {
+		return this;
+	}
+	finish() {
+		if (this.finished) return;
+		this.finished = true;
+		this.resolveDone();
+	}
+};
+function coalesceKey(change) {
+	switch (change.event) {
+		case SENT:
+		case UPDATED:
+		case DELETED: return `message:${change.messageId}`;
+		case REACTIONS: return `reaction:${change.messageId}:${change.orgUserId}`;
+		case CREATED:
+		case CHAT_UPDATED:
+		case ADDED: return "chat";
+		case READ:
+		case MUTED: return `member:${change.orgUserId}`;
+		default: return null;
+	}
+}
+function merge(existing, next) {
+	switch (existing.event) {
+		case SENT:
+		case UPDATED:
+		case DELETED: {
+			const events = [existing.event, next.event];
+			const event = events.includes(SENT) ? SENT : events.includes(DELETED) ? DELETED : UPDATED;
+			return {
+				...next,
+				event
+			};
+		}
+		case CREATED:
+		case CHAT_UPDATED:
+		case ADDED: return {
+			...existing,
+			members: union(existing.members ?? [], next.members ?? [])
+		};
+		case REACTIONS: return next;
+		default: return existing;
+	}
+}
+const key = (orgId, id) => `${orgId}\u0000${id}`;
+/** This process's open chat streams, and the live delivery of every chat
+*  change to them. */
+var ChatHub = class {
+	pubsub;
+	reads;
+	logger;
+	flushMs;
+	closeTimeoutMs;
+	streams = /* @__PURE__ */ new Set();
+	byMember = /* @__PURE__ */ new Map();
+	byCommunity = /* @__PURE__ */ new Map();
+	queues = /* @__PURE__ */ new Map();
+	ready = [];
+	running = 0;
+	pending = 0;
+	dirty = /* @__PURE__ */ new Map();
+	flushing = false;
+	flushAgain = false;
+	closing = false;
+	unsubscribe = null;
+	flushTimer = null;
+	constructor(params) {
+		this.pubsub = params.pubsub;
+		this.reads = params.reads;
+		this.logger = params.logger ?? noopLogger;
+		this.flushMs = params.flushMs ?? FLUSH_MS;
+		this.closeTimeoutMs = params.closeTimeoutMs ?? CLOSE_TIMEOUT_MS;
+	}
+	async start() {
+		if (this.unsubscribe || this.closing) return;
+		this.unsubscribe = this.pubsub.subscribe(CHAT_CHANNEL, (message) => this.receive(message), () => this.reset());
+		this.flushTimer = setInterval(() => {
+			if (!this.flushing) this.flush();
+		}, this.flushMs);
+		this.flushTimer.unref();
+		this.logger.info("chat hub started");
+	}
+	/** Ends every stream with `closed { reason: 'shutdown' }` and waits, up to
+	*  2 s in all, for each to be read to its end. */
+	async close() {
+		if (this.closing) return;
+		this.closing = true;
+		this.unsubscribe?.();
+		this.unsubscribe = null;
+		if (this.flushTimer) clearInterval(this.flushTimer);
+		this.queues.clear();
+		this.ready = [];
+		this.pending = 0;
+		const streams = [...this.streams];
+		for (const stream of streams) stream.end({
+			type: "closed",
+			reason: "shutdown"
+		});
+		let timer;
+		await Promise.race([Promise.all(streams.map((stream) => stream.done)), new Promise((resolve) => {
+			timer = setTimeout(resolve, this.closeTimeoutMs);
+		})]);
+		clearTimeout(timer);
+		this.logger.info("chat hub closed", { streams: streams.length });
+	}
+	/** Registers one stream. It starts with `ready`, then the member's unread. */
+	open(registration) {
+		const { actor, communityId } = registration;
+		const stream = new LiveStream(actor.orgId, communityId, actor.id, (ended) => this.unregister(ended), (full) => this.markDirty(full.orgId, full.communityId, full.orgUserId));
+		if (this.closing) {
+			stream.end({
+				type: "closed",
+				reason: "shutdown"
+			});
+			return stream;
+		}
+		this.streams.add(stream);
+		this.index(this.byMember, key(stream.orgId, stream.orgUserId), stream);
+		this.index(this.byCommunity, key(stream.orgId, stream.communityId), stream);
+		stream.push({
+			type: "ready",
+			heartbeatMs: HEARTBEAT_MS
+		});
+		this.markDirty(stream.orgId, stream.communityId, stream.orgUserId);
+		this.flush();
+		this.logger.debug("chat stream opened", {
+			orgId: stream.orgId,
+			communityId,
+			streams: this.streams.size
+		});
+		return stream;
+	}
+	index(map, at, stream) {
+		const set = map.get(at) ?? /* @__PURE__ */ new Set();
+		set.add(stream);
+		map.set(at, set);
+	}
+	unindex(map, at, stream) {
+		const set = map.get(at);
+		set?.delete(stream);
+		if (set?.size === 0) map.delete(at);
+	}
+	unregister(stream) {
+		if (!this.streams.delete(stream)) return;
+		this.unindex(this.byMember, key(stream.orgId, stream.orgUserId), stream);
+		this.unindex(this.byCommunity, key(stream.orgId, stream.communityId), stream);
+		this.logger.debug("chat stream closed", {
+			orgId: stream.orgId,
+			communityId: stream.communityId,
+			streams: this.streams.size
+		});
+	}
+	streamsOf(orgId, communityId, orgUserId) {
+		return [...this.byMember.get(key(orgId, orgUserId)) ?? []].filter((stream) => stream.communityId === communityId);
+	}
+	communityStreams(orgId, communityId) {
+		return [...this.byCommunity.get(key(orgId, communityId)) ?? []];
+	}
+	receive(message) {
+		const parsed = chatChangeSchema.safeParse(message);
+		if (!parsed.success) {
+			this.logger.warn("chat change unreadable");
+			return;
+		}
+		const change = parsed.data;
+		if (this.closing || !this.byCommunity.has(key(change.orgId, change.communityId))) return;
+		const at = key(change.orgId, change.chatId);
+		const queue = this.queues.get(at) ?? {
+			pending: [],
+			running: false,
+			queued: false
+		};
+		this.queues.set(at, queue);
+		const coalesce = coalesceKey(change);
+		const index = coalesce === null ? -1 : queue.pending.findIndex((other) => coalesceKey(other) === coalesce);
+		if (index >= 0) queue.pending[index] = merge(queue.pending[index], change);
+		else {
+			if (this.pending >= MAX_PENDING) {
+				this.overflow();
+				return;
+			}
+			queue.pending.push(change);
+			this.pending += 1;
+		}
+		if (!queue.running && !queue.queued) {
+			queue.queued = true;
+			this.ready.push(at);
+		}
+		this.pump();
+	}
+	pump() {
+		while (this.running < MAX_CHATS && this.ready.length > 0) {
+			const at = this.ready.shift();
+			const queue = this.queues.get(at);
+			if (!queue) continue;
+			queue.queued = false;
+			const change = queue.pending.shift();
+			if (!change) {
+				this.queues.delete(at);
+				continue;
+			}
+			this.pending -= 1;
+			queue.running = true;
+			this.running += 1;
+			this.handle(change).finally(() => {
+				queue.running = false;
+				this.running -= 1;
+				if (this.queues.get(at) === queue) if (queue.pending.length > 0) {
+					queue.queued = true;
+					this.ready.push(at);
+				} else this.queues.delete(at);
+				this.pump();
+			});
+		}
+	}
+	overflow() {
+		this.logger.warn("chat hub queue full; dropping pending changes", { pending: this.pending });
+		for (const [at, queue] of this.queues) {
+			queue.pending = [];
+			queue.queued = false;
+			if (!queue.running) this.queues.delete(at);
+		}
+		this.ready = [];
+		this.pending = 0;
+		this.resync([...this.streams]);
+	}
+	reset() {
+		this.logger.info("chat hub reset", { streams: this.streams.size });
+		this.resync([...this.streams]);
+	}
+	resync(streams) {
+		for (const stream of streams) {
+			stream.push({ type: "resync" });
+			this.markDirty(stream.orgId, stream.communityId, stream.orgUserId);
+		}
+	}
+	async handle(change) {
+		try {
+			switch (change.event) {
+				case SENT:
+				case UPDATED:
+				case DELETED:
+					await this.onMessage(change);
+					return;
+				case REACTIONS:
+					await this.onReactions(change);
+					return;
+				case CREATED:
+				case CHAT_UPDATED:
+				case ADDED:
+					await this.onChat(change);
+					return;
+				case READ:
+				case MUTED:
+					if (change.orgUserId) this.markDirty(change.orgId, change.communityId, change.orgUserId, change.chatId);
+					return;
+				case TYPING:
+					await this.onTyping(change);
+					return;
+				default: this.logger.debug("chat change ignored", { event: change.event });
+			}
+		} catch (error) {
+			this.logger.error("chat change read failed", {
+				orgId: change.orgId,
+				chatId: change.chatId,
+				event: change.event,
+				error: describeError(error)
+			});
+			this.resync(this.communityStreams(change.orgId, change.communityId));
+		}
+	}
+	async participantStreams(change) {
+		const active = await this.reads.activeParticipants(change.orgId, change.chatId);
+		const members = [];
+		const streams = [];
+		for (const orgUserId of active) {
+			const local = this.streamsOf(change.orgId, change.communityId, orgUserId);
+			if (local.length > 0) {
+				members.push(orgUserId);
+				streams.push(...local);
+			}
+		}
+		return {
+			members,
+			streams
+		};
+	}
+	async onMessage(change) {
+		const { members, streams } = await this.participantStreams(change);
+		if (streams.length === 0 || !change.messageId) return;
+		const [view] = await this.reads.messageViews(change.orgId, [change.messageId]);
+		if (!view || view.chatId !== change.chatId) return;
+		const event = view.deletedAt ? {
+			type: "message.deleted",
+			chatId: change.chatId,
+			messageId: view.id,
+			deletedAt: view.deletedAt
+		} : {
+			type: change.event === SENT ? "message.created" : "message.updated",
+			chatId: change.chatId,
+			message: view
+		};
+		for (const stream of streams) stream.push(event);
+		if (change.event !== UPDATED || view.deletedAt) for (const orgUserId of members) this.markDirty(change.orgId, change.communityId, orgUserId, change.chatId);
+	}
+	async onReactions(change) {
+		const { streams } = await this.participantStreams(change);
+		if (streams.length === 0 || !change.messageId || !change.orgUserId) return;
+		const reactions = await this.reads.messageReactions(change.orgId, change.messageId);
+		for (const stream of streams) stream.push({
+			type: "message.reactions",
+			chatId: change.chatId,
+			messageId: change.messageId,
+			reactions,
+			orgUserId: change.orgUserId,
+			reaction: change.reaction ?? null
+		});
+	}
+	async onChat(change) {
+		const live = await this.reads.liveChat(change.orgId, change.chatId);
+		const active = new Set(live?.participantIds ?? []);
+		if (live) for (const orgUserId of active) {
+			const streams = this.streamsOf(change.orgId, change.communityId, orgUserId);
+			if (streams.length === 0) continue;
+			for (const stream of streams) stream.push({
+				type: "chat.updated",
+				chatId: change.chatId,
+				chat: live.chat,
+				participants: live.participants
+			});
+			this.markDirty(change.orgId, change.communityId, orgUserId, change.chatId);
+		}
+		for (const orgUserId of change.members ?? []) {
+			if (active.has(orgUserId)) continue;
+			const streams = this.streamsOf(change.orgId, change.communityId, orgUserId);
+			if (streams.length === 0) continue;
+			for (const stream of streams) stream.push({
+				type: "chat.removed",
+				chatId: change.chatId
+			});
+			this.markDirty(change.orgId, change.communityId, orgUserId);
+		}
+	}
+	async onTyping(change) {
+		if (!change.orgUserId || !change.until) return;
+		const { streams } = await this.participantStreams(change);
+		const until = new Date(change.until);
+		for (const stream of streams) {
+			if (stream.orgUserId === change.orgUserId) continue;
+			stream.push({
+				type: "typing",
+				chatId: change.chatId,
+				orgUserId: change.orgUserId,
+				until
+			});
+		}
+	}
+	markDirty(orgId, communityId, orgUserId, chatId) {
+		const at = key(orgId, communityId);
+		const group = this.dirty.get(at) ?? {
+			orgId,
+			communityId,
+			members: /* @__PURE__ */ new Map()
+		};
+		this.dirty.set(at, group);
+		const chats = group.members.get(orgUserId) ?? /* @__PURE__ */ new Set();
+		group.members.set(orgUserId, chats);
+		if (chatId) chats.add(chatId);
+	}
+	/** Pushes the `chat.state` of every dirty member and chat and the `unread`
+	*  of every dirty member, read now. One flush runs at a time. */
+	async flush() {
+		if (this.flushing) {
+			this.flushAgain = true;
+			return;
+		}
+		this.flushing = true;
+		try {
+			do {
+				this.flushAgain = false;
+				const groups = [...this.dirty.values()];
+				this.dirty = /* @__PURE__ */ new Map();
+				await Promise.all(groups.map((group) => this.flushGroup(group)));
+			} while (this.flushAgain && this.dirty.size > 0 && !this.closing);
+		} finally {
+			this.flushing = false;
+		}
+	}
+	async flushGroup(group) {
+		const { orgId, communityId } = group;
+		const members = [...group.members.keys()].filter((orgUserId) => this.streamsOf(orgId, communityId, orgUserId).length > 0);
+		if (members.length === 0) return;
+		let states;
+		try {
+			states = await this.reads.memberStates(orgId, communityId, members);
+		} catch (error) {
+			this.logger.error("chat member state read failed", {
+				orgId,
+				communityId,
+				error: describeError(error)
+			});
+			for (const orgUserId of members) {
+				const chats = group.members.get(orgUserId) ?? /* @__PURE__ */ new Set();
+				this.markDirty(orgId, communityId, orgUserId);
+				for (const chatId of chats) this.markDirty(orgId, communityId, orgUserId, chatId);
+			}
+			return;
+		}
+		for (const state of states) {
+			const chats = group.members.get(state.orgUserId);
+			const streams = this.streamsOf(orgId, communityId, state.orgUserId);
+			if (!chats || streams.length === 0) continue;
+			const events = state.chats.filter((chat) => chats.has(chat.chatId)).map((chat) => ({
+				type: "chat.state",
+				chatId: chat.chatId,
+				unread: chat.unread,
+				lastReadMessageId: chat.lastReadMessageId,
+				subscription: chat.subscription
+			}));
+			events.push({
+				type: "unread",
+				...state.unread
+			});
+			for (const stream of streams) for (const event of events) stream.push(event);
+		}
+	}
+};
+//#endregion
+export { CHAT_CHANNEL, ChatHub, ChatLiveForwarder, TYPING, publishChange };
+
+//# sourceMappingURL=live.js.map