git.giacomolli.uk - onechat/blob - telegram_api.go

   1 package main
   2
   3 import (
   4         "bytes"
   5         "context"
   6         "encoding/json"
   7         "errors"
   8         "fmt"
   9         "io"
  10         "mime/multipart"
  11         "net/http"
  12         "net/url"
  13         "path"
  14         "strconv"
  15         "strings"
  16         "time"
  17 )
  18
  19 const (
  20         // telegramUpdateWaitTimeout is how long one getUpdates call waits for
  21         // an update.
  22         telegramUpdateWaitTimeout = 50 * time.Second
  23
  24         // telegramPollSlack is how much longer than telegramUpdateWaitTimeout a
  25         // getUpdates call can take before the bot gives it up.
  26         telegramPollSlack = 20 * time.Second
  27
  28         // telegramPollTimeout is how long one getUpdates call can take.
  29         telegramPollTimeout = telegramUpdateWaitTimeout + telegramPollSlack
  30
  31         // telegramSendTimeout is how long a sendMessage or sendRichMessage call
  32         // can take. A connection that stops without a close, such as after a
  33         // network change, then fails the call, and the sender tries again,
  34         // instead of a wait until TCP gives up. The client has no timeout of
  35         // its own, because the long poll of getUpdates needs a longer limit.
  36         telegramSendTimeout = 30 * time.Second
  37
  38         // telegramFileLookupTimeout is the longest wait for media file details.
  39         telegramFileLookupTimeout = 30 * time.Second
  40
  41         // telegramFileDownloadTimeout is the longest wait for downloaded media
  42         // bytes.
  43         telegramFileDownloadTimeout = 30 * time.Second
  44
  45         // telegramTypingTimeout is the longest wait to show the typing action.
  46         telegramTypingTimeout = 30 * time.Second
  47
  48         // telegramAnswerBytes is the most bytes of one answer of the Bot API.
  49         telegramAnswerBytes = 16 << 20
  50 )
  51
  52 // TelegramAPI calls the Telegram Bot API. The bot token is a part of each URL,
  53 // so no error of TelegramAPI holds a URL, a net/http error, or the token.
  54 type TelegramAPI struct {
  55         base  string
  56         token string
  57         http  *http.Client
  58 }
  59
  60 // TelegramNetworkError tells that a Bot API call got no valid answer, such as
  61 // after a network error. A later call can work. Cause tells why in plain words,
  62 // with no URL and no token.
  63 type TelegramNetworkError struct {
  64         Cause string
  65 }
  66
  67 // TelegramError is an answer of the Bot API that tells of a failure. Its text
  68 // gives the HTTP status and the description, such as "502 Bad Gateway".
  69 // RetryAfter is the wait that the Bot API asks for after HTTP 429. Refused
  70 // tells that the answer is a Bot API answer with ok false, not a page of a
  71 // proxy or of a server error.
  72 type TelegramError struct {
  73         Status      int
  74         Description string
  75         RetryAfter  time.Duration
  76         Refused     bool
  77 }
  78
  79 // TelegramUpdate is one update of getUpdates. Message is nil for the kinds of
  80 // updates that are not a new message.
  81 type TelegramUpdate struct {
  82         UpdateID int64            `json:"update_id"`
  83         Message  *TelegramMessage `json:"message"`
  84 }
  85
  86 // TelegramEntity is a message entity of sendMessage: a part of the text with a
  87 // format, such as bold or a link. Offset and Length count UTF-16 code units.
  88 // URL is the target of a text_link, and Language the language of a pre.
  89 type TelegramEntity struct {
  90         Type     string `json:"type"`
  91         Offset   int    `json:"offset"`
  92         Length   int    `json:"length"`
  93         URL      string `json:"url,omitempty"`
  94         Language string `json:"language,omitempty"`
  95 }
  96
  97 // TelegramAnswer is the envelope of each answer of the Bot API.
  98 type TelegramAnswer struct {
  99         OK          bool            `json:"ok"`
 100         Result      json.RawMessage `json:"result"`
 101         ErrorCode   int             `json:"error_code"`
 102         Description string          `json:"description"`
 103         Parameters  struct {
 104                 RetryAfter int `json:"retry_after"`
 105         } `json:"parameters"`
 106 }
 107
 108 // TelegramMessage holds text and supported media metadata of a bot message.
 109 type TelegramMessage struct {
 110         Chat     TelegramChat      `json:"chat"`
 111         From     *TelegramUser     `json:"from"`
 112         Text     string            `json:"text"`
 113         Caption  string            `json:"caption"`
 114         Photo    []TelegramPhoto   `json:"photo"`
 115         Document *TelegramDocument `json:"document"`
 116         Voice    *TelegramVoice    `json:"voice"`
 117 }
 118
 119 // TelegramVoice identifies a voice note in the authenticated file API.
 120 type TelegramVoice struct {
 121         FileID   string `json:"file_id"`
 122         FileSize int64  `json:"file_size"`
 123 }
 124
 125 // TelegramPhoto is one supplied size of a photo.
 126 type TelegramPhoto struct {
 127         FileID   string `json:"file_id"`
 128         Width    int    `json:"width"`
 129         Height   int    `json:"height"`
 130         FileSize int64  `json:"file_size"`
 131 }
 132
 133 // TelegramDocument is a file sent without photo compression.
 134 type TelegramDocument struct {
 135         FileID   string `json:"file_id"`
 136         MimeType string `json:"mime_type"`
 137         FileSize int64  `json:"file_size"`
 138 }
 139
 140 // TelegramChat is the chat of a message. Type is private for a chat with one
 141 // user.
 142 type TelegramChat struct {
 143         ID   int64  `json:"id"`
 144         Type string `json:"type"`
 145 }
 146
 147 // TelegramUser is the sender of a message.
 148 type TelegramUser struct {
 149         ID int64 `json:"id"`
 150 }
 151
 152 // newTelegramAPI returns the client of the Bot API at base with token.
 153 func newTelegramAPI(base, token string) *TelegramAPI {
 154         return &TelegramAPI{
 155                 base:  base,
 156                 token: token,
 157                 http:  &http.Client{},
 158         }
 159 }
 160
 161 // GetUpdates waits for the updates from offset on, up to
 162 // telegramUpdateWaitTimeout, and returns them. Telegram forgets each update
 163 // before offset. Only new messages are asked for.
 164 func (b *TelegramAPI) GetUpdates(ctx context.Context, offset int64) ([]TelegramUpdate, error) {
 165         var updates []TelegramUpdate
 166
 167         err := b.call(ctx, telegramPollTimeout, "getUpdates", map[string]any{
 168                 "offset":          offset,
 169                 "timeout":         int(telegramUpdateWaitTimeout / time.Second),
 170                 "allowed_updates": []string{"message"},
 171         }, &updates)
 172
 173         return updates, err
 174 }
 175
 176 // call sends one call of method with the JSON params and decodes its result
 177 // into result, when result is not nil. The call can take up to timeout. Its
 178 // request setup errors name the method. Network and answer errors give a safe
 179 // cause, so the caller can add the operation without exposing the request URL.
 180 func (b *TelegramAPI) call(ctx context.Context, timeout time.Duration, method string, params, result any) error {
 181         ctx, cancel := context.WithTimeout(ctx, timeout)
 182         defer cancel()
 183
 184         body, err := json.Marshal(params)
 185         if err != nil {
 186                 return fmt.Errorf("%s: encode request: %w", method, err)
 187         }
 188
 189         request, err := http.NewRequestWithContext(ctx, http.MethodPost, b.base+"/bot"+b.token+"/"+method, bytes.NewReader(body))
 190         if err != nil {
 191                 return fmt.Errorf("%s: make request: %s", method, b.redact(err))
 192         }
 193
 194         request.Header.Set("Content-Type", "application/json")
 195
 196         return b.answer(request, timeout, result)
 197 }
 198
 199 // redact returns the text of err without a URL and without the token. A
 200 // *url.Error holds the URL of the call, which holds the token, so only its
 201 // cause is kept.
 202 func (b *TelegramAPI) redact(err error) string {
 203         var urlError *url.Error
 204
 205         if errors.As(err, &urlError) {
 206                 err = urlError.Err
 207         }
 208
 209         return strings.ReplaceAll(err.Error(), b.token, "TOKEN")
 210 }
 211
 212 // answer reads the bounded Bot API response without keeping its request URL.
 213 func (b *TelegramAPI) answer(request *http.Request, timeout time.Duration, result any) error {
 214         response, err := b.http.Do(request)
 215         if err != nil {
 216                 return b.networkError("no answer", err, timeout)
 217         }
 218
 219         data, err := io.ReadAll(io.LimitReader(response.Body, telegramAnswerBytes))
 220         err = errors.Join(err, response.Body.Close())
 221         if err != nil {
 222                 return b.networkError("answer cut off", err, timeout)
 223         }
 224
 225         var answer TelegramAnswer
 226
 227         err = json.Unmarshal(data, &answer)
 228         if err != nil && response.StatusCode != http.StatusOK {
 229                 return &TelegramError{
 230                         Status:      response.StatusCode,
 231                         Description: http.StatusText(response.StatusCode),
 232                 }
 233         }
 234
 235         if err != nil {
 236                 return b.networkError("invalid JSON", err, timeout)
 237         }
 238
 239         if !answer.OK {
 240                 return &TelegramError{
 241                         Status:      response.StatusCode,
 242                         Description: b.redact(errors.New(answer.Description)),
 243                         RetryAfter:  time.Duration(answer.Parameters.RetryAfter) * time.Second,
 244                         Refused:     true,
 245                 }
 246         }
 247
 248         if result == nil {
 249                 return nil
 250         }
 251
 252         err = json.Unmarshal(answer.Result, result)
 253         if err != nil {
 254                 return b.networkError("invalid result", err, timeout)
 255         }
 256
 257         return nil
 258 }
 259
 260 // networkError returns the TelegramNetworkError of err, which happened at the
 261 // step that what names. When the call used all of its time timeout, the cause
 262 // is "no answer in TIMEOUT", because the Go text of a deadline does not tell
 263 // how long the wait was.
 264 func (b *TelegramAPI) networkError(what string, err error, timeout time.Duration) error {
 265         if errors.Is(err, context.DeadlineExceeded) {
 266                 return &TelegramNetworkError{
 267                         Cause: "no answer in " + timeout.String(),
 268                 }
 269         }
 270
 271         return &TelegramNetworkError{
 272                 Cause: what + ": " + b.redact(err),
 273         }
 274 }
 275
 276 // GetFile downloads bounded media through the authenticated file endpoint.
 277 // Errors never include its token or URL, and the body is limited before
 278 // storage.
 279 func (b *TelegramAPI) GetFile(ctx context.Context, id string, limit int64, tooLarge error) (data []byte, err error) {
 280         var file struct {
 281                 Path string `json:"file_path"`
 282                 Size int64  `json:"file_size"`
 283         }
 284
 285         err = b.call(ctx, telegramFileLookupTimeout, "getFile", map[string]any{"file_id": id}, &file)
 286         if err != nil {
 287                 return nil, fmt.Errorf("get media file: %w", err)
 288         }
 289
 290         if file.Size > limit {
 291                 return nil, tooLarge
 292         }
 293
 294         if file.Path == "" || path.Clean(file.Path) != file.Path || strings.HasPrefix(file.Path, "/") || strings.HasPrefix(file.Path, "../") || strings.ContainsAny(file.Path, "?%#\\") {
 295                 return nil, errors.New("invalid media file path")
 296         }
 297
 298         ctx, cancel := context.WithTimeout(ctx, telegramFileDownloadTimeout)
 299         defer cancel()
 300
 301         request, err := http.NewRequestWithContext(ctx, http.MethodGet, b.base+"/file/bot"+b.token+"/"+file.Path, nil)
 302         if err != nil {
 303                 return nil, fmt.Errorf("make media request: %s", b.redact(err))
 304         }
 305
 306         response, err := b.http.Do(request)
 307         if err != nil {
 308                 return nil, b.networkError("media download failed", err, telegramFileDownloadTimeout)
 309         }
 310
 311         defer func() {
 312                 closeErr := response.Body.Close()
 313                 if closeErr != nil {
 314                         err = errors.Join(err, b.networkError("close media download", closeErr, telegramFileDownloadTimeout))
 315                 }
 316         }()
 317
 318         if response.StatusCode != http.StatusOK {
 319                 return nil, &TelegramError{
 320                         Status:      response.StatusCode,
 321                         Description: http.StatusText(response.StatusCode),
 322                 }
 323         }
 324
 325         data, err = io.ReadAll(io.LimitReader(response.Body, limit+1))
 326         if err != nil {
 327                 return nil, b.networkError("media cut off", err, telegramFileDownloadTimeout)
 328         }
 329
 330         if int64(len(data)) > limit {
 331                 return nil, tooLarge
 332         }
 333
 334         return data, nil
 335 }
 336
 337 // SendMessage sends text to chat with the format of entities, with no parse
 338 // mode, so the text needs no escaping. With no entities, the text is plain. A
 339 // call that takes longer than telegramSendTimeout fails with a
 340 // TelegramNetworkError.
 341 func (b *TelegramAPI) SendMessage(ctx context.Context, chat int64, text string, entities []TelegramEntity) error {
 342         params := map[string]any{
 343                 "chat_id": chat,
 344                 "text":    text,
 345         }
 346
 347         if len(entities) > 0 {
 348                 params["entities"] = entities
 349         }
 350
 351         return b.call(ctx, telegramSendTimeout, "sendMessage", params, nil)
 352 }
 353
 354 // SendRichMessage sends markdown to chat as a rich message, which Telegram
 355 // renders itself, tables included. A call that takes longer than
 356 // telegramSendTimeout fails with a TelegramNetworkError.
 357 func (b *TelegramAPI) SendRichMessage(ctx context.Context, chat int64, markdown string) error {
 358         return b.call(ctx, telegramSendTimeout, "sendRichMessage", map[string]any{
 359                 "chat_id": chat,
 360                 "rich_message": map[string]any{
 361                         "markdown": markdown,
 362                 },
 363         }, nil)
 364 }
 365
 366 // SendImage uploads an image to the owner as a photo, or as a document when the
 367 // Bot API refuses the photo. Network failures do not trigger a second send.
 368 func (b *TelegramAPI) SendImage(ctx context.Context, chat int64, name string, data []byte, caption string) error {
 369         err := b.sendImage(ctx, "sendPhoto", "photo", chat, name, data, caption)
 370         if telegramRejected(err) {
 371                 err = b.sendImage(ctx, "sendDocument", "document", chat, name, data, caption)
 372         }
 373
 374         return err
 375 }
 376
 377 func (b *TelegramAPI) sendImage(ctx context.Context, method, field string, chat int64, name string, data []byte, caption string) error {
 378         ctx, cancel := context.WithTimeout(ctx, telegramSendTimeout)
 379         defer cancel()
 380
 381         var body bytes.Buffer
 382
 383         writer := multipart.NewWriter(&body)
 384         err := writer.WriteField("chat_id", strconv.FormatInt(chat, 10))
 385         if err != nil {
 386                 return fmt.Errorf("write image chat: %w", err)
 387         }
 388
 389         err = writer.WriteField("caption", caption)
 390         if err != nil {
 391                 return fmt.Errorf("write image caption: %w", err)
 392         }
 393
 394         part, err := writer.CreateFormFile(field, name)
 395         if err != nil {
 396                 return fmt.Errorf("make image part: %w", err)
 397         }
 398
 399         _, err = part.Write(data)
 400         if err != nil {
 401                 return fmt.Errorf("write image part: %w", err)
 402         }
 403
 404         err = writer.Close()
 405         if err != nil {
 406                 return fmt.Errorf("close image form: %w", err)
 407         }
 408
 409         request, err := http.NewRequestWithContext(ctx, http.MethodPost, b.base+"/bot"+b.token+"/"+method, &body)
 410         if err != nil {
 411                 return fmt.Errorf("make image upload: %s", b.redact(err))
 412         }
 413
 414         request.Header.Set("Content-Type", writer.FormDataContentType())
 415
 416         err = b.answer(request, telegramSendTimeout, nil)
 417         if err != nil {
 418                 return fmt.Errorf("upload image: %w", err)
 419         }
 420
 421         return nil
 422 }
 423
 424 // SendTyping shows the typing action in chat for about five seconds. A call
 425 // that takes longer than telegramTypingTimeout fails with a
 426 // TelegramNetworkError.
 427 func (b *TelegramAPI) SendTyping(ctx context.Context, chat int64) error {
 428         return b.call(ctx, telegramTypingTimeout, "sendChatAction", map[string]any{
 429                 "chat_id": chat,
 430                 "action":  "typing",
 431         }, nil)
 432 }
 433
 434 func (e *TelegramNetworkError) Error() string {
 435         return e.Cause
 436 }
 437
 438 func (e *TelegramError) Error() string {
 439         return fmt.Sprintf("%d %s", e.Status, e.Description)
 440 }
 441
 442 // telegramRejected tells if the Bot API refused a call with ok false and HTTP
 443 // 400 or 404. Then the call did nothing: 400 refuses the request, and 404 tells
 444 // that the method is not there. An error page with no Bot API answer does not
 445 // tell this, so it is not a refusal.
 446 func telegramRejected(err error) bool {
 447         var answer *TelegramError
 448
 449         return errors.As(err, &answer) && answer.Refused && (answer.Status == http.StatusBadRequest || answer.Status == http.StatusNotFound)
 450 }
 451
 452 // telegramRetryable tells if a later try of a failed Bot API call can work:
 453 // after a network error, HTTP 429, or a server error. It returns the wait that
 454 // the Bot API asks for, or 0.
 455 func telegramRetryable(err error) (bool, time.Duration) {
 456         var network *TelegramNetworkError
 457
 458         if errors.As(err, &network) {
 459                 return true, 0
 460         }
 461
 462         var answer *TelegramError
 463
 464         if errors.As(err, &answer) {
 465                 return answer.Status == http.StatusTooManyRequests || answer.Status >= 500, answer.RetryAfter
 466         }
 467
 468         return false, 0
 469 }