@prajwalshete/telegram-plugin 0.0.0-stage → 0.1.1

package/dist/engine/outbox/send.js

@@ -0,0 +1,362 @@
+import { TemplateOptions } from "../../contracts/templates.js";
+import { nextBackoff } from "../../core/pacing.js";
+import { toPlainText } from "../../core/split/plain.js";
+import { sql } from "../../ports/sql.js";
+import { settle } from "../../telegram/classify.js";
+import { withToken } from "../bot-api.js";
+import { botDto, deliveryDto, parseJson, parseObject } from "../rows.js";
+import { afterChatGone, chatGoneSql, migrateChat } from "../chat-state.js";
+import { metricCount } from "../metrics.js";
+import { inputFile } from "../../telegram/multipart.js";
+// src/engine/outbox/send.ts
+/** Telegram's multipart upload cap. */
+const MAX_UPLOAD_BYTES = 52428800;
+function skip(status, code, detail) {
+	return detail === void 0 ? {
+		type: "skip",
+		status,
+		code
+	} : {
+		type: "skip",
+		status,
+		code,
+		detail
+	};
+}
+async function openFile(rt, row) {
+	if (!row.file_ref) return null;
+	const render = parseObject(row.render_json);
+	const sourceKey = typeof render?.fileSource === "string" ? render.fileSource : null;
+	if (sourceKey) {
+		const source = rt.registry.fileSources.get(sourceKey);
+		return source ? source.resolve({
+			actor: null,
+			ref: row.file_ref,
+			env: rt.env
+		}) : null;
+	}
+	return rt.files ? rt.files.open(row.file_ref, null) : null;
+}
+function commonOptions(row) {
+	const opts = parseJson(row.options_json, TemplateOptions, {});
+	const markup = parseObject(row.reply_markup_json);
+	return {
+		...row.message_thread_id === null ? {} : { message_thread_id: row.message_thread_id },
+		...opts.silent ? { disable_notification: true } : {},
+		...opts.protectContent ? { protect_content: true } : {},
+		...opts.linkPreview === true ? {} : { link_preview_options: { is_disabled: true } },
+		...markup ? { reply_markup: markup } : {}
+	};
+}
+async function call(rt, api, row, chatId, plain) {
+	const common = commonOptions(row);
+	const html = row.body_html ?? "";
+	const text = plain ? toPlainText(html) : html;
+	const mode = plain || html === "" ? {} : { parse_mode: "HTML" };
+	const idOf = (v) => typeof v === "object" && v !== null && typeof v.message_id === "number" ? v.message_id : null;
+	let promise;
+	switch (row.kind) {
+		case "text":
+			promise = api.sendMessage({
+				chat_id: chatId,
+				text,
+				...mode,
+				...common
+			});
+			break;
+		case "edit": {
+			if (row.target_message_id === null) return skip("failed", "target_missing");
+			const { link_preview_options, reply_markup } = common;
+			promise = api.editMessageText({
+				chat_id: chatId,
+				message_id: row.target_message_id,
+				text,
+				...mode,
+				...link_preview_options ? { link_preview_options } : {},
+				...reply_markup && "inline_keyboard" in reply_markup ? { reply_markup } : {}
+			});
+			break;
+		}
+		case "delete":
+			if (row.target_message_id === null) return skip("failed", "target_missing");
+			promise = api.deleteMessage({
+				chat_id: chatId,
+				message_id: row.target_message_id
+			});
+			break;
+		case "document":
+		case "photo": {
+			const file = await openFile(rt, row);
+			if (!file) return skip("failed", "file_missing");
+			if (file.size !== null && file.size > 52428800) {
+				await file.body.cancel().catch(() => {});
+				return skip("failed", "file_too_large");
+			}
+			const upload = inputFile(file.body, row.file_name ?? file.name, row.file_mime ?? file.mime);
+			const { link_preview_options: _ignored, ...rest } = common;
+			const caption = html === "" ? {} : {
+				caption: text,
+				...mode
+			};
+			promise = row.kind === "document" ? api.sendDocument({
+				chat_id: chatId,
+				document: upload,
+				...caption,
+				...rest
+			}) : api.sendPhoto({
+				chat_id: chatId,
+				photo: upload,
+				...caption,
+				...rest
+			});
+			break;
+		}
+		default: return skip("failed", "kind_unknown");
+	}
+	const r = await settle(promise);
+	if (r.outcome.kind === "ok") return {
+		ok: true,
+		messageId: idOf(r.value)
+	};
+	return {
+		ok: false,
+		outcome: r.outcome
+	};
+}
+/** Sends one claimed row. Never throws for Telegram or network failures. */
+async function sendDelivery(rt, bot, chat, row, now) {
+	if (!chat) return skip("failed", "chat_not_found");
+	if (chat.status !== "active") return skip("dropped", `chat_${chat.status}`);
+	if (rt.hooks.beforeSend) {
+		const verdict = { allow: true };
+		await rt.hook("beforeSend", async (fn) => {
+			verdict.allow = await fn(deliveryDto(row, true));
+		});
+		if (verdict.allow === false) return skip("cancelled", "before_send");
+	}
+	let current = chat;
+	let plain = false;
+	let migrated = false;
+	return withToken(rt, bot, async (api) => {
+		for (;;) {
+			const r = await call(rt, api, row, current.chat_id, plain);
+			if ("type" in r) return r;
+			if (r.ok) return {
+				type: "api",
+				outcome: {
+					kind: "ok",
+					retryable: false
+				},
+				messageId: r.messageId,
+				chat: current,
+				formatFallback: plain
+			};
+			const o = r.outcome;
+			if (o.kind === "migrated" && o.migrateToChatId && !migrated) {
+				migrated = true;
+				current = await migrateChat(rt, current, o.migrateToChatId, now);
+				continue;
+			}
+			if (o.kind === "parse_error" && !plain && (row.body_html ?? "") !== "") {
+				plain = true;
+				rt.log.warn("tg.format_fallback", {
+					botId: bot.id,
+					deliveryId: row.id
+				});
+				continue;
+			}
+			return {
+				type: "api",
+				outcome: o,
+				messageId: null,
+				chat: current,
+				formatFallback: plain
+			};
+		}
+	});
+}
+/** Back to the queue without counting an attempt (pacing, 401, early stop). */
+function releaseSql(rt, row, token, now) {
+	return sql`UPDATE tg_delivery SET status = 'queued', lease_until = NULL, lease_token = NULL, updated_at = ${now}
+             WHERE tenant = ${rt.tenant} AND id = ${row.id} AND lease_token = ${token}`;
+}
+function finalSql(rt, row, token, f, now) {
+	return sql`UPDATE tg_delivery SET status = ${f.status}, attempts = ${f.attempts},
+               next_attempt_at = ${f.nextAttemptAt}, error_code = ${f.code}, error_detail = ${f.detail},
+               tg_message_id = COALESCE(${f.messageId ?? null}, tg_message_id), sent_at = ${f.sentAt ?? null},
+               lease_until = NULL, lease_token = NULL, updated_at = ${now}
+             WHERE tenant = ${rt.tenant} AND id = ${row.id} AND lease_token = ${token}`;
+}
+/** Fence for side effects in the same batch (they run before the delivery update clears the token). */
+function leased(row, token) {
+	return sql`EXISTS (SELECT 1 FROM tg_delivery WHERE id = ${row.id} AND lease_token = ${token})`;
+}
+function detailOf(o) {
+	return o.description ? o.description.slice(0, 500) : null;
+}
+/**
+* Applies one result (docs/06 §8 table) as one batch, then runs hooks. With `defer`, the writes of a successful
+* send are pushed there instead (the drain commits them in a bounded window, see `FLUSH_EVERY_SENDS`).
+*/
+async function applyOutcome(rt, bot, chat, row, token, s, now, defer) {
+	const failedHook = async (code) => rt.hook("onDeliveryFailed", (fn) => fn({
+		...deliveryDto(row, false),
+		status: "failed",
+		errorCode: code,
+		nextAttemptAt: null
+	}));
+	const metric = (outcome, code) => metricCount(rt, "tg.send", 1, {
+		botId: bot.id,
+		outcome,
+		...code ? { code } : {}
+	});
+	if (s.type === "skip") {
+		await rt.db.batch([finalSql(rt, row, token, {
+			status: s.status,
+			attempts: row.attempts,
+			nextAttemptAt: row.next_attempt_at,
+			code: s.code,
+			detail: s.detail ?? null
+		}, now)]);
+		rt.log.info("tg.send", {
+			botId: bot.id,
+			deliveryId: row.id,
+			status: s.status,
+			code: s.code
+		});
+		if (s.status === "failed") {
+			metric("failed", s.code);
+			await failedHook(s.code);
+			return { result: "failed" };
+		}
+		metric(s.status, s.code);
+		return { result: "dropped" };
+	}
+	const o = s.outcome;
+	const target = s.chat;
+	const code = o.reason ?? o.kind;
+	const base = {
+		attempts: row.attempts,
+		nextAttemptAt: row.next_attempt_at
+	};
+	const log = (status, extra = {}) => rt.log.info("tg.send", {
+		botId: bot.id,
+		deliveryId: row.id,
+		status,
+		attempt: row.attempts + 1,
+		...extra
+	});
+	switch (o.kind) {
+		case "ok": {
+			const writes = [sql`UPDATE tg_chat SET next_allowed_at = ${chat?.next_allowed_at ?? null},
+                   minute_window_start = ${chat?.minute_window_start ?? null},
+                   minute_count = ${chat?.minute_count ?? 0}
+            WHERE id = ${target.id} AND ${leased(row, token)}`, finalSql(rt, row, token, {
+				...base,
+				attempts: row.attempts + 1,
+				status: "sent",
+				code: s.formatFallback ? "format_fallback" : null,
+				detail: null,
+				messageId: s.messageId,
+				sentAt: now
+			}, now)];
+			if (defer) defer.push(...writes);
+			else await rt.db.batch(writes);
+			metric("sent");
+			log("sent");
+			return { result: "sent" };
+		}
+		case "retry_after": {
+			const ms = o.retryAfterMs ?? 1e3;
+			await rt.db.batch([sql`UPDATE tg_chat SET next_allowed_at = ${now + ms} WHERE id = ${target.id} AND ${leased(row, token)}`, finalSql(rt, row, token, {
+				...base,
+				status: "queued",
+				nextAttemptAt: now + ms,
+				code: "retry_after",
+				detail: detailOf(o)
+			}, now)]);
+			metric("retry", "retry_after");
+			log("retry", {
+				code: "retry_after",
+				ms
+			});
+			return {
+				result: "retry",
+				retryAfterMs: ms
+			};
+		}
+		case "blocked":
+		case "left": {
+			const status = o.kind === "blocked" ? "blocked" : "left";
+			await rt.db.batch([...chatGoneSql(rt, target, status, now, row.id).map((q) => sql`${q} AND ${leased(row, token)}`), finalSql(rt, row, token, {
+				...base,
+				status: "dropped",
+				code,
+				detail: detailOf(o)
+			}, now)]);
+			metric("dropped", code);
+			log("dropped", { code });
+			await afterChatGone(rt, target, status, now);
+			return { result: "dropped" };
+		}
+		case "unauthorized": {
+			const changed = await rt.db.batch([releaseSql(rt, row, token, now), sql`UPDATE tg_bot SET status = 'invalid_token', status_detail = ${detailOf(o) ?? "Unauthorized"},
+                   checked_at = ${now}, updated_at = ${now}
+            WHERE tenant = ${rt.tenant} AND id = ${bot.id} AND status != 'invalid_token' RETURNING id`]);
+			metric("retry", "unauthorized");
+			rt.log.error("tg.bot_unauthorized", { botId: bot.id });
+			if ((changed[1]?.rows.length ?? 0) > 0) await rt.hook("onBotStatus", (fn) => fn({
+				...botDto(bot),
+				status: "invalid_token",
+				updatedAt: now
+			}));
+			return {
+				result: "retry",
+				unauthorized: true
+			};
+		}
+		case "server_error":
+		case "network":
+		case "timeout": {
+			const attempts = row.attempts + 1;
+			if (attempts >= rt.limits.maxAttempts) {
+				await rt.db.batch([finalSql(rt, row, token, {
+					...base,
+					attempts,
+					status: "failed",
+					code,
+					detail: detailOf(o)
+				}, now)]);
+				metric("failed", code);
+				log("failed", { code });
+				await failedHook(code);
+				return { result: "failed" };
+			}
+			metric("retry", code);
+			const next = now + nextBackoff(attempts - 1, Math.random);
+			await rt.db.batch([finalSql(rt, row, token, {
+				...base,
+				attempts,
+				status: "queued",
+				nextAttemptAt: next,
+				code,
+				detail: detailOf(o)
+			}, now)]);
+			log("retry", { code });
+			return { result: "retry" };
+		}
+		default:
+			await rt.db.batch([finalSql(rt, row, token, {
+				...base,
+				attempts: row.attempts + 1,
+				status: "failed",
+				code,
+				detail: detailOf(o)
+			}, now)]);
+			metric("failed", code);
+			log("failed", { code });
+			await failedHook(code);
+			return { result: "failed" };
+	}
+}
+export { MAX_UPLOAD_BYTES, applyOutcome, releaseSql, sendDelivery };

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

