package telegram

Import Path
	github.com/gotd/td/telegram (on go.dev)

Dependency Relation
	imports 41 packages, and imported by 0 packages

Involved Source Files

	    auth.go
	    bot.go
	    builder.go
	    cdn.go
	    cfg.go
	    client.go
	    compat.go
	    conn_builder.go
	    connect.go
	    device.go
	  d doc.go
		Package telegram implements Telegram client.

	    flood_wait.go
	    handle_updates.go
	    invoke.go
	    middleware.go
	    migrate_to_dc.go
	    options.go
	    ping.go
	    pool.go
	    rand_int64.go
	    self.go
	    send_message.go
	    session.go
	    sub_conns.go
	    transfer.go
	    typemap.go
Package-Level Type Names (total 17, in which 13 are exported)

	/* sort exporteds by: alphabet | popularity */
	 type Client (struct)
		Client represents a MTProto client to Telegram.

		Fields (total 35, none are exported)
			/* 35 unexporteds ... *//* 35 unexporteds: */
			appHash string
				// immutable

			appID int
				Client config.
				// immutable

			cancel context.CancelFunc
			cfg *manager.AtomicConfig
			clock clock.Clock
				// immutable

			conn clientConn
			connBackoff func() backoff.BackOff
				// immutable

			connMux sync.Mutex
			connsCounter atomic.Int64
			create connConstructor
				Connection factory fields.
				// immutable

			ctx context.Context
				Client context. Will be canceled by Run on exit.

			defaultMode manager.ConnMode
				// immutable

			device DeviceConfig
				Telegram device information.
				// immutable

			domains map[int]string
				DCList state.
				Domain list (for websocket)
				// immutable

			invoker tg.Invoker
				invoker implements tg.Invoker on top of Client and mw.
				// immutable

			log *zap.Logger
				// immutable

			migration chan struct{}
			migrationTimeout time.Duration
				Migration state.
				// immutable

			mw []Middleware
				mw is list of middlewares used in invoker, can be blank.
				// immutable

			noUpdatesMode bool
				Denotes that no update mode is enabled.
				// immutable

			opts mtproto.Options
				MTProto options.
				// immutable

			rand io.Reader
				Wrappers for external world, like logs or PRNG.
				// immutable

			ready *tdsync.ResetReady
				Ready signal channel, sends signal when client connection is ready.
				Resets on reconnect.
				// immutable

			resolver dcs.Resolver
				// immutable

			restart chan struct{}
				Restart signal channel.
				// immutable

			session *pool.SyncSession
				Connection state. Guarded by connMux.

			sessions map[int]*pool.SyncSession
			sessionsMux sync.Mutex
			storage clientStorage
				Session storage.
				// immutable, nillable

			subConns map[int]CloseInvoker
				Connections to non-primary DC.

			subConnsMux sync.Mutex
			testDC bool
				Denotes to use Test DCs.
				// immutable

			tg *tg.Client
				tg provides RPC calls via Client. Uses invoker below.
				// immutable

			tracer trace.Tracer
				Tracing.

			updateHandler UpdateHandler
				Telegram updates handler.
				// immutable

		Methods (total 42, in which 14 are exported)
			(*Client) API() *tg.Client
				API returns *tg.Client for calling raw MTProto methods.

			(*Client) Auth() *auth.Client
				Auth returns auth client.

			(*Client) Config() tg.Config
				Config returns current config.

			(*Client) DC(ctx context.Context, dc int, max int64) (CloseInvoker, error)
				DC creates new multi-connection invoker to given DC.

			(*Client) Invoke(ctx context.Context, input bin.Encoder, output bin.Decoder) error
				Invoke invokes raw MTProto RPC method. It sends input and decodes result
				into output.

			(*Client) MediaOnly(ctx context.Context, dc int, max int64) (CloseInvoker, error)
				MediaOnly creates new multi-connection invoker to given DC ID.
				It connects to MediaOnly DCs.

			(*Client) MigrateTo(ctx context.Context, dcID int) error
				MigrateTo forces client to migrate to another DC.

			(*Client) Ping(ctx context.Context) error
				Ping sends low level ping request to Telegram server.

			(*Client) Pool(max int64) (CloseInvoker, error)
				Pool creates new multi-connection invoker to current DC.

			(*Client) QR() qrlogin.QR
				QR returns QR login helper.

			(*Client) RandInt64() (int64, error)
				RandInt64 returns new random int64 from random source.
				
				Useful helper for places in API where random int is required.

			(*Client) Run(ctx context.Context, f func(ctx context.Context) error) (err error)
				Run starts client session and blocks until connection close.
				The f callback is called on successful session initialization and Run
				will return on f() result.
				
				Context of callback will be canceled if fatal error is detected.
				The ctx is used for background operations like updates handling or pools.
				
				See `examples/bg-run` and `contrib/gb` package for classic approach without
				explicit callback, with Connect and defer close().

			(*Client) Self(ctx context.Context) (*tg.User, error)
				Self returns current user.
				
				You can use tg.User.Bot to check whether current user is bot.

			(*Client) SendMessage(ctx context.Context, req *tg.MessagesSendMessageRequest) error
				SendMessage sends message to peer.
				
				Deprecated: use helpers like message.NewSender.

			/* 28 unexporteds ... *//* 28 unexporteds: */
			(*Client) asHandler() manager.Handler
			(*Client) createConn(id int64, mode manager.ConnMode, setup manager.SetupCallback) pool.Conn
			(*Client) createPool(dc int, max int64, creator func() pool.Conn) (*pool.DC, error)
			(*Client) createPrimaryConn(setup manager.SetupCallback) pool.Conn
			(*Client) dc(ctx context.Context, dcID int, max int64, dialer mtproto.Dialer) (*pool.DC, error)
			(*Client) dcList() dcs.List
			(*Client) ensureRestart(ctx context.Context) error
			(*Client) exportAuth(ctx context.Context, dcID int) (*tg.AuthExportedAuthorization, error)
			(*Client) fetchConfig(ctx context.Context)
			(*Client) handleUpdates(b *bin.Buffer) error
			(*Client) init()
				init sets fields which needs explicit initialization, like maps or channels.

			(*Client) invokeConn(ctx context.Context, input bin.Encoder, output bin.Decoder) error
				invokeConn directly invokes RPC call on primary connection without any
				additional handling.

			(*Client) invokeDirect(ctx context.Context, input bin.Encoder, output bin.Decoder) error
				invokeDirect directly invokes RPC method, automatically handling datacenter redirects.

			(*Client) invokeMigrate(ctx context.Context, dcID int, input bin.Encoder, output bin.Decoder) error
			(*Client) invokeSub(ctx context.Context, dc int, input bin.Encoder, output bin.Decoder) error
			(*Client) isPermanentError(err error) bool
			(*Client) migrateToDc(ctx context.Context, dcID int) error
			(*Client) onReady()
			(*Client) onSession(cfg tg.Config, s mtproto.Session) error
			(*Client) primaryDC(dc int) mtproto.Dialer
			(*Client) processUpdates(updates tg.UpdatesClass) error
			(*Client) reconnectUntilClosed(ctx context.Context) error
			(*Client) resetReady()
			(*Client) restoreConnection(ctx context.Context) error
			(*Client) runUntilRestart(ctx context.Context) error
			(*Client) saveSession(cfg tg.Config, s mtproto.Session) error
			(*Client) transfer(ctx context.Context, to *tg.Client, dc int) (tg.AuthAuthorizationClass, error)
				transfer exports current authorization and imports it to another DC.
				See https://core.telegram.org/api/datacenter#authorization-transfer.

			(*Client) updateInterceptor(updates ...tg.UpdateClass)
		Implements (at least 2, in which 1 is exported)
			*Client : github.com/gotd/td/tg.Invoker
			/* at least one unexported ... *//* at least one unexported: */
			*Client : github.com/gotd/td/telegram/internal/manager.protoConn
		As Outputs Of (at least 2, both are exported)
			func ClientFromEnvironment(opts Options) (*Client, error)
			func NewClient(appID int, appHash string, opt Options) *Client
		As Inputs Of (at least one exported)
			func RunUntilCanceled(ctx context.Context, client *Client) error

	 type CloseInvoker (interface)
		CloseInvoker is a closeable tg.Invoker.

		Methods (total 2, both are exported)
			( CloseInvoker) Close() error
			( CloseInvoker) Invoke(ctx context.Context, input bin.Encoder, output bin.Decoder) error
		Implemented By (at least one exported)
			*github.com/gotd/td/internal/pool.DC
		Implements (at least 2, both are exported)
			 CloseInvoker : github.com/gotd/td/tg.Invoker
			 CloseInvoker : io.Closer
		As Outputs Of (at least 3, all are exported)
			func (*Client).DC(ctx context.Context, dc int, max int64) (CloseInvoker, error)
			func (*Client).MediaOnly(ctx context.Context, dc int, max int64) (CloseInvoker, error)
			func (*Client).Pool(max int64) (CloseInvoker, error)

	 type DeviceConfig = manager.DeviceConfig (struct)
		DeviceConfig is config which send when Telegram connection session created.

	 type Error = tgerr.Error (struct)
		Error represents RPC error returned to request.

	 type FileSessionStorage = session.FileStorage (struct)
		FileSessionStorage is alias of mtproto.FileSessionStorage.

	 type InvokeFunc (func)
		InvokeFunc implements tg.Invoker as function.

		Methods (only one, which is exported)
			( InvokeFunc) Invoke(ctx context.Context, input bin.Encoder, output bin.Decoder) error
				Invoke implements tg.Invoker.

		Implements (at least one exported)
			 InvokeFunc : github.com/gotd/td/tg.Invoker
		As Outputs Of (at least 2, both are exported)
			func Middleware.Handle(next tg.Invoker) InvokeFunc
			func MiddlewareFunc.Handle(next tg.Invoker) InvokeFunc

	 type Middleware (interface)
		Middleware returns new InvokeFunc for next invoker.

		Methods (only one, which is exported)
			( Middleware) Handle(next tg.Invoker) InvokeFunc
		Implemented By (at least one exported)
			 MiddlewareFunc
		As Inputs Of (at least one unexported)
			/* at least one unexported ... *//* at least one unexported: */
			func chainMiddlewares(invoker tg.Invoker, chain ...Middleware) tg.Invoker

	 type MiddlewareFunc (func)
		MiddlewareFunc implements Middleware as function.

		Methods (only one, which is exported)
			( MiddlewareFunc) Handle(next tg.Invoker) InvokeFunc
				Handle implements Middleware.

		Implements (at least one exported)
			 MiddlewareFunc : Middleware

	 type Options (struct)
		Options of Client.

		Fields (total 23, all are exported)
			AckBatchSize int
				AckBatchSize is limit of MTProto ACK buffer size.

			AckInterval time.Duration
				AckInterval is maximum time to buffer MTProto ACK.

			Clock clock.Clock
			CompressThreshold int
				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 int
				DC ID to connect.
				
				If not provided, 2 will be used by default.

			DCList dcs.List
				DCList is initial list of addresses to connect.

			Device DeviceConfig
				Device is device config.
				Will be sent with session creation request.

			DialTimeout time.Duration
				DialTimeout is timeout of creating connection.

			ExchangeTimeout time.Duration
				ExchangeTimeout is timeout of every key exchange request.

			Logger *zap.Logger
				Logger is instance of zap.Logger. No logs by default.

			MaxRetries int
				MaxRetries is limit of send retries.

			MessageID mtproto.MessageIDSource
			Middlewares []Middleware
				Middlewares list allows wrapping tg.Invoker. Can be useful for metrics,
				tracing, etc. Note that order is important, see ExampleMiddleware.
				
				Middlewares are called in order from first to last.

			MigrationTimeout time.Duration
				MigrationTimeout configures migration timeout.

			NoUpdates bool
				NoUpdates enables no updates mode.
				
				Enabled by default if no UpdateHandler is provided.

			PublicKeys []PublicKey
				PublicKeys of telegram.
				
				If not provided, embedded public keys will be used.

			Random io.Reader
				Random is random source. Defaults to crypto.

			ReconnectionBackoff func() backoff.BackOff
				ReconnectionBackoff configures and returns reconnection backoff object.

			Resolver dcs.Resolver
				Resolver to use.

			RetryInterval time.Duration
				RetryInterval is duration between send retries.

			SessionStorage SessionStorage
				SessionStorage will be used to load and save session data.
				NB: Very sensitive data, save with care.

			TracerProvider trace.TracerProvider
				OpenTelemetry.

			UpdateHandler UpdateHandler
				UpdateHandler will be called on received update.

		Methods (only one, which is unexported)
			/* one unexported ... *//* one unexported: */
			(*Options) setDefaults()
		As Outputs Of (at least one exported)
			func OptionsFromEnvironment(opts Options) (Options, error)
		As Inputs Of (at least 5, all are exported)
			func BotFromEnvironment(ctx context.Context, opts Options, setup func(ctx context.Context, client *Client) error, cb func(ctx context.Context, client *Client) error) error
			func ClientFromEnvironment(opts Options) (*Client, error)
			func NewClient(appID int, appHash string, opt Options) *Client
			func OptionsFromEnvironment(opts Options) (Options, error)
			func TestClient(ctx context.Context, opts Options, cb func(ctx context.Context, client *Client) error) error

	 type PublicKey = exchange.PublicKey (struct)
		PublicKey is a Telegram server public key.

	 type SessionStorage = session.Storage (interface)
		SessionStorage is alias of mtproto.SessionStorage.

	 type UpdateHandler (interface)
		UpdateHandler will be called on received updates from Telegram.

		Methods (only one, which is exported)
			( UpdateHandler) Handle(ctx context.Context, u tg.UpdatesClass) error
		Implemented By (at least 2, both are exported)
			 UpdateHandlerFunc
			 github.com/gotd/td/tg.UpdateDispatcher

	 type UpdateHandlerFunc (func)
		UpdateHandlerFunc type is an adapter to allow the use of
		ordinary function as update handler.
		
		UpdateHandlerFunc(f) is an UpdateHandler that calls f.

		Methods (only one, which is exported)
			( UpdateHandlerFunc) Handle(ctx context.Context, u tg.UpdatesClass) error
				Handle calls f(ctx, u)

		Implements (at least one exported)
			 UpdateHandlerFunc : UpdateHandler

	/* 4 unexporteds ... *//* 4 unexporteds: */
	 type clientConn (interface)

		Methods (total 3, all are exported)
			( clientConn) Invoke(ctx context.Context, input bin.Encoder, output bin.Decoder) error
			( clientConn) Ping(ctx context.Context) error
			( clientConn) Run(ctx context.Context) error
		Implemented By (at least 3, in which 2 are exported)
			*github.com/gotd/td/telegram/internal/manager.Conn
			 github.com/gotd/td/internal/pool.Conn (interface)
			/* at least one unexported ... *//* at least one unexported: */
			 github.com/gotd/td/internal/pool.poolConn
		Implements (at least one exported)
			 clientConn : github.com/gotd/td/tg.Invoker

	 type clientHandler (struct)

		Fields (only one, which is unexported)
			/* one unexported ... *//* one unexported: */
			client *Client
		Methods (total 2, both are exported)
			( clientHandler) OnMessage(b *bin.Buffer) error
			( clientHandler) OnSession(cfg tg.Config, s mtproto.Session) error
		Implements (at least one exported)
			 clientHandler : github.com/gotd/td/telegram/internal/manager.Handler

	 type clientStorage (interface)

		Methods (total 2, both are exported)
			( clientStorage) Load(ctx context.Context) (*session.Data, error)
			( clientStorage) Save(ctx context.Context, data *session.Data) error
		Implemented By (at least one exported)
			*github.com/gotd/td/session.Loader

	 type connConstructor (func)

		As Outputs Of (at least one unexported)
			/* at least one unexported ... *//* at least one unexported: */
			func defaultConstructor() connConstructor


