Conn represents a MTProto client to Telegram.ackBatchSizeintackIntervaltime.Duration ackSendChan is queue for outgoing message id's that require waiting for
ack from server.authKeycrypto.AuthKeycipherCipher Wrappers for external world, like current time, logs or PRNG.
Should be immutable. compressThreshold is a threshold in bytes to determine that message
is large enough to be compressed using gzip.conntransport.ConndcIDintdialTimeouttime.DurationdialerDialer exchangeLock locks write calls during key exchange.exchangeTimeouttime.DurationgetTimeoutfunc(req uint32) time.Duration gotSession is a signal channel for wait for handleSessionCreated message.handlerHandlerloglog.HelpermessageIDMessageIDSource // replay attack protectionpermKeycrypto.AuthKey permKeyCheck overrides checkPermKey in tests. unix timestamp when permanent key was generated by this process.
Zero means "unknown" (for restored sessions). pfs enables dual-key lifecycle (perm+temp) and binding/renewal loops. pfsBindingLost is signaled when the server reports AUTH_KEY_PERM_EMPTY
in PFS mode: the connection is recreated with a new temporary key. callbacks for ping results.
Key is ping id. pingInterval is duration between ping_delay_disconnect request.pingMuxsync.Mutex pingTimeout sets ping_delay_disconnect delay. Ensure Run once.randio.ReaderreqMuxsync.Mutexrpc*rpc.EnginersaPublicKeys[]exchange.PublicKeysaltint64saltFetchIntervaltime.Duration server salts fetched by getSalts. sentContentMessages is count of created content messages, used to
compute sequence number within session.serverTime*ServerTime sessionContinued is set by connect when the connection continues a
session from sessionState: the server sends no new_session_created. sessionFailed is signaled when the server session can't be used any
more (msg_id too high): Run stops, so the connection is replaced by
one in a new session.sessionIDint64 use session() to access authKey, salt or sessionID. sessionStartMsgID is the first msg_id of the current session after an
in-place session reset, see resetSession. sessionState keeps the server session across reconnects, nillable. unix timestamp when temporary key expires. tempKeyTTL controls requested temporary key lifetime in seconds.types*tmap.Map wire is the optional wire tracer, wireID is the connection id
reported to it.wireIDint64 Invoke sends input and decodes result into output.
NOTE: Assuming that call contains content message (seqno increment). Ping sends ping request to server and waits until pong is received or
context is canceled. Run initializes MTProto connection to server and blocks until disconnection.
When connection is ready, Handler.OnSession is called.(*Conn) ackLoop(ctx context.Context) error beforeSession reports whether msgID was allocated before the current
session was started by resetSession.(*Conn) bindTempAuthKey(ctx context.Context) error(*Conn) bindTempAuthKeyAttempt(ctx context.Context) error checkPermKey reports whether the server does not know the permanent key:
it sends help.getNearestDc encrypted with the permanent key (without PFS)
on a separate connection. The server answers -404 for an unknown key, which
makes that connection generate a new key. connect establishes connection using configured transport, creating
new auth key if needed.(*Conn) connectPFS(ctx context.Context) error(*Conn) consumeMessage(ctx context.Context, buf *bin.Buffer) error createAuthKey generates new authorization key.(*Conn) createPermAuthKey(ctx context.Context) error(*Conn) createTempAuthKey(ctx context.Context) error currentSessionID returns current session id.(*Conn) decryptMessage(b *bin.Buffer) (*crypto.EncryptedMessageData, error)(*Conn) dropPFSKeys()(*Conn) dropRPC(req rpc.Request) error encodeHTTPWait builds an encrypted http_wait service message into a fresh
buffer. It mirrors write, but does not send: the transport sends the frame as
a long-poll POST. enqueueAck enqueues message id for acknowledgement by ackLoop. failSession ends the server session after bad_msg_notification "msg_id
too high": msg_ids already sent in it were ahead of the server time, and
ids must keep increasing within a session, so corrected ids can only be
used in a new one. The message id generator is reset to the corrected
time and the connection is replaced by one in a new session; pending
requests are sent again there. This is what TDLib does
(SessionConnection: "Session will be closed", a new Session with new
AuthData follows).(*Conn) getSalts(ctx context.Context) error(*Conn) handleAck(b *bin.Buffer) error(*Conn) handleAuthKeyNotFound(ctx context.Context) error handleBadMsg handles bad_msg_notification and bad_server_salt received in
the message msgID.(*Conn) handleBindConnectionNotInited(attempt int) error handleBindEncryptedMessageInvalid decides what to do when
auth.bindTempAuthKey returns ENCRYPTED_MESSAGE_INVALID: retry the bind
(nil), reconnect, or drop the permanent key (ErrPFSDropKeysRequired).
The PFS docs say to drop both keys when the permanent key is older than
60 seconds, but that loses the authorization on a false positive. Like
TDLib (Session::on_bind_result), the permanent key is immune when it is
younger than 60 seconds (not yet propagated), or older than a day and was
bound successfully within the last day. Otherwise it is checked with a
request encrypted with it (checkPermKey) and dropped only if the server
does not know it. handleClose closes rpc engine and underlying connection on context done.(*Conn) handleContainer(ctx context.Context, b *bin.Buffer) error(*Conn) handleFutureSalts(b *bin.Buffer) error(*Conn) handleGZIP(ctx context.Context, msgID int64, b *bin.Buffer) error(*Conn) handleMessage(ctx context.Context, msgID int64, b *bin.Buffer) error(*Conn) handlePong(b *bin.Buffer) error(*Conn) handleResult(b *bin.Buffer) error(*Conn) handleSessionCreated(b *bin.Buffer) error(*Conn) invoke(ctx context.Context, req rpc.Request) error(*Conn) invokeOnce(ctx context.Context, input bin.Encoder, output bin.Decoder) error(*Conn) logExchangeInit(ctx context.Context)(*Conn) logWithBuffer(b *bin.Buffer) log.Helper(*Conn) logWithType(b *bin.Buffer) log.Helper(*Conn) logWithTypeID(id uint32) log.Helper(*Conn) newEncryptedMessage(id int64, seq int32, payload bin.Encoder, b *bin.Buffer) error(*Conn) newMessageID() int64 newSessionID sets session id to random value.(*Conn) nextMsgSeq(content bool) (msgID int64, seqNo int32) nextPing returns the time until the next ping and its disconnect_delay.
With the default (zero) pingInterval, the interval is random in
[pingSendAfter, pingSendAfterForce]: Telegram Desktop sends a ping at the
first send after pingSendAfter or by timer at pingSendAfterForce, which
gives 30–45 s on the wire.(*Conn) noUpdates(err error) bool observeExchangeTime updates the server time offset from the server_time of
a key exchange (unix seconds, zero if unknown), like Telegram Desktop does. observeServerTime updates the server time offset from the time encoded in
a received msg_id.(*Conn) pingDelayDisconnect(ctx context.Context, delay int) error(*Conn) pingLoop(ctx context.Context) error(*Conn) pong(pingID int64) chan struct{} processContainerMessage handles a single message of a received container.
The container itself is not content-related (even seqno), so content-related
inner messages (odd seqno) must be acknowledged individually, like tdesktop
and tdlib do.
Inner msg_ids are checked for duplicates like top-level ones (tdesktop
registers them in its received ids, Android checks isMessageIdProcessed): a
message the server sends again, e.g. in a new container after our ack was
lost, is acknowledged again but not handled twice.(*Conn) readLoop(ctx context.Context) (err error) releaseSessionState saves the session of this connection for the next one.(*Conn) removePong(pingID int64) resetSession clears the state bound to the previous session after the
auth key and session were replaced in place: the new session starts with
seqno 0, an empty received msg_id buffer and no cached future salts, and
pending requests are sent again in it. Pending acks are dropped by ackLoop.
This matches tdesktop (SessionPrivate::changeSessionId on a key change,
followed by resendAll).
Must be called with exchangeLock held for writing, so nothing is sent
with the old msg_id and seqno in the new session. reuseSession continues the server session saved in sessionState for key,
if any.(*Conn) runExchange(ctx context.Context, mode exchange.ExchangeMode, expiresIn int) (exchange.ClientExchangeResult, error) saltLoop fetches future salts every saltFetchInterval. It runs only if
the interval is set.
Nothing is fetched at start: Telegram Desktop never sends
get_future_salts, it uses the salt of new_session_created and the one
bad_server_salt brings when the current salt expires. serverNow returns the current server time, or local time if the connection
has no ServerTime. serverTimeOffset returns the server time offset, zero if unknown. Session returns current connection session info. startHTTPWait enables http_wait long-polling if the transport requires it.
It is a no-op for transports that do not implement httpWaiter (TCP, WebSocket,
MTProxy), which receive server pushes over a full-duplex socket instead.(*Conn) storeSalt(salt int64)(*Conn) tempKeyRenewalLoop(ctx context.Context) error traceEvent reports e if tracing is enabled. Callers on hot paths should
check c.wire before building the event. traceKey reports a key event for the current auth key.(*Conn) traceMessage(dir WireDirection, key crypto.AuthKey, salt, session, msgID int64, seqNo int32, body []byte) traceRejected reports a rejected incoming message. traceRequestDone reports the result of a request. traceRequestStart reports a request that is going to be sent and returns
the start time for traceRequestDone. traceResend reports a request sent again with the same message id.(*Conn) traceSession(old, current int64)(*Conn) updateSalt()(*Conn) wireConn() WireConn write encrypts and sends a message. If service is set, msgID and seqNo are
ignored and allocated under the exchange lock.(*Conn) writeContentMessage(ctx context.Context, msgID int64, seqNo int32, message bin.Encoder) error writeServiceMessage writes a service message. Its msg_id and seqno are
allocated after the exchange lock is taken, so a message that waited for a
key exchange is numbered in the new session.
*Conn : github.com/gotd/td/tg.Invoker
*Conn : github.com/gotd/td/telegram/internal/manager.protoConn
func New(dialer Dialer, opt Options) *Conn
NewSessionHandler is implemented by a Handler that wants to know when the
server created a new session (new_session_created), e.g. to recover
updates it may have missed.( NewSessionHandler) OnNewSession(firstMsgID int64) error
*github.com/gotd/td/telegram/internal/manager.Conn
github.com/gotd/td/telegram/internal/manager.NewSessionHandler(interface)
github.com/gotd/td/telegram.primaryHandler
NewSessionHandler : github.com/gotd/td/telegram/internal/manager.NewSessionHandler
Options of Conn. AckBatchSize is maximum ack-s to buffer. AckInterval is maximum time to buffer ack. Cipher defines message crypto. Clock is current time source. Defaults to system time. CompressThreshold is a threshold in bytes to determine that message
is large enough to be compressed using GZIP.
If < 0, compression will be disabled.
If == 0, default value will be used. DC is datacenter ID for key exchange.
Defaults to 2. DialTimeout is timeout of creating connection. EnablePFS enables Perfect Forward Secrecy using temporary auth keys. ExchangeTimeout is timeout of every key exchange request. Handler will be called on received message. Key that can be used to restore previous connection. KeyCreatedAt is the creation time of the permanent key (Key, or PermKey
in PFS mode), Unix seconds; zero if unknown. It is reported back in
Session.KeyCreatedAt and used by the PFS key recovery policy. Logger is the structured logger. No logs by default. MaxRetries is max retry count until rpc request failure. MessageID is message id source. Share source between connection to
reduce collision probability. PermKey is permanent auth key for PFS mode. PingInterval is the duration between ping_delay_disconnect requests.
Zero (default) pings like Telegram Desktop: every 30–45 seconds (a
random interval in [30s, 45s]) with disconnect_delay 60. A positive
value pings at that fixed interval with disconnect_delay
PingInterval + PingTimeout. PingTimeout is the time to wait for a pong, after which the connection
is considered dead. Default is 15 seconds. PublicKeys of telegram.
If not provided, embedded public keys will be used. Random is random source. Defaults to crypto. RequestTimeout is function which returns request timeout for given type ID. RetryInterval is duration between retries. Salt from server that can be used to restore previous connection. SaltFetchInterval is the duration between get_future_salts requests.
Zero (default) never sends get_future_salts, like Telegram Desktop:
the server salt is taken from new_session_created and bad_server_salt
(a request with an expired salt is re-sent with the new one). A
positive value fetches future salts every interval, the first time
one interval after the session starts. ServerTime tracks the server time offset; share it between connections
of a client. Defaults to a new ServerTime over Clock. Message ids of the
default MessageID source and the msg_id time check use it. SessionState keeps the server session (session_id and seqno) across
reconnects of a connection slot with the same key. Nil starts a new
session on every connect. Not used in PFS mode, where every connection
has a new temporary key. TempKeyTTL is temporary auth key lifetime in seconds.
Default: 86400 (24h). Minimum: 60. Tracer for OTEL. Types map, used in verbose logging of incoming message. WireTracer observes plaintext messages and lifecycle events of the
connection. Nil (default) disables wire tracing. engine for replacing RPC engine.(*Options) setDefaultPublicKeys()(*Options) setDefaults()
func github.com/gotd/td/pool.(*SyncSession).Options(opts Options) (Options, pool.Session)
func New(dialer Dialer, opt Options) *Conn
func github.com/gotd/td/pool.(*SyncSession).Options(opts Options) (Options, pool.Session)
func github.com/gotd/td/telegram/internal/manager.CreateConn(create Dialer, mode manager.ConnMode, appID int, opts Options, connOpts manager.ConnOptions) *manager.Conn
ServerTime tracks the difference between the server clock and the local
clock, so that message ids and the msg_id time window use server time even
when the local clock is off.
Like TDLib (AuthData::update_server_time_difference), the difference is
taken from the time encoded in every received msg_id (and the server_time
of the key exchange): the first observation sets it, later ones only raise
it, since a message is always received after the server created it. A
bad_msg_notification "msg_id too high" resets it from the notification's
own msg_id.
One ServerTime is shared by all connections of a client. It is safe for
concurrent use.baseclock.Clock known reports whether offset was observed (not only seeded).muxsync.Mutex offset is server time minus local time, in nanoseconds. Known reports whether the offset was observed from the server. Now returns the current server time. Offset returns server time minus local time. Seed sets the offset, e.g. one persisted by a previous run, unless it was
already observed from the server. observe updates the offset from a server time point received now. It
reports whether the offset changed. reset sets the offset from a server time point received now, also when it
is lower than the current one (the local clock went forward or the offset
was too high).
*ServerTime : github.com/cenkalti/backoff/v4.Clock
func NewServerTime(base clock.Clock, offset time.Duration) *ServerTime
SessionState is the server session of a connection slot: session_id and
the number of content messages sent in it (for seqno). Connections that
share a SessionState one at a time continue the same server session after
a reconnect with the same auth key, so the server keeps its queued answers
and updates and does not send new_session_created, like TDLib and Telegram
Desktop do. A new session is started when the key changes.
A SessionState must be used by one connection at a time: acquire it with
TryAcquire before passing it in Options; the connection releases it when
Run returns.contentMessagesint32idint64inUseboolkeyID[8]byte lastBindAt is the time of the last successful auth.bindTempAuthKey
of the slot, Unix seconds (PFS key recovery policy).muxsync.Mutex TryAcquire marks the state as used by a connection. It reports false if
another connection uses it.(*SessionState) lastBind() int64 load returns the session of key keyID, if any. release saves the session of the connection and frees the state. A zero id
forgets the session.(*SessionState) setLastBind(at int64)
func NewSessionState() *SessionState
func github.com/gotd/td/telegram.(*Client).acquireSessionState(dc int) *SessionState
WireConn identifies the connection of a traced message or event. DC is the DC id of the connection used for key exchange
(Options.DC): 10000 is added for test DCs. ID is unique for every Conn of the process, starting from 1.
func (*Conn).wireConn() WireConn
WireDirection is the direction of a traced message. String implements fmt.Stringer.
WireDirection : fmt.Stringer
WireDirection : context.stringer
WireDirection : runtime.stringer
func (*Conn).traceMessage(dir WireDirection, key crypto.AuthKey, salt, session, msgID int64, seqNo int32, body []byte)
const WireIn
const WireOut
WireTracer observes the plaintext MTProto traffic and the lifecycle of a
connection, e.g. to record wire traces for debugging or for comparing the
client behavior with other implementations.
Callbacks are called synchronously from the connection goroutines, so
implementations must be safe for concurrent use and must return quickly.
Calls are not ordered by wire order: incoming messages are decrypted
concurrently, and outgoing messages are reported by concurrent writers
just before they are written, so a reported outgoing message may never
reach the wire if the write fails. Order by message id where needed.
The tracer never receives auth key material: only auth key ids. OnEvent is called on connection, key, session and request lifecycle
events. OnMessage is called for every encrypted message: outgoing messages
just before encryption and incoming messages after decryption and
msg_key check, before session and msg_id checks (rejected messages
are reported too, followed by a WireRejected event).
The body is the serialized message body as sent or received
(including gzip_packed and msg_container). It is only valid during
the call: the tracer must not modify or retain it, and must copy it
if needed.
httpWaiter is an optional capability of a transport.Conn that needs the
mtproto layer to drive HTTP long-polling.
The MTProto HTTP transport is request/response: to receive server-pushed
messages while idle, the client must keep an http_wait service message in
flight so the server has a response to hold open. http_wait is encrypted with
the session key, so only the mtproto layer can produce it — the transport
cannot. A transport implementing this interface (see the telegram/dcs HTTP
resolver) is detected by Conn after the handshake and handed a factory that
yields freshly-encrypted http_wait frames.
See https://core.telegram.org/mtproto/transports#http-transport. HTTPWaitParams reports the desired http_wait fields (milliseconds). StartHTTPWait starts the transport long-poll loop, using frame to build
each encrypted http_wait message. It must be non-blocking.
*github.com/gotd/td/telegram/dcs.httpConn
IDuint32Namestring LogAttr returns the type info as an inline log group.
Package-Level Functions (total 12, in which 3 are exported)
New creates new unstarted connection.
NewServerTime creates a ServerTime over the base clock (clock.System if
nil), starting with the given offset, e.g. a persisted one. The offset is
replaced by the first observed server time.
NewSessionState returns an empty SessionState.
badMsgTimeCode reports whether err is a bad_msg_notification about the
msg_id time (16, 17 or 20), after which the request can be sent again.
bindRetryDelay is the delay before bind attempt n+1 after
ENCRYPTED_MESSAGE_INVALID: a fresh permanent key may not have reached all
servers yet, so retries need time (1 s, 2 s, 4 s).
needAck reports whether a message with the given seqno is content-related
and must be acknowledged.
https://core.telegram.org/mtproto/description#message-sequence-number-msg-seqno
peekID returns the type id of an encodable message for logging, or 0 if it
cannot be determined without encoding.
vendoredKeys parses vendored file _data/public_keys.pem as list of
PEM-encoded public RSA keys.
Most recent key list can be found on https://my.telegram.org/apps.
Package-Level Variables (total 10, in which 2 are exported)
ErrPFSDropKeysRequired is returned when stored permanent key should be
dropped and generated again on the next connection attempt.
ErrPFSReconnectRequired is returned when connection should be recreated
to continue PFS flow (e.g. temp key renewal).
publicKeys is byte blob of new keys added for PQInnerData encryption (key exchange).
See https://github.com/telegramdesktop/tdesktop/commit/95a7ce4622dc24717dc5b95fc99599dddfd4ff6c.
See https://github.com/tdlib/td/commit/e9e24282378fcdb3a3ce020bee4253b65ac98213.
Package-Level Constants (total 30, in which 14 are exported)
WireConnDown is reported when the connection is closed, Err is the
reason (nil on graceful close).
WireConnStart is reported before dialing.
WireConnUp is reported when the transport connection is established.
WireDecryptFailed is reported when an incoming message can't be
decrypted or fails the msg_key check: Err.
WireIn is a message received from the server.
WireKeyCreated is reported when a new auth key is created by key
exchange: AuthKeyID, TempKey and ExpiresAt (temporary keys).
WireKeySet is reported when the connection starts using an auth key
for messages, including after the key is re-created because the server
did not find it: AuthKeyID, TempKey and ExpiresAt (temporary keys).
WireOut is a message sent by the client.
WireRejected is reported when a decrypted incoming message is
rejected: MessageID and Reason ("bad_session" or "bad_msg_id").
WireRequest is reported when a request is going to be sent:
MessageID, SeqNo and TypeID (of the encoded request, e.g. a
wrapper like invokeWithLayer).
WireRequestDone is reported when a request is finished: MessageID,
Err (nil on success, RPC or context error otherwise) and Latency.
WireRequestResend is reported when a request is re-encoded and sent
again after bad_server_salt: MessageID and Reason ("bad_server_salt").
Retransmits after an ack timeout reuse the message id and are only
visible as repeated outgoing messages.
WireSaltChange is reported when the server salt changes: Old and New.
Salts set by key exchange are implied by WireKeyCreated.
WireSessionNew is reported when the client session id changes:
Old and New.
https://core.telegram.org/mtproto/description#message-identifier-msg-id
A message is rejected over 300 seconds after it is created or 30 seconds
before it is created (this is needed to protect from replay attacks).
https://core.telegram.org/mtproto/description#message-identifier-msg-id
A message is rejected over 300 seconds after it is created or 30 seconds
before it is created (this is needed to protect from replay attacks).
maxTimeResends limits resends of one request after bad_msg_notification
about its msg_id time.
minOffsetStep is the smallest increase of the offset that is applied, as in
TDLib (1e-4 s).
Prevent obviously invalid ttl values that can break renewal math.
Ping cadence of Telegram Desktop (mtproto/session_private.cpp): the next
ping is due kPingSendAfter after the last one and is forced at
kPingSendAfterForce; ping_delay_disconnect always asks for 60 seconds.
Ping cadence of Telegram Desktop (mtproto/session_private.cpp): the next
ping is due kPingSendAfter after the last one and is forced at
kPingSendAfterForce; ping_delay_disconnect always asks for 60 seconds.
Ping cadence of Telegram Desktop (mtproto/session_private.cpp): the next
ping is due kPingSendAfter after the last one and is forced at
kPingSendAfterForce; ping_delay_disconnect always asks for 60 seconds.
slowWriteThreshold is the duration after which a single write (lock
acquisition + encrypt + transport send) is considered suspiciously slow and
logged at warning level. A blocked or slow write is the primary signature of
a half-open connection where updates are still received but requests can no
longer be issued.
The pages are generated with Goldsv0.8.7. (GOOS=linux GOARCH=amd64)
Golds is a Go 101 project developed by Tapir Liu.
PR and bug reports are welcome and can be submitted to the issue list.
Please follow @zigo_101 (reachable from the left QR code) to get the latest news of Golds.