@@ -0,0 +1,35 @@
+import { TransportPort } from "../../ports/ports.js";
+import { Runtime } from "../runtime.js";
+/** Marks plugin messages on a shared queue. */
+export declare const QUEUE_MARK = "cf-telegram-plugin";
+/**
+ * Body of a plugin message on the host's Queue (marked with `mark`): `drain` a bot, process a queued webhook
+ * `update`, or process due `events` of a tenant. `plugin.queue()` consumes them.
+ */
+export type PluginQueueMessage = {
+  mark: typeof QUEUE_MARK;
+  type: "drain";
+  tenant: string;
+  botId: string;
+} | {
+  mark: typeof QUEUE_MARK;
+  type: "update";
+  tenant: string;
+  botId: string;
+  update: unknown;
+} |
+/** Process due events now (sent by `plugin.kick()` after an `emit()` commit); fan-out then kicks the drains. */
+{
+  mark: typeof QUEUE_MARK;
+  type: "events";
+  tenant: string;
+};
+/** True for a message body the plugin sent (so a shared queue consumer can route it to `plugin.queue()`). */
+export declare function isPluginMessage(body: unknown): body is PluginQueueMessage;
+/**
+ * The default transport (`name: "outbox"`): `kick()` drains inline within `KICK_BUDGET_MS` (run it in
+ * `waitUntil`); otherwise the minute tick drains.
+ */
+export declare function cronTransport<A>(rt: Runtime<A>): TransportPort;
+/** Queue transport: `kick()` sends one `drain` message per bot (default: every bot with due work). */
+export declare function queueTransport<A>(rt: Runtime<A>, queue: Queue<unknown>): TransportPort;

