gotd/td

When calling a method like client.API().SomeMethod(ctx, ...), the request flows through the following layers:

1. Serialization: The generated tg.Client method serializes the request using the bin package and calls Invoke on the telegram.Client.
2. Middleware: Middlewares (such as rate limiting, flood-wait retry, or tracing) process the request.
3. Connection Pooling: telegram.Client acquires a connection from the pool for the target Data Center (DC), handling migrations or redirects to CDN DCs if necessary.
4. MTProto Layer: mtproto.Conn wraps the payload in an MTProto message (proto), encrypts it using the session auth_key (crypto), and writes it via the transport codec.
5. RPC Engine: The rpc engine manages message IDs, sends acknowledgments (acks), and handles retransmissions.
6. Response Handling: The response is decrypted, decoded, and routed back to the caller. Simultaneously, updates are dispatched to the telegram/updates manager and then to the user's UpdateHandler.

The gotd library is organized into a layered architecture where each layer depends only on the layers below it. This separation of concerns allows for modularity and specialized handling at different levels of the protocol stack:

1. High level (telegram): Authentication, updates, DC management, and convenience helpers.
2. Pool (pool): Per-datacenter connection pooling (pool.DC).
3. Connection (mtproto): Manages a single MTProto connection lifecycle (key exchange, pings, salts, and (de)serialization).
4. Support Layers:
   • RPC engine (rpc): Handles request/response matching, acknowledgements, and retries.
   • Crypto (crypto & exchange): Implements AES-IGE, RSA, Diffie-Hellman, and the auth key generation protocol.
   • Binary protocol (bin & proto): Handles TL/MTProto wire types and message primitives using non-streaming, reflection-free serialization.
5. Transport (transport): Manplements TCP/WebSocket connections, codecs (abridged, full, etc.), and obfuscation.

This example demonstrates several patterns for handling large file uploads in gotd:

• Multi-connection Upload Pool: Uses client.Pool(N) to create a pool of N sub-connections to the current Data Center (DC). This allows part uploads to be balanced across multiple connections for higher throughput.
• Thread Management: Uses uploader.WithThreads(N) to set a per-upload goroutine limit. This should be matched to the pool size to ensure part uploads fan out across all available connections.
• Progress Tracking: Uses uploader.WithProgress to implement a custom uploader.Progress interface. This allows logging upload speed (instantaneous and average) and progress at specific intervals (e.g., every 5 seconds).
• FFmpeg Integration:
  • Probing: Uses ffprobe to determine video width, height, and duration, which are then set via Resolution and Duration.
  • Thumbnails: Extracts a JPEG thumbnail using ffmpeg and attaches it via UploadedDocumentBuilder.Thumb.
  • Trimming: Uses the -cut flag to apply the ffmpeg -t command to limit video duration.
  • Compression: Uses the -max-size flag to re-encode the video to fit a target size budget by deriving a target bitrate from the requested size and duration.
• Video Replies: Uses message.UploadedDocument(...).Video() to ensure the uploaded file is sent as a video reply.

Use td/telegram/auth.Flow to handle the user authentication process. You can define a custom CodeAuthenticatorFunc to prompt the user for the login code (e.g., via terminal). For accounts without 2FA, use telegram.CodeOnlyAuth. For accounts with 2FA, use telegram.ConstantAuth to provide the password.

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