Package-Level Functions (total 13, in which 6 are exported)

	 func BotFromEnvironment(ctx context.Context, opts Options, setup func(ctx context.Context, client *Client) error, cb func(ctx context.Context, client *Client) error) error
		BotFromEnvironment creates bot client using ClientFromEnvironment
		connects to server and authenticates it.
		
		Variables:
		BOT_TOKEN — token from BotFather.

	 func ClientFromEnvironment(opts Options) (*Client, error)
		ClientFromEnvironment creates client using OptionsFromEnvironment
		but does not connect to server.
		
		Variables:
		
			APP_ID:   app_id of Telegram app.
			APP_HASH: app_hash of Telegram app.

	 func NewClient(appID int, appHash string, opt Options) *Client
		NewClient creates new unstarted client.

	 func OptionsFromEnvironment(opts Options) (Options, error)
		OptionsFromEnvironment fills unfilled field in opts parameter
		using environment variables.
		
		Variables:
		
			SESSION_FILE:        path to session file
			SESSION_DIR:         path to session directory, if SESSION_FILE is not set
			ALL_PROXY, NO_PROXY: see https://pkg.go.dev/golang.org/x/net/proxy#FromEnvironment

	 func RunUntilCanceled(ctx context.Context, client *Client) error
		RunUntilCanceled is client callback which
		locks until client context is canceled.

	 func TestClient(ctx context.Context, opts Options, cb func(ctx context.Context, client *Client) error) error
		TestClient creates and authenticates user telegram.Client
		using Telegram test server.

	/* 7 unexporteds ... *//* 7 unexporteds: */
	 func chainMiddlewares(invoker tg.Invoker, chain ...Middleware) tg.Invoker
		chainMiddlewares composes new invoker in such order that first element in
		chain is called first, and latest "next" argument will be "invoker".
		
		E.g. we have invoker and two middlewares, so order will be following:
		0, 1, (invoker), 1 (after "next"), 0 (after "next").
		
		See TestMiddlewareOrder or ExampleMiddleware.

	 func defaultBackoff(c clock.Clock) func() backoff.BackOff
	 func defaultConstructor() connConstructor
	 func getTypesMapping() *tmap.Map
	 func parseCDNKeys(keys ...tg.CDNPublicKey) ([]*rsa.PublicKey, error)
	 func retry(ctx context.Context, logger *zap.Logger, cb func(ctx context.Context) error) error
	 func sessionDir() (string, error)
