telegoapi

Documentation

Overview

Package telegoapi provides API for calling Telegram for Telego.

This API package describes the main part of communication with Telegram Bot API.

The response represents the API response from Telegram with respectful result and error values.

Caller interface represents the general logic of sending requests to API and receiving responses from it. Currently, Telego provides valyala/fasthttp and net/http implementation, but your own can be defined and specified via telego.BotOption's.

RequestConstructor interface represents a general way of constructing RequestData used in Caller. Currently, Telego provides an only default implementation that uses goccy/go-json instead of encoding/json and std mime/multipart package.

NamedReader interface represents a general way of sending files that are provided to RequestConstructor. As io.Reader can be provided, any valid reader and name method should return a unique name for every file in one request, otherwise not all files will be sent properly.

Index

• Constants
• Variables
• type Caller
• type DefaultConstructor
  • func (d DefaultConstructor) JSONRequest(parameters any) (*RequestData, error)
  • func (d DefaultConstructor) MultipartRequest(parameters map[string]string, filesParameters map[string]NamedReader) (*RequestData, error)
• type Error
  • func (a *Error) Error() string
• type FastHTTPCaller
  • func (a FastHTTPCaller) Call(url string, data *RequestData) (*Response, error)
• type HTTPCaller
  • func (h HTTPCaller) Call(url string, data *RequestData) (*Response, error)
• type NamedReader
• type RequestConstructor
• type RequestData
• type Response
  • func (r Response) String() string
• type ResponseParameters
• type RetryCaller
  • func (r *RetryCaller) Call(url string, data *RequestData) (resp *Response, err error)

Constants

const (
	// ContentTypeHeader http content type header
	ContentTypeHeader = "Content-Type"

	// ContentTypeJSON http JSON content type
	ContentTypeJSON = "application/json"
)

Variables

var DefaultFastHTTPCaller = &FastHTTPCaller{
	Client: &fasthttp.Client{},
}

DefaultFastHTTPCaller is a default fast http caller

var DefaultHTTPCaller = &HTTPCaller{
	Client: http.DefaultClient,
}

DefaultHTTPCaller is a default http caller

var ErrMaxRetryAttempts = errors.New("max retry attempts reached")

ErrMaxRetryAttempts returned when max retry attempts reached

Types

type Caller

type Caller interface {
	Call(url string, data *RequestData) (*Response, error)
}

Caller represents way to call API with request

type DefaultConstructor

type DefaultConstructor struct{}

DefaultConstructor default implementation of RequestConstructor

func (DefaultConstructor) JSONRequest

func (d DefaultConstructor) JSONRequest(parameters any) (*RequestData, error)

JSONRequest is default implementation

func (DefaultConstructor) MultipartRequest

func (d DefaultConstructor) MultipartRequest(parameters map[string]string, filesParameters map[string]NamedReader) (
	*RequestData, error,
)

MultipartRequest is default implementation

type Error

type Error struct {
	Description string              `json:"description,omitempty"`
	ErrorCode   int                 `json:"error_code,omitempty"`
	Parameters  *ResponseParameters `json:"parameters,omitempty"`
}

Error represents error from telegram API

func (*Error) Error

func (a *Error) Error() string

Error converts Error to human-readable string

type FastHTTPCaller

type FastHTTPCaller struct {
	Client *fasthttp.Client
}

FastHTTPCaller fasthttp implementation of Caller

func (FastHTTPCaller) Call

func (a FastHTTPCaller) Call(url string, data *RequestData) (*Response, error)

Call is a fasthttp implementation

type HTTPCaller

type HTTPCaller struct {
	Client *http.Client
}

HTTPCaller http implementation of Caller

func (HTTPCaller) Call

func (h HTTPCaller) Call(url string, data *RequestData) (*Response, error)

Call is a http implementation

type NamedReader

type NamedReader interface {
	io.Reader
	Name() string
}

NamedReader represents a way to send files (or other data). Implemented by os.File. Note: Name method may be called multiple times and should return unique names for all files sent in one request.

Warning: Since, for sending data (files) reader data will be copied, using the same reader multiple times as is will not work. For os.File you can use file.Seek(0, io.SeekStart) to prepare for a new request.

type RequestConstructor

type RequestConstructor interface {
	JSONRequest(parameters any) (*RequestData, error)
	MultipartRequest(parameters map[string]string, filesParameters map[string]NamedReader) (*RequestData, error)
}

RequestConstructor represents a way to construct API request

type RequestData

type RequestData struct {
	ContentType string
	Buffer      *bytes.Buffer
}

RequestData represents data needed to execute request

type Response

type Response struct {
	Ok     bool            `json:"ok"`
	Result json.RawMessage `json:"result,omitempty"`
	*Error
}

Response represents response returned by Telegram API

func (Response) String

func (r Response) String() string

type ResponseParameters

type ResponseParameters struct {
	// MigrateToChatID - Optional. The group has been migrated to a supergroup with the specified identifier.
	// This number may have more than 32 significant bits and some programming languages may have difficulty/silent
	// defects in interpreting it. But it has at most 52 significant bits, so a signed 64-bit integer or
	// double-precision float type are safe for storing this identifier.
	MigrateToChatID int64 `json:"migrate_to_chat_id,omitempty"`

	// RetryAfter - Optional. In case of exceeding flood control, the number of seconds left to wait before the
	// request can be repeated
	RetryAfter int `json:"retry_after,omitempty"`
}

ResponseParameters - Describes why a request was unsuccessful.

type RetryCaller

type RetryCaller struct {
	Caller       Caller
	MaxAttempts  int
	ExponentBase float64
	StartDelay   time.Duration
	MaxDelay     time.Duration
}

RetryCaller decorator over Caller that provides reties with exponential backoff Delay = (ExponentBase ^ AttemptNumber) * StartDelay or MaxDelay

func (*RetryCaller) Call

func (r *RetryCaller) Call(url string, data *RequestData) (resp *Response, err error)

Call makes calls using provided caller with retries