package/dist/engine/outbox/transport.js

@@ -0,0 +1,175 @@
+import { isBotUsable, loadBot } from "../bot-api.js";
+import { botsWithDueWork, drainBot, sendCap } from "./drain.js";
+import { parseUpdate } from "../../telegram/update.js";
+import { processUpdate } from "../dispatch/dispatcher.js";
+import { runEvents } from "../events/tick.js";
+import { handleDeadLetters } from "./dead-letter.js";
+// src/engine/outbox/transport.ts
+/** Budget for drains started from a request (`waitUntil` allows ~30 s after the response). */
+const KICK_BUDGET_MS = 25e3;
+/** Marks plugin messages on a shared queue. */
+const QUEUE_MARK = "cf-telegram-plugin";
+/** True for a message body the plugin sent (so a shared queue consumer can route it to `plugin.queue()`). */
+function isPluginMessage(body) {
+	return typeof body === "object" && body !== null && body.mark === "cf-telegram-plugin";
+}
+/**
+* Drains the given bots (default: every bot with due work) one after another within one budget. The Free-plan
+* send cap applies to the whole invocation, not per bot.
+*/
+async function drainBots(rt, botIds, budgetMs) {
+	const started = rt.clock.now();
+	const ids = botIds ?? await botsWithDueWork(rt, started);
+	const results = [];
+	let capLeft = sendCap(rt);
+	for (const id of new Set(ids)) {
+		const left = budgetMs - (rt.clock.now() - started);
+		if (left <= 0 || capLeft <= 0) break;
+		const r = await drainBot(rt, id, {
+			budgetMs: left,
+			...Number.isFinite(capLeft) ? { maxSends: capLeft } : {}
+		});
+		capLeft -= r.claimed;
+		results.push(r);
+	}
+	return results;
+}
+/**
+* The default transport (`name: "outbox"`): `kick()` drains inline within `KICK_BUDGET_MS` (run it in
+* `waitUntil`); otherwise the minute tick drains.
+*/
+function cronTransport(rt) {
+	return {
+		name: "outbox",
+		async kick(botIds) {
+			await drainBots(rt, botIds, Math.min(KICK_BUDGET_MS, rt.limits.tickBudgetMs));
+		}
+	};
+}
+/** Queue transport: `kick()` sends one `drain` message per bot (default: every bot with due work). */
+function queueTransport(rt, queue) {
+	return {
+		name: "queue",
+		async kick(botIds) {
+			const ids = [...new Set(botIds ?? await botsWithDueWork(rt, rt.clock.now()))];
+			if (ids.length === 0) return;
+			const body = (botId) => ({
+				mark: QUEUE_MARK,
+				type: "drain",
+				tenant: rt.tenant,
+				botId
+			});
+			await queue.sendBatch(ids.map((id) => ({ body: body(id) })));
+		}
+	};
+}
+/** Delay before the queue re-kicks a bot whose next row is due later (null = let the tick handle it). */
+function rekickDelaySeconds(r, now) {
+	if (r.stoppedBy === "budget" || r.stoppedBy === "cap") return 0;
+	if (r.stoppedBy !== "idle" || r.nextDueAt === null) return null;
+	const sec = Math.ceil((r.nextDueAt - now) / 1e3);
+	return sec <= 60 ? Math.max(1, sec) : null;
+}
+/**
+* Queue consumer. Handles (acks or retries, one by one) every plugin message of the batch (`isPluginMessage`) and
+* returns true when the batch held nothing else. A batch with host messages too returns false after handling the
+* plugin's: the host then handles the rest and must skip `isPluginMessage(m.body)` messages (and must not
+* `ackAll()` / `retryAll()`). A dedicated plugin queue avoids mixed batches. Drain messages for the same bot are
+* merged; a drain that stops early or has work due soon re-kicks itself with `delaySeconds`.
+*/
+async function handleQueueBatch(rt, batch, opts = {}) {
+	const mine = batch.messages.filter((m) => isPluginMessage(m.body));
+	if (mine.length === 0) return false;
+	await handlePluginMessages(rt, batch, mine, opts);
+	return mine.length === batch.messages.length;
+}
+async function handlePluginMessages(rt, batch, messages, opts) {
+	if (opts.deadLetterQueue !== void 0 && batch.queue === opts.deadLetterQueue) {
+		const own = {
+			queue: batch.queue,
+			metadata: batch.metadata,
+			messages,
+			ackAll: () => {
+				for (const m of messages) m.ack();
+			},
+			retryAll: (o) => {
+				for (const m of messages) m.retry(o);
+			}
+		};
+		await handleDeadLetters(rt, own);
+		return;
+	}
+	const drains = /* @__PURE__ */ new Map();
+	const events = [];
+	for (const m of messages) {
+		const body = m.body;
+		if (body.tenant !== rt.tenant) {
+			m.ack();
+			continue;
+		}
+		if (body.type === "events") {
+			events.push(m);
+			continue;
+		}
+		if (body.type === "drain") {
+			drains.set(body.botId, [...drains.get(body.botId) ?? [], m]);
+			continue;
+		}
+		try {
+			const bot = await loadBot(rt, body.botId);
+			const parsed = parseUpdate(body.update);
+			if (bot && isBotUsable(bot) && parsed.ok) await processUpdate(rt, bot, parsed.update);
+			m.ack();
+		} catch {
+			m.retry({ delaySeconds: 5 });
+		}
+	}
+	if (events.length > 0) try {
+		await runEvents(rt, rt.clock.now());
+		for (const m of events) m.ack();
+	} catch (e) {
+		rt.log.error("tg.queue_events_failed", { error: e instanceof Error ? e.name : "error" });
+		for (const m of events) m.retry({ delaySeconds: 5 });
+	}
+	if (rt.transport.name === "do" && drains.size > 0) {
+		try {
+			await rt.transport.kick([...drains.keys()]);
+			for (const msgs of drains.values()) for (const m of msgs) m.ack();
+		} catch {
+			for (const msgs of drains.values()) for (const m of msgs) m.retry({ delaySeconds: 5 });
+		}
+		return;
+	}
+	const started = rt.clock.now();
+	let capLeft = sendCap(rt);
+	for (const [botId, msgs] of drains) try {
+		const left = rt.limits.tickBudgetMs - (rt.clock.now() - started);
+		if (left <= 0 || capLeft <= 0) {
+			for (const m of msgs) m.retry({ delaySeconds: 1 });
+			continue;
+		}
+		const r = await drainBot(rt, botId, {
+			budgetMs: left,
+			...Number.isFinite(capLeft) ? { maxSends: capLeft } : {}
+		});
+		capLeft -= r.claimed;
+		const delay = rekickDelaySeconds(r, rt.clock.now());
+		if (delay !== null && rt.queue) {
+			const body = {
+				mark: QUEUE_MARK,
+				type: "drain",
+				tenant: rt.tenant,
+				botId
+			};
+			await rt.queue.send(body, delay > 0 ? { delaySeconds: delay } : {});
+		}
+		for (const m of msgs) m.ack();
+	} catch (e) {
+		rt.log.error("tg.queue_drain_failed", {
+			botId,
+			error: e instanceof Error ? e.name : "error"
+		});
+		for (const m of msgs) m.retry({ delaySeconds: 5 });
+	}
+}
+export { KICK_BUDGET_MS, QUEUE_MARK, cronTransport, drainBots, handleQueueBatch, isPluginMessage, queueTransport };

