@prajwalshete/telegram-plugin 0.0.0-stage → 0.1.0

package/dist/engine/outbox/drain.js

@@ -0,0 +1,381 @@
+import { takeChatSlot, takeToken } from "../../core/pacing.js";
+import { sql } from "../../ports/sql.js";
+import { isBotUsable } from "../bot-api.js";
+import { metricCount, metricTiming } from "../metrics.js";
+import { applyOutcome, releaseSql, sendDelivery } from "./send.js";
+// src/engine/outbox/drain.ts
+/** Longest the loop waits for the next due row (pacing gap, retry) before it stops. */
+const MAX_IDLE_WAIT_MS = 5e3;
+/** How often the D1 lease is renewed (and the bot row re-read) during a drain. */
+const LEASE_RENEW_EVERY_MS = 5e3;
+/** Longest a successful send's result write waits for its batch. */
+const FLUSH_EVERY_MS = 1e3;
+const CHAT_KINDS = [
+	"private",
+	"group",
+	"supergroup",
+	"channel"
+];
+function chatKind(kind) {
+	return CHAT_KINDS.includes(kind) ? kind : "private";
+}
+async function acquireLease(rt, botId, token, now) {
+	return rt.db.first(sql`UPDATE tg_bot SET drain_lease_until = ${now + rt.limits.drainLeaseMs}, drain_token = ${token}
+        WHERE tenant = ${rt.tenant} AND id = ${botId} AND deleted_at IS NULL
+          AND status IN ('active', 'webhook_error')
+          AND (drain_lease_until IS NULL OR drain_lease_until < ${now})
+          AND (paused_until IS NULL OR paused_until < ${now})
+        RETURNING *`);
+}
+async function renewLease(rt, botId, token, now) {
+	return rt.db.first(sql`UPDATE tg_bot SET drain_lease_until = ${now + rt.limits.drainLeaseMs}
+        WHERE tenant = ${rt.tenant} AND id = ${botId} AND drain_token = ${token} RETURNING *`);
+}
+async function releaseLease(rt, botId, token) {
+	await rt.db.run(sql`UPDATE tg_bot SET drain_lease_until = NULL, drain_token = NULL
+        WHERE tenant = ${rt.tenant} AND id = ${botId} AND drain_token = ${token}`);
+}
+/** The default lease: a row lease on `tg_bot` with a fencing token (docs/06 §8 step 2). */
+function d1Lease(rt, botId, token) {
+	let bot = null;
+	let renewedAt = Number.NEGATIVE_INFINITY;
+	const keep = (b, now) => {
+		bot = b;
+		renewedAt = now;
+		return b;
+	};
+	return {
+		acquire: async (now) => keep(await acquireLease(rt, botId, token, now), now),
+		renew: async (now) => now - renewedAt < LEASE_RENEW_EVERY_MS && bot ? bot : keep(await renewLease(rt, botId, token, now), now),
+		release: () => releaseLease(rt, botId, token)
+	};
+}
+/**
+* Claims the head of each chat's queue: within a message (same chat + source + source id) only the lowest unsent
+* part, then one row per chat whose pacing allows a send now. Expired `sending` leases are re-claimed.
+*/
+/** Within a message (same chat + source + source id) only the lowest unsent part is a "head". */
+function headsCte(rt, botId) {
+	return sql`heads AS (
+    SELECT d.id, d.chat_ref, d.status, d.next_attempt_at, d.lease_until, d.created_at, d.rowid AS seq,
+           ROW_NUMBER() OVER (PARTITION BY d.chat_ref, d.source, COALESCE(d.source_id, '')
+                              ORDER BY d.part, d.created_at, d.rowid) AS rn
+    FROM tg_delivery d
+    WHERE d.tenant = ${rt.tenant} AND d.bot_id = ${botId} AND d.status IN ('queued', 'sending')
+  )`;
+}
+/**
+* Claims the head of each chat's queue: one row per chat (oldest first, insert order breaks ties) whose pacing
+* allows a send now. Expired `sending` leases are re-claimed.
+*/
+function claimSql(rt, botId, token, now, limit) {
+	return sql`WITH ${headsCte(rt, botId)},
+        ready AS (
+          SELECT h.id, h.next_attempt_at, h.created_at, h.seq,
+                 ROW_NUMBER() OVER (PARTITION BY h.chat_ref ORDER BY h.next_attempt_at, h.created_at, h.seq) AS crn
+          FROM heads h LEFT JOIN tg_chat c ON c.id = h.chat_ref
+          WHERE h.rn = 1
+            AND ((h.status = 'queued' AND h.next_attempt_at <= ${now})
+                 OR (h.status = 'sending' AND (h.lease_until IS NULL OR h.lease_until < ${now})))
+            AND (c.next_allowed_at IS NULL OR c.next_allowed_at <= ${now})
+        )
+        UPDATE tg_delivery SET status = 'sending', lease_until = ${now + rt.limits.drainLeaseMs},
+                               lease_token = ${token}, updated_at = ${now}
+        WHERE id IN (SELECT id FROM ready WHERE crn = 1 ORDER BY next_attempt_at, created_at, seq LIMIT ${limit})
+        RETURNING *`;
+}
+/**
+* Claims a slice and, in the same D1 call, reads the next due time (used when nothing was claimable, e.g. the
+* only chat is waiting for its pacing slot).
+*/
+async function claimSlice(rt, botId, token, now, limit) {
+	const [claimed, due] = await rt.db.batch([claimSql(rt, botId, token, now, limit), nextDueSql(rt, botId)]);
+	return {
+		rows: claimed?.rows ?? [],
+		due: (due?.rows[0])?.due ?? null
+	};
+}
+/** Earliest time a head row of this bot can be claimed (due time, live lease, chat pacing); null = empty. */
+async function nextDueAt(rt, botId) {
+	return (await rt.db.first(nextDueSql(rt, botId)))?.due ?? null;
+}
+function nextDueSql(rt, botId) {
+	return sql`WITH ${headsCte(rt, botId)}
+        SELECT MIN(MAX(CASE WHEN h.status = 'sending' THEN COALESCE(h.lease_until, 0) ELSE h.next_attempt_at END,
+                       COALESCE(c.next_allowed_at, 0))) AS due
+        FROM heads h LEFT JOIN tg_chat c ON c.id = h.chat_ref WHERE h.rn = 1`;
+}
+/** Bots with work due now (or within `aheadMs`). */
+async function botsWithDueWork(rt, now, aheadMs = 0) {
+	return (await rt.db.all(sql`SELECT DISTINCT d.bot_id FROM tg_delivery d JOIN tg_bot b ON b.id = d.bot_id
+        WHERE d.tenant = ${rt.tenant} AND b.deleted_at IS NULL AND b.status IN ('active', 'webhook_error')
+          AND (b.paused_until IS NULL OR b.paused_until < ${now})
+          AND ((d.status = 'queued' AND d.next_attempt_at <= ${now + aheadMs})
+               OR (d.status = 'sending' AND d.lease_until < ${now}))`)).map((r) => r.bot_id);
+}
+async function pool(items, size, fn) {
+	let next = 0;
+	const workers = Array.from({ length: Math.max(1, Math.min(size, items.length)) }, async () => {
+		while (next < items.length) {
+			const item = items[next++];
+			await fn(item);
+		}
+	});
+	await Promise.all(workers);
+}
+/**
+* Drains one bot until its queue is idle, the budget is spent, or the bot must stop (401 / repeated 429).
+* After releasing the lease it looks once more: a row queued while this drain was finishing (whose kick lost the
+* lease race) is sent now instead of waiting for the next tick.
+*/
+async function drainBot(rt, botId, opts = {}) {
+	const started = rt.clock.now();
+	const budget = opts.budgetMs ?? rt.limits.tickBudgetMs;
+	let total = await drainOnce(rt, botId, opts);
+	for (let round = 0; round < 3; round++) {
+		const now = rt.clock.now();
+		if (total.stoppedBy !== "idle" || total.nextDueAt === null || total.nextDueAt > now) break;
+		const left = budget - (now - started);
+		if (left <= 0) break;
+		const capLeft = sendCap(rt, opts.maxSends) - total.claimed;
+		if (capLeft <= 0) break;
+		const more = await drainOnce(rt, botId, {
+			...opts,
+			budgetMs: left,
+			...Number.isFinite(capLeft) ? { maxSends: capLeft } : {}
+		});
+		if (more.stoppedBy === "lease") break;
+		total = {
+			...more,
+			claimed: total.claimed + more.claimed,
+			sent: total.sent + more.sent,
+			retried: total.retried + more.retried,
+			failed: total.failed + more.failed,
+			dropped: total.dropped + more.dropped
+		};
+	}
+	return total;
+}
+/** Claims one drain may make: `maxSends`, else 40 on the Free plan, else unlimited. */
+function sendCap(rt, maxSends) {
+	return maxSends ?? (rt.limits.plan === "free" ? 40 : Number.POSITIVE_INFINITY);
+}
+/** Bot-level pacing: a token bucket (default) or exact spacing between send starts. */
+function botPacer(rt, ratePerSec, strict) {
+	if (strict) {
+		const interval = 1e3 / ratePerSec;
+		let last = Number.NEGATIVE_INFINITY;
+		return () => {
+			const now = rt.clock.now();
+			const wait = Math.ceil(last + interval - now);
+			if (wait > 0) return wait;
+			last = now;
+			return 0;
+		};
+	}
+	let bucket = null;
+	return () => {
+		const r = takeToken(bucket, rt.clock.now(), { ratePerSec });
+		bucket = r.state;
+		return r.ok ? 0 : r.waitMs;
+	};
+}
+async function drainOnce(rt, botId, opts) {
+	const started = rt.clock.now();
+	const budget = opts.budgetMs ?? rt.limits.tickBudgetMs;
+	const cap = sendCap(rt, opts.maxSends);
+	const maxIdle = opts.maxIdleWaitMs ?? MAX_IDLE_WAIT_MS;
+	const token = rt.ids.uuid();
+	const lease = opts.lease ? opts.lease(token) : d1Lease(rt, botId, token);
+	const result = {
+		botId,
+		claimed: 0,
+		sent: 0,
+		retried: 0,
+		failed: 0,
+		dropped: 0,
+		stoppedBy: "idle",
+		nextDueAt: null
+	};
+	let bot = await lease.acquire(started);
+	if (!bot) {
+		result.stoppedBy = "lease";
+		return result;
+	}
+	let spins = 0;
+	const takeBotToken = botPacer(rt, Math.max(1, Math.min(bot.rate_per_sec, rt.limits.perBotPerSec)), opts.strictPacing === true);
+	try {
+		for (;;) {
+			const now = rt.clock.now();
+			if (now - started >= budget) {
+				result.stoppedBy = "budget";
+				break;
+			}
+			if (result.claimed >= cap) {
+				result.stoppedBy = "cap";
+				break;
+			}
+			const renewed = await lease.renew(now);
+			if (!renewed) {
+				result.stoppedBy = "lease";
+				break;
+			}
+			bot = renewed;
+			if (!isBotUsable(bot)) {
+				result.stoppedBy = "unavailable";
+				break;
+			}
+			const { rows, due } = await claimSlice(rt, botId, token, now, Math.max(1, Math.min(rt.limits.drainSlice, cap - result.claimed)));
+			if (rows.length === 0) {
+				const wait = due === null ? null : due - rt.clock.now();
+				if (wait !== null && wait <= maxIdle && rt.clock.now() - started + wait < budget && spins < 50) {
+					if (wait <= 0) spins++;
+					await rt.sleep(Math.max(wait, wait <= 0 ? 100 : 1));
+					continue;
+				}
+				result.nextDueAt = due;
+				result.stoppedBy = "idle";
+				break;
+			}
+			result.claimed += rows.length;
+			const stop = await sendSlice(rt, bot, rows, token, result, takeBotToken);
+			if (stop) {
+				result.stoppedBy = stop;
+				break;
+			}
+		}
+	} finally {
+		await lease.release();
+	}
+	result.nextDueAt = await nextDueAt(rt, botId);
+	const ms = rt.clock.now() - started;
+	metricCount(rt, "tg.drain", 1, {
+		botId,
+		outcome: result.stoppedBy
+	});
+	metricTiming(rt, "tg.drain_ms", ms, { botId });
+	rt.log.info("tg.drain", {
+		botId,
+		claimed: result.claimed,
+		sent: result.sent,
+		failed: result.failed,
+		retried: result.retried,
+		dropped: result.dropped,
+		stoppedBy: result.stoppedBy,
+		ms
+	});
+	return result;
+}
+/**
+* Commits buffered result writes; one retry, then a loud error log (the rows stay `sending` and are re-sent once
+* their lease expires) and the error is rethrown so the drain stops instead of sending more it cannot record.
+*/
+async function commitWrites(rt, botId, writes, sends) {
+	try {
+		await rt.db.batch(writes);
+		return;
+	} catch (e) {
+		rt.log.warn("tg.drain_flush_retry", {
+			botId,
+			sends,
+			error: e instanceof Error ? e.name : "error"
+		});
+	}
+	try {
+		await rt.db.batch(writes);
+	} catch (e) {
+		rt.log.error("tg.drain_flush_failed", {
+			botId,
+			sends,
+			error: e instanceof Error ? e.name : "error"
+		});
+		throw e;
+	}
+}
+async function sendSlice(rt, bot, rows, token, result, takeBotToken) {
+	const chats = /* @__PURE__ */ new Map();
+	const refs = [...new Set(rows.map((r) => r.chat_ref))];
+	for (let i = 0; i < refs.length; i += 50) {
+		const chunk = refs.slice(i, i + 50);
+		const found = await rt.db.all(sql`SELECT * FROM tg_chat WHERE tenant = ${rt.tenant} AND id IN (${sql.join(chunk)})`);
+		for (const c of found) chats.set(c.id, c);
+	}
+	let stop = null;
+	const retryAfters = [];
+	const done = /* @__PURE__ */ new Set();
+	let pending = [];
+	let pendingSends = 0;
+	let lastFlush = rt.clock.now();
+	let flushFailed = false;
+	const flush = async (extra = []) => {
+		const writes = [...pending, ...extra];
+		const sends = pendingSends;
+		pending = [];
+		pendingSends = 0;
+		lastFlush = rt.clock.now();
+		if (writes.length === 0) return;
+		await commitWrites(rt, bot.id, writes, sends).catch((e) => {
+			flushFailed = true;
+			throw e;
+		});
+	};
+	try {
+		await pool(rows, rt.limits.drainConcurrency, async (row) => {
+			if (stop || flushFailed) return;
+			const chat = chats.get(row.chat_ref) ?? null;
+			let now = rt.clock.now();
+			if (chat) {
+				const pace = {
+					nextAllowedAt: chat.next_allowed_at,
+					windowStart: chat.minute_window_start,
+					windowCount: chat.minute_count
+				};
+				const slot = takeChatSlot(pace, now, chatKind(chat.kind), {
+					perChatIntervalMs: rt.limits.perChatIntervalMs,
+					perGroupPerMin: rt.limits.perGroupPerMin
+				});
+				if (!slot.ok) {
+					done.add(row.id);
+					await rt.db.batch([releaseSql(rt, row, token, now), sql`UPDATE tg_chat SET next_allowed_at = ${now + slot.waitMs} WHERE id = ${chat.id}`]);
+					return;
+				}
+				chat.next_allowed_at = slot.state.nextAllowedAt;
+				chat.minute_window_start = slot.state.windowStart;
+				chat.minute_count = slot.state.windowCount;
+			}
+			for (let wait = takeBotToken(); wait > 0; wait = takeBotToken()) await rt.sleep(wait);
+			now = rt.clock.now();
+			const summary = await sendDelivery(rt, bot, chat, row, now);
+			done.add(row.id);
+			const ended = rt.clock.now();
+			metricTiming(rt, "tg.send_ms", ended - now, { botId: bot.id });
+			const writes = [];
+			const effect = await applyOutcome(rt, bot, chat, row, token, summary, ended, writes);
+			if (writes.length > 0) {
+				pending.push(...writes);
+				pendingSends++;
+				if (pendingSends >= 5 || rt.clock.now() - lastFlush >= 1e3) await flush();
+			}
+			if (effect.result === "sent") result.sent++;
+			else if (effect.result === "retry") result.retried++;
+			else if (effect.result === "failed") result.failed++;
+			else result.dropped++;
+			if (effect.retryAfterMs !== void 0) retryAfters.push(effect.retryAfterMs);
+			if (effect.unauthorized) stop = "unauthorized";
+		});
+	} finally {
+		if (!flushFailed) await flush(rows.filter((r) => !done.has(r.id)).map((r) => releaseSql(rt, r, token, rt.clock.now())));
+	}
+	if (!stop && retryAfters.length >= 2) {
+		const until = rt.clock.now() + Math.max(...retryAfters);
+		await rt.db.run(sql`UPDATE tg_bot SET paused_until = ${until} WHERE tenant = ${rt.tenant} AND id = ${bot.id}`);
+		rt.log.warn("tg.bot_paused", {
+			botId: bot.id,
+			reason: "rate_limited",
+			ms: until - rt.clock.now()
+		});
+		stop = "paused";
+	}
+	return stop;
+}
+export { FLUSH_EVERY_MS, botsWithDueWork, d1Lease, drainBot, nextDueAt, sendCap };

