go-telegram/docs/reference/transport.md

<!-- Code generated by gomarkdoc. DO NOT EDIT -->

# transport

```go
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](<#BackoffStrategy>)
- [type ExponentialBackoff](<#ExponentialBackoff>)
  - [func DefaultBackoff\(\) \*ExponentialBackoff](<#DefaultBackoff>)
  - [func \(b \*ExponentialBackoff\) NextDelay\(attempt int\) time.Duration](<#ExponentialBackoff.NextDelay>)
- [type LongPoller](<#LongPoller>)
  - [func NewLongPoller\(b \*client.Bot\) \*LongPoller](<#NewLongPoller>)
  - [func \(p \*LongPoller\) Run\(ctx context.Context\) error](<#LongPoller.Run>)
  - [func \(p \*LongPoller\) Stop\(ctx context.Context\) error](<#LongPoller.Stop>)
  - [func \(p \*LongPoller\) Updates\(\) \<\-chan api.Update](<#LongPoller.Updates>)
- [type Updater](<#Updater>)
- [type WebhookOption](<#WebhookOption>)
  - [func WithBufferSize\(n int\) WebhookOption](<#WithBufferSize>)
- [type WebhookServer](<#WebhookServer>)
  - [func NewWebhookServer\(b \*client.Bot, opts ...WebhookOption\) \*WebhookServer](<#NewWebhookServer>)
  - [func \(w \*WebhookServer\) ListenAndServe\(ctx context.Context, addr string\) error](<#WebhookServer.ListenAndServe>)
  - [func \(w \*WebhookServer\) Run\(ctx context.Context\) error](<#WebhookServer.Run>)
  - [func \(w \*WebhookServer\) ServeHTTP\(rw http.ResponseWriter, r \*http.Request\)](<#WebhookServer.ServeHTTP>)
  - [func \(w \*WebhookServer\) Stop\(ctx context.Context\) error](<#WebhookServer.Stop>)
  - [func \(w \*WebhookServer\) Updates\(\) \<\-chan api.Update](<#WebhookServer.Updates>)


<a name="BackoffStrategy"></a>
## type [BackoffStrategy](<https://github.com/lukaszraczylo/go-telegram/blob/main/transport/backoff.go#L12-L14>)

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.

```go
type BackoffStrategy interface {
    NextDelay(attempt int) time.Duration
}
```

<a name="ExponentialBackoff"></a>
## type [ExponentialBackoff](<https://github.com/lukaszraczylo/go-telegram/blob/main/transport/backoff.go#L18-L23>)

ExponentialBackoff implements capped exponential back\-off with jitter. Defaults: Base=500ms, Max=30s, Factor=2.0, Jitter=0.2.

```go
type ExponentialBackoff struct {
    Base   time.Duration
    Max    time.Duration
    Factor float64
    Jitter float64 // 0..1; fraction of computed delay added/subtracted at random
}
```

<a name="DefaultBackoff"></a>
### func [DefaultBackoff](<https://github.com/lukaszraczylo/go-telegram/blob/main/transport/backoff.go#L26>)

```go
func DefaultBackoff() *ExponentialBackoff
```

DefaultBackoff returns an ExponentialBackoff with library defaults.

<a name="ExponentialBackoff.NextDelay"></a>
### func \(\*ExponentialBackoff\) [NextDelay](<https://github.com/lukaszraczylo/go-telegram/blob/main/transport/backoff.go#L36>)

```go
func (b *ExponentialBackoff) NextDelay(attempt int) time.Duration
```

NextDelay implements BackoffStrategy.

<a name="LongPoller"></a>
## type [LongPoller](<https://github.com/lukaszraczylo/go-telegram/blob/main/transport/longpoll.go#L21-L31>)

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.

```go
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
}
```

<a name="NewLongPoller"></a>
### func [NewLongPoller](<https://github.com/lukaszraczylo/go-telegram/blob/main/transport/longpoll.go#L34>)

```go
func NewLongPoller(b *client.Bot) *LongPoller
```

NewLongPoller constructs a LongPoller with sensible defaults.

<a name="LongPoller.Run"></a>
### func \(\*LongPoller\) [Run](<https://github.com/lukaszraczylo/go-telegram/blob/main/transport/longpoll.go#L51>)

```go
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.

