lukaszraczylo
9cfe193e2e
PR #1 changed AllowedUpdates type and shifted longpoll.go line numbers but left docs/reference/ stale, breaking the codegen-clean CI gate.
9.4 KiB
transport
import "github.com/lukaszraczylo/go-telegram/transport"
Package transport provides update delivery mechanisms (long-poll and webhook) that feed updates into the dispatch package's Router.
All implementations satisfy the Updater interface so user code can swap one for the other without touching handler logic.
Index
- type BackoffStrategy
- type ExponentialBackoff
- type LongPoller
- type Updater
- type WebhookOption
- type WebhookServer
- func NewWebhookServer(b *client.Bot, opts ...WebhookOption) *WebhookServer
- func (w *WebhookServer) ListenAndServe(ctx context.Context, addr string) error
- func (w *WebhookServer) Run(ctx context.Context) error
- func (w *WebhookServer) ServeHTTP(rw http.ResponseWriter, r *http.Request)
- func (w *WebhookServer) Stop(ctx context.Context) error
- func (w *WebhookServer) Updates() <-chan api.Update
type BackoffStrategy
BackoffStrategy returns the duration to wait before the next attempt after `attempt` consecutive failures (1-based). Implementations must be safe to call from a single goroutine.
type BackoffStrategy interface {
NextDelay(attempt int) time.Duration
}
type ExponentialBackoff
ExponentialBackoff implements capped exponential back-off with jitter. Defaults: Base=500ms, Max=30s, Factor=2.0, Jitter=0.2.
type ExponentialBackoff struct {
Base time.Duration
Max time.Duration
Factor float64
Jitter float64 // 0..1; fraction of computed delay added/subtracted at random
}
func DefaultBackoff
func DefaultBackoff() *ExponentialBackoff
DefaultBackoff returns an ExponentialBackoff with library defaults.
func (*ExponentialBackoff) NextDelay
func (b *ExponentialBackoff) NextDelay(attempt int) time.Duration
NextDelay implements BackoffStrategy.
type LongPoller
LongPoller pulls updates via Bot.GetUpdates in a loop, advancing the offset cursor after each batch. It applies BackoffStrategy on transient errors (network failures, 5xx, 429).
At-least-once semantics on shutdown: when ctx is cancelled or Stop is called mid-batch, any updates already fetched but not yet dispatched are dropped without advancing the offset. On the next restart those updates will be re-delivered by Telegram.
type LongPoller struct {
Bot *client.Bot
Timeout int // seconds, default 30
Limit int // 1..100, default 100
AllowedTypes []api.UpdateType
Backoff BackoffStrategy
// contains filtered or unexported fields
}
func NewLongPoller
func NewLongPoller(b *client.Bot) *LongPoller
NewLongPoller constructs a LongPoller with sensible defaults.
func (*LongPoller) Run
func (p *LongPoller) Run(ctx context.Context) error
Run implements Updater. It blocks until ctx is cancelled, Stop is called, or a fatal error occurs (e.g. unauthorized). See LongPoller for at-least-once delivery semantics on shutdown.
func (*LongPoller) Stop
func (p *LongPoller) Stop(ctx context.Context) error
Stop implements Updater.
func (*LongPoller) Updates
func (p *LongPoller) Updates() <-chan api.Update
Updates implements Updater.
type Updater
Updater is the abstraction over update sources. Implementations must:
- return a channel from Updates() that receives every Update they read.
- close the channel after Run returns.
- honour ctx cancellation in Run.
type Updater interface {
// Updates returns the channel updates flow into. Multiple readers
// is implementation-defined; users should treat it as single-reader.
Updates() <-chan api.Update
// Run blocks until ctx is cancelled or a fatal error occurs. It is
// the user's responsibility to call Run in a goroutine if needed.
Run(ctx context.Context) error
// Stop signals Run to exit and waits for the channel to drain.
// Implementations must be idempotent.
Stop(ctx context.Context) error
}
type WebhookOption
WebhookOption configures a WebhookServer at construction time.
type WebhookOption func(*webhookOptions)
func WithBufferSize
func WithBufferSize(n int) WebhookOption
WithBufferSize sets the size of the updates channel buffer. Default is 64.
type WebhookServer
WebhookServer implements Updater by exposing an http.Handler that receives updates from Telegram. It can be mounted on the user's own HTTP server (via ServeHTTP) or run standalone (via ListenAndServe).
type WebhookServer struct {
Bot *client.Bot
SecretToken string // verify X-Telegram-Bot-Api-Secret-Token; empty disables
// contains filtered or unexported fields
}
func NewWebhookServer
func NewWebhookServer(b *client.Bot, opts ...WebhookOption) *WebhookServer
NewWebhookServer constructs a WebhookServer with default buffer size (64). Use WithBufferSize to override.
func (*WebhookServer) ListenAndServe
func (w *WebhookServer) ListenAndServe(ctx context.Context, addr string) error
ListenAndServe starts an HTTP server on addr and blocks until Stop is called (which triggers Shutdown with the caller's context) or the server returns an error other than http.ErrServerClosed. Callers must invoke Stop(ctx) to cleanly shut down the server; the ctx passed here is only used as the server's base context for incoming requests.
func (*WebhookServer) Run
func (w *WebhookServer) Run(ctx context.Context) error
Run implements Updater. It blocks until Stop is called or ctx is cancelled. If the server has not been started via ListenAndServe, Run only watches for shutdown — the user is expected to mount ServeHTTP on their own router.
func (*WebhookServer) ServeHTTP
func (w *WebhookServer) ServeHTTP(rw http.ResponseWriter, r *http.Request)
ServeHTTP implements http.Handler. Telegram POSTs each update as JSON to this endpoint. Non-POST requests get 405; bad bodies get 400; secret token mismatches get 401.
func (*WebhookServer) Stop
func (w *WebhookServer) Stop(ctx context.Context) error
Stop implements Updater.
func (*WebhookServer) Updates
func (w *WebhookServer) Updates() <-chan api.Update
Updates implements Updater.
Generated by gomarkdoc