package/dist/engine/outbox/enqueue.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/engine/outbox/enqueue.js

@@ -0,0 +1,63 @@
+import { fitCaption, splitMessage } from "../../core/split/split.js";
+import { sql } from "../../ports/sql.js";
+// src/engine/outbox/enqueue.ts
+function partsOf(input) {
+	const html = input.html ?? "";
+	if (input.kind === "document" || input.kind === "photo") {
+		if (!input.file) throw new TypeError("document / photo delivery needs a file");
+		const { caption, rest } = html === "" ? {
+			caption: "",
+			rest: []
+		} : fitCaption(html);
+		return [{
+			kind: input.kind,
+			html: caption === "" ? null : caption,
+			file: input.file
+		}, ...rest.map((p) => ({
+			kind: "text",
+			html: p,
+			file: null
+		}))];
+	}
+	if (input.kind === "delete") return [{
+		kind: "delete",
+		html: null,
+		file: null
+	}];
+	if (input.kind === "edit") return [{
+		kind: "edit",
+		html,
+		file: null
+	}];
+	const parts = splitMessage(html);
+	if (parts.length === 0) throw new TypeError("text delivery is empty");
+	return parts.map((p) => ({
+		kind: "text",
+		html: p,
+		file: null
+	}));
+}
+/** One `INSERT … ON CONFLICT DO NOTHING` per part. `ids` gives each row its id. */
+function deliveryFragments(ctx, input, now) {
+	const parts = partsOf(input);
+	const sourceId = input.sourceId ?? input.dedupeKey;
+	const options = input.options && Object.keys(input.options).length > 0 ? JSON.stringify(input.options) : null;
+	const render = input.render ? JSON.stringify(input.render) : null;
+	const notBefore = input.notBefore ?? now;
+	return parts.map((p, i) => {
+		const markup = i === parts.length - 1 && input.replyMarkup ? JSON.stringify(input.replyMarkup) : null;
+		const fileRender = p.file?.source ? JSON.stringify({
+			...input.render,
+			fileSource: p.file.source
+		}) : render;
+		return sql`INSERT INTO tg_delivery (id, tenant, bot_id, chat_ref, message_thread_id, source, source_id, kind,
+        body_html, part, parts, file_ref, file_name, file_mime, reply_markup_json, options_json, render_json,
+        target_message_id, dedupe_key, status, attempts, next_attempt_at, created_at, updated_at)
+      VALUES (${ctx.ids.uuid()}, ${ctx.tenant}, ${input.botId}, ${input.chatRef}, ${input.threadId ?? null},
+        ${input.source}, ${sourceId}, ${p.kind}, ${p.html}, ${i}, ${parts.length}, ${p.file?.ref ?? null},
+        ${p.file?.name ?? null}, ${p.file?.mime ?? null}, ${markup}, ${options}, ${fileRender},
+        ${input.targetMessageId ?? null}, ${`${input.dedupeKey}:${i}`}, 'queued', 0, ${notBefore}, ${now}, ${now})
+      ON CONFLICT (tenant, dedupe_key) DO NOTHING`;
+	});
+}
+export { deliveryFragments };

package/dist/engine/outbox/select.js

@@ -0,0 +1,24 @@
+import { TelegramConfigError } from "../errors.js";
+import { doTransport } from "./do-transport.js";
+import { cronTransport, queueTransport } from "./transport.js";
+// src/engine/outbox/select.ts
+/**
+* Builds the drain transport for `options.transport` (see `TransportChoice`). Throws `TelegramConfigError` when
+* `queue` / `do` is chosen and its binding is missing.
+*/
+function selectTransport(rt, mapped, choice) {
+	if (typeof choice === "function") return choice(rt);
+	switch (choice ?? "auto") {
+		case "cron": return cronTransport(rt);
+		case "queue":
+			if (!mapped.queue) throw new TelegramConfigError("transport \"queue\" needs env.queue");
+			return queueTransport(rt, mapped.queue);
+		case "do":
+			if (!mapped.botDO) throw new TelegramConfigError("transport \"do\" needs env.botDO (a TelegramBotDO namespace)");
+			return doTransport(rt, mapped.botDO);
+		default:
+			if (mapped.botDO) return doTransport(rt, mapped.botDO);
+			return mapped.queue ? queueTransport(rt, mapped.queue) : cronTransport(rt);
+	}
+}
+export { selectTransport };