package/dist/engine/outbox/wake.js

@@ -0,0 +1,28 @@
+import { runEvents } from "../events/tick.js";
+import { scheduleWakeStage } from "../schedules/wake.js";
+// src/engine/outbox/wake.ts
+/** Events stage: due events of the tenant (fan-out kicks the bots' objects). No wake of its own (the tick is). */
+async function eventWakeStage(rt, _botId, now) {
+	if (rt.features.events) await runEvents(rt, now);
+	return null;
+}
+/** The stages a TelegramBotDO alarm runs, in order: due schedules of the bot, then due events of the tenant. */
+function wakeStages() {
+	return [scheduleWakeStage, eventWakeStage];
+}
+/** Runs every wake stage for `botId`; failures are logged. Returns the earliest next wake the stages asked for. */
+async function runWake(rt, botId, now, stages = wakeStages()) {
+	let next = null;
+	for (const stage of stages) try {
+		const at = await stage(rt, botId, rt.clock.now());
+		if (typeof at === "number" && Number.isFinite(at)) next = next === null ? at : Math.min(next, at);
+	} catch (e) {
+		rt.log.error("tg.wake_stage_failed", {
+			botId,
+			error: e instanceof Error ? e.name : "error"
+		});
+		next = next === null ? now + 6e4 : Math.min(next, now + 6e4);
+	}
+	return next;
+}
+export { runWake, wakeStages };