<a name="LongPoller.Stop"></a>
### func \(\*LongPoller\) [Stop](<https://github.com/lukaszraczylo/go-telegram/blob/main/transport/longpoll.go#L122>)

```go
func (p *LongPoller) Stop(ctx context.Context) error
```

Stop implements Updater.

<a name="LongPoller.Updates"></a>
### func \(\*LongPoller\) [Updates](<https://github.com/lukaszraczylo/go-telegram/blob/main/transport/longpoll.go#L46>)

```go
func (p *LongPoller) Updates() <-chan api.Update
```

Updates implements Updater.

<a name="Updater"></a>
## type [Updater](<https://github.com/lukaszraczylo/go-telegram/blob/main/transport/updater.go#L13-L23>)

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.

```go
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
}
```

<a name="WebhookOption"></a>
## type [WebhookOption](<https://github.com/lukaszraczylo/go-telegram/blob/main/transport/webhook.go#L38>)

WebhookOption configures a WebhookServer at construction time.

```go
type WebhookOption func(*webhookOptions)
```

<a name="WithBufferSize"></a>
### func [WithBufferSize](<https://github.com/lukaszraczylo/go-telegram/blob/main/transport/webhook.go#L46>)

```go
func WithBufferSize(n int) WebhookOption
```

WithBufferSize sets the size of the updates channel buffer. Default is 64.

<a name="WebhookServer"></a>
## type [WebhookServer](<https://github.com/lukaszraczylo/go-telegram/blob/main/transport/webhook.go#L24-L35>)

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

```go
type WebhookServer struct {
    Bot         *client.Bot
    SecretToken string // verify X-Telegram-Bot-Api-Secret-Token; empty disables
    // contains filtered or unexported fields
}
```

<a name="NewWebhookServer"></a>
### func [NewWebhookServer](<https://github.com/lukaszraczylo/go-telegram/blob/main/transport/webhook.go#L52>)

```go
func NewWebhookServer(b *client.Bot, opts ...WebhookOption) *WebhookServer
```

NewWebhookServer constructs a WebhookServer with default buffer size \(64\). Use WithBufferSize to override.

<a name="WebhookServer.ListenAndServe"></a>
### func \(\*WebhookServer\) [ListenAndServe](<https://github.com/lukaszraczylo/go-telegram/blob/main/transport/webhook.go#L150>)

```go
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.

<a name="WebhookServer.Run"></a>
### func \(\*WebhookServer\) [Run](<https://github.com/lukaszraczylo/go-telegram/blob/main/transport/webhook.go#L71>)

```go
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.

<a name="WebhookServer.ServeHTTP"></a>
### func \(\*WebhookServer\) [ServeHTTP](<https://github.com/lukaszraczylo/go-telegram/blob/main/transport/webhook.go#L97>)

```go
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.

<a name="WebhookServer.Stop"></a>
### func \(\*WebhookServer\) [Stop](<https://github.com/lukaszraczylo/go-telegram/blob/main/transport/webhook.go#L83>)

```go
func (w *WebhookServer) Stop(ctx context.Context) error
```

Stop implements Updater.

<a name="WebhookServer.Updates"></a>
### func \(\*WebhookServer\) [Updates](<https://github.com/lukaszraczylo/go-telegram/blob/main/transport/webhook.go#L65>)

```go
func (w *WebhookServer) Updates() <-chan api.Update
```

Updates implements Updater.

Generated by [gomarkdoc](<https://github.com/princjef/gomarkdoc>)