ADR 0274 — A Telegram token has one outbound budget
Context
Telegram counts a bot’s bulk messages per token. A bot sends through several paths: a marketing campaign, a reply in a handler, an operator note, a retry after a rate limit. Each path can be paced below the limit on its own and the sum can still be over it, so the limit has to be counted once for the token.
Two ways of counting existed in consuming applications. One kept a token bucket
per token with a full initial bucket and a refill: it released a saved burst at
start and again after a 429 pause, which is exactly when the next message is
most expensive. The other paced one broadcast run at a fixed rate and left every
other sender alone. Neither expressed the unit that Telegram counts — an album
of N media is N messages, a copyMessages of N ids is N messages, and the call
to action after an album is one more.
The primitive is provider-specific: the budget belongs to a Telegram token, the
cost belongs to Bot API methods, and the pause comes from Telegram’s
parameters.retry_after. It is not a durable job queue and not a cross-process
lock. This ADR replaces only the token-wide part of ADR 0201’s position that a
429 on a bot’s own replies stays the application’s; the application still owns
the retry policy and the wording a person reads.
Decision
stitchkit/telegram owns one outbound budget per bot token. A
telegramOutboundBudget({ token, messagesPerSecond }) returns one object for
that token in the process. A second call for the same token returns the same
object; a call with different options is refused, because two policies for one
credential is the defect this exists to prevent. Another token is another
budget. The registry keeps a 128-bit identity of the token from the existing
argumentsDigest, never the credential; stats() and every refusal are
token-free.
The schedule is strict, not a bucket with a burst. The first call after idle
is immediate; after that each call occupies cost / messagesPerSecond of the
timeline. The budget keeps one nextGrantAt and one pausedUntil:
at = max(now, nextGrantAt, pausedUntil)
grant head at at
nextGrantAt = at + cost * 1000 / messagesPerSecond
A classic bucket with capacity 24 would release 24 saved messages at start and
again on resume. That is the stampede a shared budget exists to prevent, so the
burst is one and the sustained rate is the declared rate. An album is weighted,
not one: sendMediaGroup and sendPaidMedia cost their media length,
copyMessages and forwardMessages cost their ids, and every other
message-producing method costs one. A non-message method (getMe, getFile,
an edit, a delete) costs nothing.
A 429 pauses every sender of the token. The pause is
max(pausedUntil, now + retry_after); a second, shorter instruction never
shortens it. Telegram’s number is used when present; when it is absent the
caller’s declared retryAfterFallbackMs is a local policy, not a provider fact.
After the pause the next grant is at the deadline and the following one is one
interval later — the queue is not released as a batch. waitUntilResumed lets
an edit or delete retry share the pause without taking a message slot.
The primitive paces; it does not retry. budget.run(method, payload, signal, send) is the narrow adapter a client transformer calls around its existing
send. It waits for the weighted slot, checks the signal, calls send once, and
rethrows. A 429 pauses and is rethrown. A network failure or a 5xx is rethrown
unchanged and does not pause the token: repeating a send whose external outcome
is unknown is the caller’s decision, and a primitive that retried it would turn
one unknown message into two. A cancelled waiter leaves the queue without
spending a slot and without calling the provider. A granted call whose send is
then aborted owns its slot; the outcome is unknown, not a definite failure.
The budget is process-local. It does not coordinate two processes or two
machines that hold the same token. That is the application’s deployment
boundary, and pretending otherwise would be a second distributed lock. The
primitive also owns no job state: a resumable broadcast keeps its own journal
and per-run pacing; the operator channel keeps its per-chat pacing. Those are
caps of their own jobs, not a second token quota. A product that uses one of
those senders wraps its send with the same budget.run, and removes its old
limiter rather than running both.
Alternatives
- Keep pacing in each product. Rejected: the limit is per token, so each product either duplicates the arithmetic or gets the sum wrong. A product that shares its token with a campaign is the ordinary case, not an edge.
- A generic rate limiter in the core. Rejected: the unit is a Telegram
message, the pause field is
retry_after, and the weighted methods are the Bot API’s. A provider-neutral limiter would push the only interesting part back into every caller. - A cross-process budget in Redis or a database. Rejected for this primitive: it is a second distributed coordination mechanism, and the deployment that needs it already owns a durable queue. The SDK states the process-local boundary instead.
- A full token bucket with capacity 24. Rejected: it produces the initial burst and the post-429 stampede the shared budget is meant to remove. A caller that wants a small burst can build it above this primitive, where the policy is visible.
Consequences
- A product’s one Bot API client installs one transformer; the old limiter and
its retry are deleted in the same cutover. The standard senders remain
per-run/per-chat paced; wrapping their
sendis the documented way to share the token budget. telegramOutboundBudgetis an evolvingstitchkit/telegramexport. The five consuming products migrate in their own release waves after the SDK publication; this repository does not claim their cutover.USER_BOT_TO_BOT_DISABLEDbecomesbot-to-bot-disabled: permanent for the send, not recipient-unreachable, because Telegram reports it when either bot has not enabled Bot to Bot messaging. The new union member is a breaking change for exhaustive consumer tables and carries the usual migration.stats()reports granted calls, weighted messages, queue depth and the remaining pause. It is diagnostic, not a billing or delivery receipt.- Cross-process budgets, durable campaign state and the retry policy stay outside this primitive.
Serves I8 (one owner for the token’s outbound budget), I9 (every declared option is load-bearing), I10 (finite waits and a bounded queue at the provider boundary), I13 (only observed facts: no invented wait, no unknown outcome retried as a definite failure) and I14 (the new reason is a marked, migrated break).
Amendment (0.114.1): a refusal arrives as a response, and grammY’s wiring is one transformer
The first release read a 429 only from the exception send() threw. A grammY
client transformer never sees one: callApi receives the Bot API’s
{ ok: false, error_code: 429, parameters: { retry_after } } as the value
the transformer chain returns and builds the GrammyError after the chain has
finished. The documented wiring therefore paced and never paused, and the
tests, which threw an error from send, could not tell. A consuming project
measured it: the first send got a 429 with retry_after: 2 and the next send,
to another chat, left 40 ms later.
runreads both shapes. Asendthat resolves with a record whoseokisfalseis classified exactly as a thrown refusal is: a rate limit pauses the token for the statedretry_afteror the declared fallback, any other answer does nothing, and the response is returned unchanged. The mechanism is fixed in the one owner, so every client already wired throughrunis repaired without a change of its own.- The grammY wiring is one function, in its own entrypoint.
stitchkit/telegram/grammyexportstelegramBudgetTransformer(budget). The type that grammY gives a transformer (Transformer) names its response per method, which a structural type cannot express without a cast at the call site; naming it institchkit/telegramwould make that peer-free entrypoint depend ongrammy. The new entrypoint followsstitchkit/telegram/screens: grammY in the declarations, never imported at run time. - A cancelled wait is a request that never left. grammY types the signal it
passes a transformer as the
abort-controllerpolyfill’s, so a hand-written closure passedundefinedand a send cancelled in the queue waited for its slot and failed asunknown. The transformer bridges the signal and throwsTelegramNotDispatchedErrorwhen the cancellation arrives before the request was handed to the client — in the queue, or in the instant after the grant, when the slot is spent and nothing was sent. A cancellation after the request was handed on stays the client’s own error and the outcome stays unknown.runitself still rejects withsignal.reason: that contract is unchanged.
The test that pins this uses grammY’s own Api over a fetch that answers 429
the way Telegram does. A test that throws from send proved only the path
nobody takes.