td

package module
v0.0.0-...-f756a1e Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Jun 26, 2023 License: MIT Imports: 0 Imported by: 0

README

td Go Reference codecov beta

A fast Telegram client in pure Go.

Before using this library, read How To Not Get Banned guide.

Due to limitations of pkg.go.dev, documentation for tg package is not shown, but there is hosted version.

Higher level libraries

The gotd itself is a pretty low-level library, and you may want to use higher level libraries instead:

  • GoTGProto is a helper package for gotd library, It aims to make td's raw functions easy-to-use with the help of features like using session strings, custom helper functions, storing peers and extracting chat or user ids through it etc.

Usage

go get github.com/gotd/td
package main

import (
	"context"

	"github.com/gotd/td/telegram"
)

func main() {
	// https://core.telegram.org/api/obtaining_api_id
	client := telegram.NewClient(appID, appHash, telegram.Options{})
	if err := client.Run(context.Background(), func(ctx context.Context) error {
		// It is only valid to use client while this function is not returned
		// and ctx is not cancelled.
		api := client.API()

		// Now you can invoke MTProto RPC requests by calling the API.
		// ...

		// Return to close client connection and free up resources.
		return nil
	}); err != nil {
		panic(err)
	}
	// Client is closed.
}

See examples for more info.

Features

  • Full MTProto 2.0 implementation in Golang, directly access any MTProto method with telegram.Client.API()
  • Highly optimized, low memory (150kb per idle client) and CPU overhead, can handle thousands concurrent clients
  • Code for Telegram types generated by ./cmd/gotdgen (based on gotd/tl parser) with embedded official documentation
  • Pluggable session storage
  • Automatic re-connects with keepalive
  • Vendored Telegram public keys that are kept up-to-date
  • Rigorously tested
    • End-to-end with real Telegram server in CI
    • End-to-end with gotd Telegram server (in pure Go)
    • Lots of unit testing
    • Fuzzing
    • 24/7 canary bot in production that tests reconnects, update handling, memory leaks and performance
  • No runtime reflection overhead
  • Conforms to Security guidelines for Telegram client software developers
    • Secure PRNG used for crypto
    • Replay attack protection
  • 2FA support
  • MTProxy support
  • Various helpers that lighten the complexity of the Telegram API
  • Connection pooling
  • Automatic datacenter migration and redirects handling
  • Graceful request cancellation via context
  • WebSocket transport support (works in WASM)

Status

The goal of this project is to implement a stable, performant and safe client for Telegram in pure Go while having a simple and convenient API and a feature parity with TDLib.

This project is fully non-commercial and not affiliated with any commercial organization (including Telegram LLC).

Examples

See examples directory.

Also take a look at

  • go-faster/bot as example of sophisticated telegram bot integration with GitHub
  • gotd/cli, command line interface for subset of telegram methods.
Auth
User

You can use td/telegram/auth.Flow to simplify user authentications.

codePrompt := func(ctx context.Context, sentCode *tg.AuthSentCode) (string, error) {
    // NB: Use "golang.org/x/crypto/ssh/terminal" to prompt password.
    fmt.Print("Enter code: ")
    code, err := bufio.NewReader(os.Stdin).ReadString('\n')
    if err != nil {
        return "", err
    }
    return strings.TrimSpace(code), nil
}
// This will setup and perform authentication flow.
// If account does not require 2FA password, use telegram.CodeOnlyAuth
// instead of telegram.ConstantAuth.
if err := auth.NewFlow(
    auth.Constant(phone, password, auth.CodeAuthenticatorFunc(codePrompt)),
    auth.SendCodeOptions{},
).Run(ctx, client.Auth()); err != nil {
    panic(err)
}
Bot

Use bot token from @BotFather.

if err := client.Auth().Bot(ctx, "token:12345"); err != nil {
    panic(err)
}
Calling MTProto directly

You can use the generated tg.Client that allows calling any MTProto method directly.

// Grab these from https://my.telegram.org/apps.
// Never share it or hardcode!
client := telegram.NewClient(appID, appHash, telegram.Options{})
client.Run(ctx, func(ctx context.Context) error {
  // Grab token from @BotFather.
  if _, err := client.Auth().Bot(ctx, "token:12345"); err != nil {
    return err
  }
  state, err := client.API().UpdatesGetState(ctx)
  if err != nil {
    return err
  }
  // Got state: &{Pts:197 Qts:0 Date:1606855030 Seq:1 UnreadCount:106}
  // This will close client and cleanup resources.
  return nil
})
Generated code

