Skip to content

feat(websocket): post approved regulations to Telegram on the backend's request - #161

Merged
lorenzocorallo merged 6 commits into
mainfrom
feat/post-regulation
Nov 15, 2026
Merged

lorenzocorallo merged 6 commits into
mainfrom
feat/post-regulation

Conversation

@lorenzocorallo

@lorenzocorallo lorenzocorallo commented Nov 2, 2026 •

Copy link
Copy Markdown
Member

Telegram side of the regulations editor (spec decision 12, postRegulation contract). The backend sends postRegulation over the existing Socket.IO channel. The bot posts the backend's text with the new regulation PDF and the differences PDF to the chat and topic it is given, then acks with the message ids so the backend can record the send.

Contract

PostRegulation from PoliNetworkOrg/backend#117 (src/websocket/telegram.ts):

postRegulation: (
  data: {
    chatId: number                // backend env REGULATIONS_TELEGRAM_CHAT_ID
    topicId: number | null        // backend env REGULATIONS_TELEGRAM_TOPIC_ID
    text: string                  // Telegram HTML, escaped by the backend; posted as is
    regulation: { documentTitle; draftTitle; body; deliberaDate; oppositionDeadline; tag; dashboardUrl: string | null } // not read by the bot
    files: { filename: string; contentType: string; base64: string }[] // official PDF, then differenze-<tag>.pdf
    idempotencyKey: string        // the backend's notification id, the same on every retry
  },
  cb: (error: string | null, result?: { messageIds: number[] }) => void
) => void

The files travel as base64, not bytes: @socket.io/bun-engine 0.1.0 doesn't deliver socket.io binary attachments. The bot decodes with Buffer.from(base64, "base64"). @polinetwork/backend v4 doesn't export the command yet, so the type is declared locally (PostRegulationEvents). Once a published SDK has it, the BotSocket type in websocket.ts can go. The bot validates with zod only the fields it uses.

Behaviour

  • Both files go out as one sendMediaGroup of documents in the topic, with text as the caption (HTML) of the last document. Telegram shows a document's caption under that document: on the last one it reads as the album's caption, on the first it would sit between the two PDFs. A single file goes out with sendDocument. A text longer than 1024 visible characters goes out first as its own message, and the documents follow uncaptioned. The backend's ~600 characters fit as a caption.
  • Ack: cb(null, { messageIds }). On failure: cb(reason, { messageIds }), where messageIds lists anything posted before the failure (usually empty). A payload that fails validation is refused before any Telegram call.
  • Rate limits: on a 429 the bot waits retry_after and tries again, up to 5 attempts and 30 s of waiting in total. With the uploads, that keeps the answer inside the backend's 60 s ack timeout. No other error is retried, because a retry could post twice.
  • Idempotency: a command with an idempotencyKey it has already seen, repeated while the first is still running waits for it and gets its answer. One repeated after a success, within 24 h, gets the same message ids without posting again. Failures are forgotten so a retry posts again. The keys live in memory, so a bot restart forgets them.

