From bebfce73f519cdd49c157cd682131167efa36fa1 Mon Sep 17 00:00:00 2001 From: Lorenzo Corallo Date: Mon, 2 Nov 2026 20:19:37 +0100 Subject: [PATCH 1/5] feat(websocket): post approved regulations to Telegram on the backend's request Handle the backend's new `postRegulation` Socket.IO command: post an Italian HTML announcement (title, approving body, delibera date, opposition/appeal deadline, release link) with the new regulation PDF and the differences PDF to the chat and topic the backend names. The documents go out as one media group captioned on the last document, or as a message followed by the documents when the text does not fit in a caption. Telegram 429s are waited out and retried (5 attempts, 120 s of waiting at most); nothing else is retried, so a post is never duplicated. The ack reports the posted message ids and time, or the error plus any messages already posted. --- src/modules/post-regulation.ts | 188 +++++++++++++++++++++++++ src/modules/websocket.ts | 18 ++- tests/post-regulation.test.ts | 250 +++++++++++++++++++++++++++++++++ 3 files changed, 454 insertions(+), 2 deletions(-) create mode 100644 src/modules/post-regulation.ts create mode 100644 tests/post-regulation.test.ts diff --git a/src/modules/post-regulation.ts b/src/modules/post-regulation.ts new file mode 100644 index 0000000..17b5742 --- /dev/null +++ b/src/modules/post-regulation.ts @@ -0,0 +1,188 @@ +import { type Api, GrammyError, InputFile } from "grammy" +import type { InputMediaDocument, Message } from "grammy/types" +import { z } from "zod/v4" +import { wait } from "@/utils/wait" + +/** Telegram's limits for bot uploads and captions, and for documents in one media group. */ +const MAX_FILE_BYTES = 50 * 1024 * 1024 +const MAX_CAPTION_LENGTH = 1024 +const MAX_FILES = 10 + +const isoDate = z.iso.date() + +const payloadSchema = z.object({ + chatId: z.number().int(), + /** The forum topic (`message_thread_id`); null for a chat without topics. */ + topicId: z.number().int().positive().nullable(), + regulation: z.object({ + /** E.g. "Raccolta dei Regolamenti Interni". */ + title: z.string().trim().min(1), + kind: z.enum(["approval", "rectification"]), + /** Who approved or rectified: "Consiglio Direttivo", "Assemblea", "Segretario", "Mario Rossi su delega del Segretario". */ + body: z.string().trim().min(1), + /** Date of the delibera, or of the rectification, as YYYY-MM-DD. */ + date: isoDate, + /** Last day to file an opposition or appeal, as YYYY-MM-DD; null when none applies. */ + oppositionDeadline: isoDate.nullable(), + /** The GitHub release with the official PDF. */ + releaseUrl: z.url({ protocol: /^https$/ }), + }), + /** The documents to attach, in display order: the new text first, then the differences. */ + files: z + .array( + z.object({ + filename: z.string().trim().min(1), + // socket.io delivers binary attachments as a Buffer over websocket and as an ArrayBuffer over polling. + data: z + .union([z.instanceof(Uint8Array), z.instanceof(ArrayBuffer)]) + .transform((data) => (data instanceof Uint8Array ? data : new Uint8Array(data))) + .refine((data) => data.byteLength > 0, "file is empty") + .refine((data) => data.byteLength <= MAX_FILE_BYTES, "file exceeds Telegram's 50 MB upload limit"), + }) + ) + .min(1) + .max(MAX_FILES), +}) + +export type PostRegulationPayload = z.input +export type RegulationNotice = z.output["regulation"] + +/** + * What the bot answers. `messageIds` lists every message posted, also on failure, since a failure after the + * text was sent leaves a partial post in the chat. + */ +export type PostRegulationResult = + | { ok: true; chatId: number; topicId: number | null; messageIds: number[]; sentAt: Date } + | { ok: false; error: string; messageIds: number[] } + +/** The `postRegulation` command the backend sends; to be dropped once `@polinetwork/backend` exports it. */ +export type PostRegulationEvents = { + postRegulation: (data: PostRegulationPayload, cb: (result: PostRegulationResult) => void) => void +} + +export type RateLimitRetryOptions = { + /** Total attempts, the first included. Default 5. */ + maxAttempts?: number + /** Give up instead of waiting once the waits would add up to more than this. Default 120 s. */ + maxTotalWaitMs?: number + sleep?: (ms: number) => Promise +} + +/** + * Runs `call`, waiting out Telegram's `retry_after` on 429 (Too Many Requests) and trying again. + * Only 429 is retried: Telegram did not perform the request, so trying again cannot post twice. + */ +export async function retryOnRateLimit(call: () => Promise, options: RateLimitRetryOptions = {}): Promise { + const { maxAttempts = 5, maxTotalWaitMs = 120_000, sleep = wait } = options + let waited = 0 + for (let attempt = 1; ; attempt++) { + try { + return await call() + } catch (error) { + if (!(error instanceof GrammyError) || error.error_code !== 429 || attempt >= maxAttempts) throw error + const delay = (error.parameters.retry_after ?? 1) * 1000 + if (waited + delay > maxTotalWaitMs) throw error + waited += delay + await sleep(delay) + } + } +} + +const escapeHtml = (text: string) => text.replaceAll("&", "&").replaceAll("<", "<").replaceAll(">", ">") + +/** YYYY-MM-DD to DD/MM/YYYY, as the documents print it. */ +const italianDate = (date: string) => date.split("-").reverse().join("/") + +/** The announcement, in Telegram HTML. */ +export function formatRegulationNotice(notice: RegulationNotice): string { + const lines = + notice.kind === "approval" + ? [ + `📜 ${escapeHtml(notice.title)}`, + "È stata emanata una nuova versione.", + "", + `Approvazione: ${escapeHtml(notice.body)}, delibera del ${italianDate(notice.date)}`, + ] + : [ + `📜 ${escapeHtml(notice.title)}`, + "È stata emanata una rettifica.", + "", + `Rettifica: ${escapeHtml(notice.body)}, il ${italianDate(notice.date)}`, + ] + if (notice.oppositionDeadline) + lines.push(`Opposizioni e ricorsi: entro il ${italianDate(notice.oppositionDeadline)}`) + lines.push("", `Versione ufficiale`) + return lines.join("\n") +} + +/** The length Telegram checks against its caption limit: the text once the HTML is parsed. */ +function visibleLength(html: string): number { + const text = html + .replace(/<[^>]*>/g, "") + .replaceAll("<", "<") + .replaceAll(">", ">") + .replaceAll(""", '"') + .replaceAll("&", "&") + return text.length +} + +function describeError(error: unknown): string { + if (error instanceof GrammyError) return `${error.method}: ${error.error_code} ${error.description}` + if (error instanceof z.ZodError) return `invalid payload: ${z.prettifyError(error)}` + return error instanceof Error ? error.message : String(error) +} + +type PostApi = Pick + +/** + * Posts a regulation announcement with its documents: one media group (or one document) with the announcement as + * caption, or the announcement as a message followed by the documents when it does not fit in a caption. + */ +export async function postRegulation( + api: PostApi, + payload: unknown, + retry: RateLimitRetryOptions = {} +): Promise { + const messageIds: number[] = [] + try { + const { chatId, topicId, regulation, files } = payloadSchema.parse(payload) + const thread = topicId === null ? {} : { message_thread_id: topicId } + const text = formatRegulationNotice(regulation) + const caption = visibleLength(text) <= MAX_CAPTION_LENGTH ? text : null + const send = (call: () => Promise) => retryOnRateLimit(call, retry) + const record = (...messages: Message[]) => messageIds.push(...messages.map((m) => m.message_id)) + + if (caption === null) { + record( + await send(() => + api.sendMessage(chatId, text, { ...thread, parse_mode: "HTML", link_preview_options: { is_disabled: true } }) + ) + ) + } + + const documents = files.map((file) => new InputFile(file.data, file.filename)) + if (documents.length === 1) { + record( + await send(() => + api.sendDocument(chatId, documents[0], { + ...thread, + ...(caption === null ? {} : { caption, parse_mode: "HTML" }), + }) + ) + ) + } else { + // In a group of documents each one keeps its own caption: the last one reads as the album's. + const media = documents.map( + (media, i): InputMediaDocument => + i === documents.length - 1 && caption !== null + ? { type: "document", media, caption, parse_mode: "HTML" } + : { type: "document", media } + ) + record(...(await send(() => api.sendMediaGroup(chatId, media, thread)))) + } + + return { ok: true, chatId, topicId, messageIds, sentAt: new Date() } + } catch (error) { + return { ok: false, error: describeError(error), messageIds } + } +} diff --git a/src/modules/websocket.ts b/src/modules/websocket.ts index c62a885..0208cda 100644 --- a/src/modules/websocket.ts +++ b/src/modules/websocket.ts @@ -1,7 +1,7 @@ import { type TelegramSocket, WS_PATH } from "@polinetwork/backend" import * as parser from "@socket.io/devalue-parser" import type { User } from "grammy/types" -import { io } from "socket.io-client" +import { io, type Socket } from "socket.io-client" import { serviceTokens } from "@/backend" import { env } from "@/env" import { Module } from "@/lib/modules" @@ -9,6 +9,7 @@ import { logger } from "@/logger" import { MessageUserStorage } from "@/middlewares/message-user-storage" import { duration } from "@/utils/duration" import type { ModuleShared } from "@/utils/types" +import { type PostRegulationEvents, postRegulation } from "./post-regulation" import type { TgLogger } from "./tg-logger" import type { GrantActor } from "./tg-logger/types" import { SocketTokenAuth } from "./websocket-auth" @@ -46,13 +47,19 @@ type SocketError = { type: string } +/** The backend's commands, plus the ones the bot handles before `@polinetwork/backend` exports them. */ +type BotSocket = + TelegramSocket extends Socket + ? Socket + : never + /** * WebSocket to handle from-backend communication * * @param bot - The telegram bot instance */ export class WebSocketClient extends Module { - private io: TelegramSocket + private io: BotSocket private lastErrorCode: string | null = null private tokenAuth = new SocketTokenAuth(serviceTokens, { logger }) @@ -175,6 +182,13 @@ export class WebSocketClient extends Module { + const result = await postRegulation(this.shared.api, data) + if (result.ok) logger.info({ chatId: result.chatId, messageIds: result.messageIds }, "[WS] regulation posted") + else logger.error({ error: result.error, messageIds: result.messageIds }, "[WS] cannot post the regulation") + cb(result) + }) } override async start() { diff --git a/tests/post-regulation.test.ts b/tests/post-regulation.test.ts new file mode 100644 index 0000000..ea5dbf0 --- /dev/null +++ b/tests/post-regulation.test.ts @@ -0,0 +1,250 @@ +import { GrammyError, InputFile } from "grammy" +import type { InputMediaDocument } from "grammy/types" +import { describe, expect, it, vi } from "vitest" +import { + formatRegulationNotice, + type PostRegulationPayload, + postRegulation, + type RegulationNotice, + retryOnRateLimit, +} from "@/modules/post-regulation" + +const notice: RegulationNotice = { + title: "Raccolta dei Regolamenti Interni", + kind: "approval", + body: "Consiglio Direttivo", + date: "2026-10-08", + oppositionDeadline: "2026-10-18", + releaseUrl: "https://github.com/PoliNetworkOrg/legal/releases/tag/rri-v2026.10.08", +} + +const payload = (overrides: Partial = {}): PostRegulationPayload => ({ + chatId: -1001234, + topicId: 42, + regulation: notice, + files: [ + { filename: "rri-v2026.10.08.pdf", data: new Uint8Array([1, 2, 3]) }, + { filename: "rri-v2026.10.08-differenze.pdf", data: new Uint8Array([4, 5]) }, + ], + ...overrides, +}) + +const rateLimited = (method: string, retryAfter: number) => + new GrammyError( + "Too Many Requests", + { + ok: false, + error_code: 429, + description: `Too Many Requests: retry after ${retryAfter}`, + parameters: { retry_after: retryAfter }, + }, + method, + {} + ) + +function fakeApi() { + let nextId = 100 + return { + sendMessage: vi.fn(async () => ({ message_id: nextId++ })), + sendDocument: vi.fn(async () => ({ message_id: nextId++ })), + sendMediaGroup: vi.fn(async (_chat: number, media: unknown[], _other?: object) => + media.map(() => ({ message_id: nextId++ })) + ), + } +} + +/** The fake only returns the message ids the code reads. */ +const asApi = (api: ReturnType) => api as unknown as Parameters[0] + +describe("formatRegulationNotice", () => { + it("lists title, body, delibera date, opposition deadline and release link in Italian", () => { + expect(formatRegulationNotice(notice)).toBe( + [ + "📜 Raccolta dei Regolamenti Interni", + "È stata emanata una nuova versione.", + "", + "Approvazione: Consiglio Direttivo, delibera del 08/10/2026", + "Opposizioni e ricorsi: entro il 18/10/2026", + "", + 'Versione ufficiale', + ].join("\n") + ) + }) + + it("words a rectification as such and omits a missing deadline", () => { + const text = formatRegulationNotice({ + ...notice, + kind: "rectification", + body: "Mario Rossi su delega del Segretario", + oppositionDeadline: null, + }) + expect(text).toContain("È stata emanata una rettifica.") + expect(text).toContain("Rettifica: Mario Rossi su delega del Segretario, il 08/10/2026") + expect(text).not.toContain("Opposizioni") + }) + + it("escapes HTML in every field it is given", () => { + const text = formatRegulationNotice({ + ...notice, + title: "A & B", + body: "