The code output of gotdgen contains references to TL types, examples, URL to official documentation and extracted comments from it.

For example, the auth.Authorization type in tg/tl_auth_authorization_gen.go:

// AuthAuthorizationClass represents auth.Authorization generic type.
//
// See https://core.telegram.org/type/auth.Authorization for reference.
//
// Example:
//  g, err := DecodeAuthAuthorization(buf)
//  if err != nil {
//      panic(err)
//  }
//  switch v := g.(type) {
//  case *AuthAuthorization: // auth.authorization#cd050916
//  case *AuthAuthorizationSignUpRequired: // auth.authorizationSignUpRequired#44747e9a
//  default: panic(v)
//  }
type AuthAuthorizationClass interface {
	bin.Encoder
	bin.Decoder
	construct() AuthAuthorizationClass
}

Also, the corresponding auth.signIn method:

// AuthSignIn invokes method auth.signIn#bcd51581 returning error if any.
// Signs in a user with a validated phone number.
//
// See https://core.telegram.org/method/auth.signIn for reference.
func (c *Client) AuthSignIn(ctx context.Context, request *AuthSignInRequest) (AuthAuthorizationClass, error) {}

The generated constructors contain detailed official documentation, including links:

// FoldersDeleteFolderRequest represents TL type `folders.deleteFolder#1c295881`.
// Delete a peer folder¹
//
// Links:
//  1) https://core.telegram.org/api/folders#peer-folders
//
// See https://core.telegram.org/method/folders.deleteFolder for reference.
type FoldersDeleteFolderRequest struct {
    // Peer folder ID, for more info click here¹
    //
    // Links:
    //  1) https://core.telegram.org/api/folders#peer-folders
    FolderID int
}

Contributions

Huge thanks to all contributors. Dealing with a project of this scale alone is impossible.

Special thanks:

  • tdakkota
    • Two-factor authentication (SRP)
    • Proxy support
    • Update dispatcher
    • Complete transport support (abridged, padded intermediate and full)
    • Telegram server for end-to-end testing
    • Multiple major refactorings, including critical cryptographical scope reduction
    • Code generation improvements (vector support, multiple modes for pretty-print)
    • And many other cool things and performance improvements
  • shadowspore
    • Background pings
    • Links in generated documentation
    • Message acknowledgements
    • Retries
    • RPC Engine
    • Gap (Updates) engine

Reference

The MTProto protocol description is hosted by Telegram.

Most important parts for client implementations:

Current implementation mostly conforms to security guidelines, but no formal security audit were performed.

Prior art

Who is using gotd?

Drop a comment here to add your project.

License

MIT License

Created by Aleksandr (ernado) Razumov

2020

Documentation

Overview

Package td implements MTProto encoding and decoding.

Directories

