README
¶
contrib
Companion packages for gotd — the Telegram MTProto
client in Go. These are optional, batteries-included helpers that bring in
heavier third-party dependencies (databases, object stores, OpenTelemetry, NTP,
…) and therefore live outside the core gotd/td module so the core stays
dependency-light.
Install
go get github.com/gotd/contrib
Each package is independent — importing one only pulls in the dependencies that package actually needs.
Packages
Running & lifecycle
| Package | Description |
|---|---|
bg |
Run a client in the background. Connect blocks until the client is connected and ready, then returns a StopFunc you call to shut it down — handy when client.Run's callback style does not fit your control flow. Supports WithContext and WithStartupTimeout. |
Middleware & RPC
| Package | Description |
|---|---|
middleware/floodwait |
Catches Telegram FLOOD_WAIT errors and retries transparently. Waiter is a scheduler-based implementation for long-running, concurrent programs (wrap your run loop with Waiter.Run); SimpleWaiter is a timer-based variant for one-off scripts. Both support WithMaxRetries/WithMaxWait. |
middleware/ratelimit |
Token-bucket rate limiter (golang.org/x/time/rate) that paces outgoing requests to stay under Telegram's limits. Pairs naturally with floodwait. |
invoker |
RPC invoker helpers and middlewares, including a debug invoker and an update-aware invoker. |
oteltg |
OpenTelemetry instrumentation for gotd: traces and metrics for outgoing RPCs. |
Authentication
| Package | Description |
|---|---|
auth |
Interfaces, implementations and utilities for telegram.UserAuthenticator — read credentials from constructors/env, ask interactively, and compose sign-up flows. |
auth/terminal |
Terminal-based UserAuthenticator that prompts for phone, code, password and sign-up info. Uses an interactive terminal when stdin is a tty and falls back to a buffered reader for pipes, files and CI. |
auth/dialog |
Compose an authenticator from individual dialog functions. |
auth/kv |
Credential/session helpers built over a generic key-value store. |
auth/localization |
Localizable prompt strings for the terminal authenticator. |
Storage — sessions, peers & state
These implement the telegram.SessionStorage, peer storage and update-state
storage interfaces against various backends. storage defines the common peer
abstractions; the rest are backend implementations.
| Package | Description |
|---|---|
storage |
Common peer-storage structures: a PeerStorage interface, peer collector, resolver cache and iteration helpers shared by the backends below. |
bbolt |
Session, peer and update-state storage backed by etcd bbolt (embedded). |
pebble |
Storage backed by CockroachDB Pebble (embedded LSM). |
redis |
Storage backed by Redis. |
s3 |
Session storage backed by any S3-compatible object store (MinIO client). |
vault |
Secret/session storage backed by HashiCorp Vault. |
I/O & streaming
| Package | Description |
|---|---|
tg_io |
Partial (ranged) I/O over Telegram — download arbitrary byte ranges of a file. |
partio |
Chunk-based reader/writer primitives that align arbitrary reads/writes to fixed-size chunks. |
http_io |
HTTP handlers built on the partial I/O primitives, e.g. serving Telegram media over HTTP. |
http_range |
Parser for HTTP Range request headers. |
Utilities
| Package | Description |
|---|---|
clock |
Clock sources, including an NTP-backed clock so MTProto time sync works on hosts with a skewed system clock. |
Documentation
Per-package API docs are on pkg.go.dev, and guides live in the gotd documentation site (see the contrib packages page under Helpers).
License
Directories
¶
| Path | Synopsis |
|---|---|
|
Package auth provides some interfaces, implementations and utility function for telegram.UserAuthenticator.
|
Package auth provides some interfaces, implementations and utility function for telegram.UserAuthenticator. |
|
dialog
Package dialog contains GUI dialog Telegram authenticator.
|
Package dialog contains GUI dialog Telegram authenticator. |
|
kv
Package kv contains wrapper implementations over generic KV storage.
|
Package kv contains wrapper implementations over generic KV storage. |
|
localization
Package localization contains localization helpers for terminal and dialog authenticator.
|
Package localization contains localization helpers for terminal and dialog authenticator. |
|
terminal
Package terminal contains authenticator implementation using terminal.
|
Package terminal contains authenticator implementation using terminal. |
|
Package bbolt contains gotd storage implementations using etcd bbolt.
|
Package bbolt contains gotd storage implementations using etcd bbolt. |
|
Package bg implements wrapper for running client in background.
|
Package bg implements wrapper for running client in background. |
|
Package clock wraps clock sources.
|
Package clock wraps clock sources. |
|
Package http_io implements http handlers based on partial input/output primitives.
|
Package http_io implements http handlers based on partial input/output primitives. |
|
Package http_range implements http range parsing.
|
Package http_range implements http range parsing. |
|
internal
|
|
|
tests
Package tests contains common storage tests and some test utilities.
|
Package tests contains common storage tests and some test utilities. |
|
Package invoker contains RPC invoker helpers and middlewares.
|
Package invoker contains RPC invoker helpers and middlewares. |
|
Package middleware wraps some useful middlewares for telegram.
|
Package middleware wraps some useful middlewares for telegram. |
|
floodwait
Package floodwait implements a tg.Invoker that handles flood wait errors.
|
Package floodwait implements a tg.Invoker that handles flood wait errors. |
|
ratelimit
Package ratelimit implements a tg.Invoker that limits request rate.
|
Package ratelimit implements a tg.Invoker that limits request rate. |
|
tg_prom
Package tg_prom implements middleware for prometheus metrics.
|
Package tg_prom implements middleware for prometheus metrics. |
|
Package oteltg provides OpenTelemetry instrumentation for gotd.
|
Package oteltg provides OpenTelemetry instrumentation for gotd. |
|
Package partio implements chunk-based input/output where aligning is required.
|
Package partio implements chunk-based input/output where aligning is required. |
|
Package pebble contains gotd storage implementations using CockroachDB pebble.
|
Package pebble contains gotd storage implementations using CockroachDB pebble. |
|
Package redis contains gotd storage implementations using Redis.
|
Package redis contains gotd storage implementations using Redis. |
|
Package s3 contains gotd storage implementations using S3 protocol.
|
Package s3 contains gotd storage implementations using S3 protocol. |
|
Package storage contains common structures for iterating over peer storage.
|
Package storage contains common structures for iterating over peer storage. |
|
Package tg_io implements partial i/o using telegram.
|
Package tg_io implements partial i/o using telegram. |
|
Package vault contains gotd secret storage implementations using Hashicorp Vault.
|
Package vault contains gotd secret storage implementations using Hashicorp Vault. |
Click to show internal directories.
Click to hide internal directories.