mirror of
https://github.com/lukaszraczylo/go-telegram.git
synced 2026-06-05 22:43:59 +00:00
lukaszraczylo
370c9c0802
Sealed-interface union variants now hardcode their wire discriminator
inside a generated MarshalJSON method instead of forcing callers to set
the field on every struct literal. Drops a class of silent-rejection
bugs where a typo in the discriminator slipped past the type checker
and through to Telegram, which then rejected the request with no
Go-side signal.
The discriminator field stays exported so incoming-message decoding,
type switches and debugging still see it. MarshalJSON wraps via a
function-local type alias and emits an outer field with the same json
tag; encoding/json (and goccy/go-json) resolve the outer field as the
shallower one and override whatever the caller wrote.
99 variants get MarshalJSON. 7 are skipped because their unions
dispatch structurally rather than by a string field: Message and
InaccessibleMessage (MaybeInaccessibleMessage, dispatched on date),
and the InputMessageContent family (InputTextMessageContent,
InputLocationMessageContent, InputVenueMessageContent,
InputContactMessageContent, InputInvoiceMessageContent — Telegram
identifies these by the presence of message_text / latitude /
phone_number / title etc.).
Discriminator extraction lives in the emitter (cmd/genapi/emitter.go).
Resolution: knownDiscriminators reverse-lookup for the 13 auto-decode
unions, then doc-string analysis ("must be X" / "always “X”")
of the variant's first required string field for marker-only unions
(BotCommandScope, InputMedia, InputPaidMedia, InputProfilePhoto,
InputStoryContent, InputPollMedia, InputPollOptionMedia,
InlineQueryResult, PassportElementError). Variants the emitter cannot
resolve a discriminator for are skipped silently rather than emitting
broken code.
Internal call-site cleanups: 4 manual discriminator assignments
removed (api/unionparam_test.go,
dispatch/filters/message/message_test.go, examples/inline/main.go ×2).
Regression tests added in api/marshaljson_variants_test.go covering
type-keyed variants, source-keyed variants, the override-user-typo
guarantee, round-trip preservation through UnmarshalChatMember, the
no-discriminator InputMessageContent path, and ride-along of
non-discriminator fields.
regen-from-fixture is deterministic across two consecutive runs;
go test -race / go vet / staticcheck all clean.
Examples
Each subdirectory contains a self-contained sample bot demonstrating one feature area.
| Example | What it shows |
|---|---|
| echo | Long-poll bot that echoes text back to the sender |
| webhook | Webhook delivery with secret-token verification |
| callback | Inline keyboard with callback queries and counter state |
| conversation | Multi-step conversation flow with dispatch/conversation |
| files | Upload and download files via api.DownloadFile |
| inline | Inline-mode bot returning search-style results |
| middleware | Custom middleware chains via Router.Use |
| stateful | Per-user state managed via closures |
| welcome | Greet new chat members; detect and log departures |
| moderation | /kick, /ban, /mute, /warn with admin permission checks |
| polls | Create polls and tally answers via OnPollAnswer |
| payments | Telegram Payments: sendInvoice → pre_checkout_query → successful_payment |
| pagination | Multi-page inline keyboard with stateless prev/next navigation |
| admin | Auth middleware allowlisting specific user IDs via Router.Use |
Running
All examples follow the same pattern:
export TELEGRAM_BOT_TOKEN=123456:ABC...
go run ./examples/<name>
Webhook examples need a public HTTPS endpoint (use Cloudflare Tunnel, ngrok, or similar).
Common patterns
Retry-safe HTTP — every example wraps the HTTP client with client.NewRetryDoer, which automatically honours Telegram's retry_after field on 429 responses.
Graceful shutdown — all examples use signal.NotifyContext so the bot drains cleanly on SIGINT/SIGTERM.
Structured logging — for production, wire a logger via client.WithLogger and wrap the process in supervision (systemd unit, k8s liveness probe, etc.).