Path Synopsis
Package bin implements binary serialization and deserialization for TL, providing Buffer that can decode and encode basic Type Language types.
Package bin implements binary serialization and deserialization for TL, providing Buffer that can decode and encode basic Type Language types.
Package clock abstracts time source.
Package clock abstracts time source.
cmd
dlkey
Binary dlkey extracts public keys from remote repo.
Binary dlkey extracts public keys from remote repo.
dltl
Binary dltl fetches .tl schema from remote repo.
Binary dltl fetches .tl schema from remote repo.
gotdchats
Binary gotdchats implements chat list request example using testing server.
Binary gotdchats implements chat list request example using testing server.
gotdecho
Binary gotdecho provides example of Telegram echo bot.
Binary gotdecho provides example of Telegram echo bot.
gotdgen
Binary gotdgen generates go source code from TL schema.
Binary gotdgen generates go source code from TL schema.
mtprint
Binary mtprint pretty-prints MTProto message from binary file.
Binary mtprint pretty-prints MTProto message from binary file.
rsagen
The rsagen command generates rsa.PublicKey variables from PEM-encoded RSA public keys.
The rsagen command generates rsa.PublicKey variables from PEM-encoded RSA public keys.
Package constant wraps Telegram-defined constants.
Package constant wraps Telegram-defined constants.
examples module
Package fileid contains BotAPI and tdlib file_id decoder.
Package fileid contains BotAPI and tdlib file_id decoder.
Package gorules contains ruleguard linter rules.
Package gorules contains ruleguard linter rules.
Package internal contains unexported implementation details of Telegram client.
Package internal contains unexported implementation details of Telegram client.
ascii
Package ascii provides data and functions to test some properties of ASCII code points.
Package ascii provides data and functions to test some properties of ASCII code points.
crypto
Package crypto implements cryptographical primitives for MTproto.
Package crypto implements cryptographical primitives for MTproto.
crypto/srp
Package srp contains implementation of Secure Remote Password protocol.
Package srp contains implementation of Secure Remote Password protocol.
exchange
Package exchange contains Telegram key exchange algorithm flows.
Package exchange contains Telegram key exchange algorithm flows.
gen
Package gen implements code generation from TL schema.
Package gen implements code generation from TL schema.
gen/example
Package td contains generated code from example schema and is used for codegen testing.
Package td contains generated code from example schema and is used for codegen testing.
keyparser
Package keyparser extracts public keys from code.
Package keyparser extracts public keys from code.
mt
Package mt contains generated code based on mtproto schema.
Package mt contains generated code based on mtproto schema.
mtproto
Package mtproto implements MTProto connection.
Package mtproto implements MTProto connection.
mtproto/salts
Package salts contains MTProto server salt storage.
Package salts contains MTProto server salt storage.
mtproxy
Package mtproxy contains MTProxy transport implementations.
Package mtproxy contains MTProxy transport implementations.
mtproxy/faketls
Package faketls contains faketls implementation.
Package faketls contains faketls implementation.
mtproxy/obfuscated2
Package obfuscated2 contains obfuscated2 implementation.
Package obfuscated2 contains obfuscated2 implementation.
mtproxy/obfuscator
Package obfuscator contains some MTProxy obfuscation utilities.
Package obfuscator contains some MTProxy obfuscation utilities.
pool
Package pool contains Telegram connections pool.
Package pool contains Telegram connections pool.
proto
Package proto implements MTProto 2.0 primitives.
Package proto implements MTProto 2.0 primitives.
proto/codec
Package codec contains MTProto transport encoding implementations.
Package codec contains MTProto transport encoding implementations.
rpc
Package rpc implements rpc engine.
Package rpc implements rpc engine.
syncio
Package syncio contains synchronized wrappers for interfaces from io package.
Package syncio contains synchronized wrappers for interfaces from io package.
tdsync
Package tdsync contains some useful synchronization utilities.
Package tdsync contains some useful synchronization utilities.
testutil
Package testutil wraps helpers for testing.
Package testutil wraps helpers for testing.
tmap
Package tmap provides type mapping facility that maps type id to type name.
Package tmap provides type mapping facility that maps type id to type name.
wsutil
Package wsutil contains some Websocket utilities.
Package wsutil contains some Websocket utilities.
Package oteltg provide OpenTelemetry instrumentation for gotd.
Package oteltg provide OpenTelemetry instrumentation for gotd.
Package session implements session storage.
Package session implements session storage.
tdesktop
Package tdesktop contains Telegram Desktop session decoder.
Package tdesktop contains Telegram Desktop session decoder.
Package tdjson contains some helpers to use jx with TL objects.
Package tdjson contains some helpers to use jx with TL objects.
tdp
Package tdp is td pretty-printing and formatting facilities for types from MTProto.
Package tdp is td pretty-printing and formatting facilities for types from MTProto.
internal
Package internal wraps internal packages for tdp package.
Package internal wraps internal packages for tdp package.
Package telegram implements Telegram client.
Package telegram implements Telegram client.
auth
Package auth provides authentication on top of tg.Client.
Package auth provides authentication on top of tg.Client.
auth/qrlogin
Package qrlogin provides QR login flow implementation.
Package qrlogin provides QR login flow implementation.
dcs
Package dcs contains Telegram DCs list and some helpers.
Package dcs contains Telegram DCs list and some helpers.
downloader
Package downloader contains downloading files helpers.
Package downloader contains downloading files helpers.
internal/deeplink
Package deeplink contains deeplink parsing helpers.
Package deeplink contains deeplink parsing helpers.
internal/e2etest
Package e2etest contains some helpers to make external E2E tests using Telegram test server.
Package e2etest contains some helpers to make external E2E tests using Telegram test server.
internal/manager
Package manager contains connection management utilities.
Package manager contains connection management utilities.
internal/upconv
Package upconv contains updates conversion helpers.
Package upconv contains updates conversion helpers.
internal/version
Package version contains gotd module version getter.
Package version contains gotd module version getter.
message
Package message contains some useful utilities for creating Telegram messages.
Package message contains some useful utilities for creating Telegram messages.
message/entity
Package entity contains message formatting and styling helpers.
Package entity contains message formatting and styling helpers.
message/html
Package html contains HTML styling options.
Package html contains HTML styling options.
message/inline
Package inline contains inline query results builder.
Package inline contains inline query results builder.
message/internal/mkrun
Package mkrun contains some helpers for generation scripts.
Package mkrun contains some helpers for generation scripts.
message/internal/mktyping
Binary mktyping generates TypingActionBuilder.
Binary mktyping generates TypingActionBuilder.
message/markup
Package markup contain bots inline markup builder.
Package markup contain bots inline markup builder.
message/peer
Package peer conatains some peer resolving and extracting helpers.
Package peer conatains some peer resolving and extracting helpers.
message/styling
Package styling contains styling options for Telegram messages.
Package styling contains styling options for Telegram messages.
message/unpack
Package unpack contains some updates result unpacking helpers.
Package unpack contains some updates result unpacking helpers.
peers
Package peers contains helpers to work with Telegram peers.
Package peers contains helpers to work with Telegram peers.
peers/members
Package members defines interfaces for working with chat/channel members.
Package members defines interfaces for working with chat/channel members.
query
Package query contains generic pagination helpers.
Package query contains generic pagination helpers.
query/cached
Package cached contains cached query helpers.
Package cached contains cached query helpers.
query/channels/participants
Package participants contains channel participants iteration helper.
Package participants contains channel participants iteration helper.
query/contacts/blocked
Package blocked contains blocked contacts iteration helper.
Package blocked contains blocked contacts iteration helper.
query/dialogs
Package dialogs contains dialog iteration helper.
Package dialogs contains dialog iteration helper.
query/hasher
Package hasher contains Telegram pagination hash implementation.
Package hasher contains Telegram pagination hash implementation.
query/internal/genutil
Package genutil is a utility package for query helpers codegeneration.
Package genutil is a utility package for query helpers codegeneration.
query/messages
Package messages contains message iteration helper.
Package messages contains message iteration helper.
query/messages/stickers/featured
Package featured contains featured stickers iteration helper.
Package featured contains featured stickers iteration helper.
query/photos
Package photos contains photos iteration helper.
Package photos contains photos iteration helper.
thumbnail
Package thumbnail implements expanding of stripped telegram thumbnails.
Package thumbnail implements expanding of stripped telegram thumbnails.
tljson
Package tljson contains some helpers to work with JSONValue class.
Package tljson contains some helpers to work with JSONValue class.
updates
Package updates provides a Telegram's internalState synchronization manager.
Package updates provides a Telegram's internalState synchronization manager.
updates/hook
Package hook contains telegram update hook middleware.
Package hook contains telegram update hook middleware.
updates/internal/e2e
Package e2e contains end-to-end updates processing test.
Package e2e contains end-to-end updates processing test.
uploader
Package uploader contains uploading files helpers.
Package uploader contains uploading files helpers.
uploader/source
Package source contains remote source interface and implementations for uploader.
Package source contains remote source interface and implementations for uploader.
tg
Package tg contains generated types from MTProto Telegram API.
Package tg contains generated types from MTProto Telegram API.
e2e
Package e2e implements MTProto encoding and decoding.
Package e2e implements MTProto encoding and decoding.
Package tgerr implements helpers for error handling.
Package tgerr implements helpers for error handling.
Package tgmock implements mock for tg.Invoker.
Package tgmock implements mock for tg.Invoker.
Package tgtest provides test Telegram server for basic end-to-end tests.
Package tgtest provides test Telegram server for basic end-to-end tests.
cluster
Package cluster contains Telegram multi-DC setup utilities.
Package cluster contains Telegram multi-DC setup utilities.
services
Package services contains some Telegram services implemented for testing.
Package services contains some Telegram services implemented for testing.
services/config
Package config contains config service implementation for tgtest server.
Package config contains config service implementation for tgtest server.
services/file
Package file contains file service implementation for tgtest server.
Package file contains file service implementation for tgtest server.
Package tgtrace is generated from gotd tracing schema.
Package tgtrace is generated from gotd tracing schema.
Package transport contains different MTProto transport implementations.
Package transport contains different MTProto transport implementations.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL