td

Documentation

Overview

Package td implements the tdlib network transport over gotd/td's telegram.Client. It constructs the client from tdlib options, persists the MTProto session through an injected store, forwards raw updates to an injected sink, and manages the blocking Run lifecycle. It does not own the authorization state machine (RFC 0006) or update reconciliation (RFC 0013).

The package is self-contained: it depends on gotd/td and small local interfaces (Session, UpdateSink), never on the root tdlib package, so the root package can import it without an import cycle.

Index

• func AsFloodWait(err error) (d time.Duration, ok bool)
• func IsMigrate(err error) bool
• func IsPermanent(err error) bool
• func IsUnauthorized(err error) bool
• type Conn
  • func Build(opts Options) (*Conn, error)
  • func (c *Conn) API() *tg.Client
  • func (c *Conn) Close() error
  • func (c *Conn) Run(ctx context.Context) error
  • func (c *Conn) Self(ctx context.Context) (*tg.User, error)
• type Options
• type Session
• type UpdateSink

Functions

func AsFloodWait

func AsFloodWait(err error) (d time.Duration, ok bool)

AsFloodWait returns the back-off duration and true if err is a FLOOD_WAIT or FLOOD_PREMIUM_WAIT error.

func IsMigrate

func IsMigrate(err error) bool

IsMigrate reports whether err is a _MIGRATE family error (PHONE_MIGRATE, NETWORK_MIGRATE, FILE_MIGRATE, etc.). gotd/td handles DC migration transparently; this helper exists for logging and diagnostics only.

func IsPermanent

func IsPermanent(err error) bool

IsPermanent reports whether err should terminate the Run loop rather than trigger a reconnect.

func IsUnauthorized

func IsUnauthorized(err error) bool

IsUnauthorized reports whether err is a 401-class auth error. Callers use it to trigger an auth state transition (RFC 0006).

Types

type Conn

type Conn struct {
	// contains filtered or unexported fields
}

Conn is a live gotd/td connection implementing the tdlib transport. It is created with Build and driven with Run; all other methods are safe to call concurrently and block on readiness as needed.

func Build

func Build(opts Options) (*Conn, error)

Build constructs a Conn from opts but does not start the network connection. Call Run to start the connection lifecycle.

func (*Conn) API

func (c *Conn) API() *tg.Client

API returns the raw TL client for issuing MTProto RPCs. Safe for concurrent use.

func (*Conn) Close

func (c *Conn) Close() error

Close releases transport resources. Connection teardown is owned by Run via context cancellation, so there is nothing extra to release here; Close exists to satisfy the transport contract and is safe to call any time.

func (*Conn) Run

func (c *Conn) Run(ctx context.Context) error

Run starts the telegram.Client event loop and blocks until ctx is cancelled or a permanent error occurs. gotd/td owns the reconnect/backoff loop; Conn adds no second layer. An orderly shutdown (context cancelled) returns nil.

func (*Conn) Self

func (c *Conn) Self(ctx context.Context) (*tg.User, error)

Self blocks until the first successful connection, then returns the authorized user. It returns a wrapped context error if ctx is cancelled first.

type Options

type Options struct {
	// AppID and AppHash are the Telegram application credentials (mandatory).
	AppID   int
	AppHash string

	// DeviceModel, SystemVersion and AppVersion are reported in initConnection.
	DeviceModel   string
	SystemVersion string
	AppVersion    string

	// TestDC selects the Telegram test DC list when true.
	TestDC bool

	// Session persists the MTProto session blob (mandatory).
	Session Session
	// Updates receives raw update batches from the network layer (mandatory).
	Updates UpdateSink

	// Logger is the tdlib logger; no-op when nil. gotd/td's own internal logging
	// is left disabled.
	Logger log.Logger
	// TracerProvider instruments RPC calls; defaults to the OTEL no-op provider.
	TracerProvider trace.TracerProvider

	// Middlewares wrap every outgoing RPC, e.g. a flood-wait waiter.
	Middlewares []telegram.Middleware

	// OnSelfSuccess and OnSelfError are the auth seam (RFC 0006); they map
	// directly onto the telegram.Options callbacks of the same name.
	OnSelfSuccess func(self *tg.User)
	OnSelfError   func(ctx context.Context, err error) error
}

Options configures a Conn.

type Session

type Session interface {
	Load(ctx context.Context) ([]byte, error)
	Store(ctx context.Context, data []byte) error
}

Session is the minimal MTProto-session blob store Conn needs. It is satisfied by an adapter in the root package over the SQLite key-value store. Load returns (nil, nil) when no session has been persisted yet.

type UpdateSink

type UpdateSink interface {
	Handle(ctx context.Context, u tg.UpdatesClass) error
}

UpdateSink receives raw, unreconciled update batches from the network layer. Its signature mirrors telegram.UpdateHandler; the reconciliation engine (RFC 0013) implements it. Handle must not block.