Backend notes (PoliNetworkOrg/backend#117)

  • Settled: base64 files, the idempotency key on every retry, and the ack read through timeout(60_000).emit(..., (timeout, err, result) => …).
  • Resolved in the backend: the text names only the PDFs actually attached, links no GitHub URL (the legal repo is private), and has no empty href. regulation.releaseUrl became dashboardUrl: string | null; the bot never read it.

Verification

  • pnpm test: 224 passed after merging current main (1 skipped test was already skipped before this PR); pnpm typecheck and pnpm check are clean. tests/post-regulation.test.ts covers media group vs. single document vs. separate message, the topic going through, base64 decoding to the exact bytes, the caption limit counted on visible text, 429 retry with its attempt and 30 s limits, a partial send being reported, invalid payloads (including non-base64 content and a missing key), and idempotency (repeat while in flight, after success, after the TTL, after a failure, no key).
  • End to end with a mocked Telegram API, run locally and not committed:
    • A real socket.io server with @socket.io/devalue-parser, standing in for the backend, sent the backend's exact shape with a 3 MB and a 200 KB PDF. It sent the same command twice with the same key, 0.5 s apart.
    • The bot side used the same handler wiring and the same autoRetry + parseMode("MarkdownV2") transformers as bot.ts.
    • The grammY Api pointed at a local fake Bot API server that parses the multipart upload and answers the first sendMediaGroup with a 429 (retry_after: 4).
    • Results, over both websocket and polling: the uploaded files' sha256 matched what was sent, parse_mode: "HTML" and message_thread_id went through, the bot retried after 4 s, the repeated command made no extra Telegram call, and emit with a callback received (null, null, { messageIds: [500, 501] }).
  • End to end against the backend's real Bun engine (Bun 1.3.11, the backend's @socket.io/bun-engine 0.1.0 + socket.io 4.8.3 + devalue parser):
    • The server was wired like server.ts: /ws/ routed to engine.handleRequest, with the engine's websocket handlers.
    • It used the same timeout(60_000).emit callback as WebSocketServer.postRegulation and the backend's exact text.
    • Files were RaccoltaRegolamentiInterni.pdf (4 MB) and differenze-rri-v2026.11.02.pdf (300 KB), as base64.
    • The same command went twice with the same key, 0.5 s apart.
    • The bot connected on WS_PATH, both with default transports (polling, then upgrade) and websocket-only.
    • Results: the uploaded files' sha256 matched what was sent, the HTML caption sat on the last document in topic 77, and the 429 was waited out. One post was made, and both acks got { messageIds: [500, 501] }. A second notification to a chat Telegram refuses came back to the backend as sendMediaGroup: 400 Bad Request: chat not found.
    • Before the switch to base64, the same run with Uint8Array files failed: the bot's decoder threw got plaintext data when reconstructing a packet and dropped the connection, matching what the backend thread found.
  • Not verified: a send to a real Telegram chat. The repo has no dev bot or test chat configured, and the chat and topic ids are still pending from Lorenzo.

…'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.
@coderabbitai

coderabbitai Bot commented Nov 2, 2026 •

Copy link
Copy Markdown
Contributor

Explain Change →

Warning

Review limit reached

You've used all free OSS reviews for now. Wait for the free limit to reset to keep reviewing this public repository.

Next included review available in 49 minutes.

Check out review usage here.

View limit details

Limit details: You’ve used the included review currently available.

Learn how review limits work.

Review configuration:

Run configuration

  • Source mode: Auto
  • Repository: Unavailable
  • Branch: Unavailable
  • File: No configuration file from this repository applied
  • Commit: Unavailable
  • Layers: Organization UI
  • Review profile: CHILL
  • Plan: Advanced
  • Run ID: 1213faaf-7856-4af3-8741-6b9a428050a3
Commits

Reviewing files that changed from the base of the PR and between de94d10 and a048885.

Files selected for processing: 2

  • src/modules/post-regulation.ts
  • tests/post-regulation.test.ts

No actionable comments were generated in the recent review.

Walkthrough

The change adds payload validation, Telegram text and document delivery, rate-limit retries, and in-memory idempotency. A WebSocket event handler invokes the posting operation and acknowledges with message IDs and any error.

Changes

Regulation posting

Layer / File(s) Summary
Payload validation and retry handling
src/modules/post-regulation.ts, tests/post-regulation.test.ts
Adds payload and result types, validates text and file inputs, and retries Telegram 429 errors within configured attempt and wait limits. Tests cover validation and retry behavior.
Telegram delivery and idempotency
src/modules/post-regulation.ts, tests/post-regulation.test.ts
Sends long text separately and attaches shorter text as a caption. Sends one file as a document or multiple files as a media group. Returns sent message IDs with failures when applicable. Keyed calls reuse in-flight or cached successful results. Tests cover posting, partial failures, and idempotency.
WebSocket posting integration
src/modules/websocket.ts
Adds the posting event to the client socket type. The handler passes an optional idempotency key to the posting operation and acknowledges with the error and message IDs.