Package-Level Variables (total 3, in which 1 is exported)

	  var AsFloodWait func(err error) (d time.Duration, ok bool)
		AsFloodWait returns wait duration and true boolean if err is
		the "FLOOD_WAIT" error.
		
		Client should wait for that duration before issuing new requests with
		same method.

	/* 2 unexporteds ... *//* 2 unexporteds: */
	  var typesMap *tmap.Map
	  var typesOnce sync.Once
Package-Level Constants (total 6, all are exported)

	const AddrProduction = "149.154.167.50:443"
		Available MTProto default server addresses.
		
		See https://my.telegram.org/apps.

	const AddrTest = "149.154.167.40:443"
		Available MTProto default server addresses.
		
		See https://my.telegram.org/apps.

	const ErrFloodWait = "FLOOD_WAIT"
		ErrFloodWait is error type of "FLOOD_WAIT" error.

	const Port = 443
		Port is default port used by telegram.

	const TestAppHash = "344583e45741c457fe1862106095a5eb"
		Test-only credentials. Can be used with AddrTest and TestAuth to
		test authentication.
		
		Reference:
		  - https://github.com/telegramdesktop/tdesktop/blob/5f665b8ecb48802cd13cfb48ec834b946459274a/docs/api_credentials.md

	const TestAppID = 17349
		Test-only credentials. Can be used with AddrTest and TestAuth to
		test authentication.
		
		Reference:
		  - https://github.com/telegramdesktop/tdesktop/blob/5f665b8ecb48802cd13cfb48ec834b946459274a/docs/api_credentials.md

The pages are generated with Golds v0.6.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 @Go100and1 (reachable from the left QR code) to get the latest news of Golds.