td

package module
Version: v0.50.0 Latest Latest
Warning

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

Go to latest
Published: Aug 24, 2021 License: MIT Imports: 0 Imported by: 0

README

td Go Reference codecov

A fast Telegram client in pure Go.

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

Usage

go get github.com/gotd/td
package main

import (
	"context"
	"github.com/gotd/td/telegram"
	"github.com/gotd/td/tg"
)

func main() {
	client := telegram.NewClient(appID, appHash, telegram.Options{})
	err := client.Run(context.Background(), func(ctx context.Context) error {
		api := tg.NewClient(client)

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

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

See examples for more info.

Status

Work is still in progress (mostly helpers and convenience wrappers), but basic functionality were tested in production and works fine. Only go1.16 is supported and no backward compatibility is provided for now.

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).

Also, see the comparison with other Go Telegram clients.

Features

  • Full MTProto 2.0 implementation in Golang
  • 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
  • CDN support with connection pooling
  • Automatic datacenter migration and redirects handling
  • Graceful request cancellation via context
  • WebSocket transport support (works in WASM)

Examples

See examples directory.

Also take a look at

  • gotd/bot with updates recovery enabled, used as canary for stability testing
  • 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 := tg.NewClient(client).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
  • zweihander
    • Background pings
    • Links in generated documentation
    • Message acknowledgements
    • Retries
    • RPC 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

Difference to other projects

Status by 11.07.2021

Topic gotd xelaj/mtproto
🚧
Maintainers
At least 3 core contributors, 1.7K commits, actively maintained, automatically updated to latest layer Single core contributor, 150 commits, effectively not maintaned from March 2021, failed to update to 129 layer
🔒️
Security
MTProto v2, conforms to security guidelines MTProto v1 that is insecure and deprecated since 2017 (SHA-1 is used instead of SHA-256), code was probably copied from sdidyk/mtproto or cjongseok/mtproto with little understanding
🚀
Features
MTProxy support, WebSocket transport, helpers for uploads, downloads, messages, text styling, datacenter redirects handling and more, but you can still use the raw API Raw MTProto API
🔨
Platforms
All platforms including WASM and special stability features for Windows that considers clock resolution Limited support for Windows
⚡️
Performance
Multiple optimizations for zero allocations Uses reflection in runtime
🧪
Stability
Lots of unit tests (237 tests, 943 including subtests), end-to-end tests with self-made Telegram server in Go, end-to-end tests with real test servers, fuzzing 12 unit tests, 41 including sub-tests

GitHub Stargazers
Has only 192 stars GitHub stars
GitHub watchers
Has 643 stars, which is much higher GitHub stars
GitHub watchers

License

MIT License

Created by Aleksandr (ernado) Razumov

2020

Documentation

Overview

Package td implements MTProto encoding and decoding.

Source Files

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.
Package examples contains usage examples for gotd features.
Package examples contains usage examples for gotd features.
auth
Binary auth implements authentication example for user using terminal.
Binary auth implements authentication example for user using terminal.
bot-auth-manual
Binary bot-auth-manual implements example of custom session storage and manually setting up client options without environment variables.
Binary bot-auth-manual implements example of custom session storage and manually setting up client options without environment variables.
bot-echo
Binary bot-echo implements basic example for bot.
Binary bot-echo implements basic example for bot.
bot-upload
Binary bot-upload implements upload example for bot.
Binary bot-upload implements upload example for bot.
bg-run Module
gif-download Module
Package gorules contains ruleguard linter rules.
Package gorules contains ruleguard linter rules.
Package session implements session storage.
Package session implements session storage.
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.
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.
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.
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/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.
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/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.
updates
Package updates provides a Telegram's state synchronization engine.
Package updates provides a Telegram's state synchronization engine.
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 transport contains different MTProto transport implementations.
Package transport contains different MTProto transport implementations.
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/faketls/tlstypes
Package tlstypes is copy of tlstypes package in mtg.
Package tlstypes is copy of tlstypes package in mtg.
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.

Jump to

Keyboard shortcuts

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