Sequence Diagram(s)

sequenceDiagram
  participant WebSocketClient
  participant IdempotentPosts
  participant postRegulation
  participant TelegramAPI
  WebSocketClient->>IdempotentPosts: Run posting with optional idempotency key
  IdempotentPosts->>postRegulation: Invoke posting operation
  postRegulation->>TelegramAPI: Send text or documents
  TelegramAPI-->>postRegulation: Return message IDs or error
  postRegulation-->>IdempotentPosts: Return posting result
  IdempotentPosts-->>WebSocketClient: Return result for acknowledgement
Loading

Change: Feature

Merge Risk: Moderate · previous review de94d

A regulation notice longer than Telegram's 4096-character message limit would fail to post along with its documents, and the backend would see the failure. Handle or limit long notices before merging; the rest of the change looks sound.

Pre-merge checks: Passed 3

Check name Status Explanation
Title check Passed The title names the primary change: adding a Telegram regulation-posting handler, reached through the websocket client, that sends approved regulations at the backend's request. The summary and object…
Linked Issues check Passed Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check Passed Check skipped because no linked issues were found for this pull request.
Full details: Title check

Explanation

The title names the primary change: adding a Telegram regulation-posting handler, reached through the websocket client, that sends approved regulations at the backend's request. The summary and objectives describe a postRegulation Socket.IO handler, the Telegram posting logic, and the websocket wiring, so the title matches the changeset. The title is 79 characters, within a reasonable length.

  • Autofix · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

Share

Recent review info

Run configuration

  • Source mode: Auto
  • Repository: Unavailable
  • Branch: Unavailable
  • File: No configuration file from this repository applied
  • Commit: Unavailable
  • Layers: Organization UI
  • Review profile: CHILL
  • Plan: Advanced
  • Run ID: f334d3c4-d6f8-411f-a05a-c5428142f581
Commits

Reviewing files that changed from the base of the PR and between b1b8304 and de94d10.

Files selected for processing: 2

  • src/modules/post-regulation.ts
  • tests/post-regulation.test.ts

Included review availability: This review used your included allowance. Your plan provides up to 1 included review per hour; 0 remain after this review.

@coderabbitai coderabbitai Bot left a comment •

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

  • Fix comments: Fix CodeRabbit comments on this PR

Comment thread src/modules/post-regulation.ts Resolved
lorenzocorallo and others added 5 commits November 2, 2026 20:27
Build against the shape the backend defines in src/websocket/telegram.ts:
post the backend's ready `text` (no formatting in the bot), files carry a
contentType, and the ack is `cb(error, { messageIds })`.

Wait at most 30 s on rate limits so the bot answers inside the backend's
60 s ack timeout, and dedupe on an optional `idempotencyKey`: a command
repeated while the first is in flight, or after it succeeded, gets the first
answer instead of posting again. Failures are forgotten so a retry reposts.

BREAKING CHANGE: the postRegulation payload and ack changed; nothing sends
the command yet.
… idempotency key

The backend's Bun socket.io engine does not deliver binary attachments, so
the backend now sends each file as `base64: string`; the bot decodes it and
refuses non-base64 content. `idempotencyKey` is now always sent (the
backend's notification id), so it is required: a payload without it is
refused before any Telegram call.

BREAKING CHANGE: postRegulation files carry `base64` instead of `data`, and
`idempotencyKey` is required.
The backend replaced regulation.releaseUrl with dashboardUrl (the legal repo is private). The bot does not read regulation, so only its declared type and the test fixture change.
@lorenzocorallo
lorenzocorallo merged commit 4766818 into main Nov 15, 2026
2 checks passed
@lorenzocorallo
lorenzocorallo deleted the feat/post-regulation branch November 15, 2026 03:03
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant