ext

ext package quick start

ext provides application-layer routing and bounded update dispatch on top of tgbot.Bot:

• ordered and nested handler groups;
• global and group middleware;
• filters, priorities, first-match routing, and propagation control;
• a fixed-size worker pool with a bounded queue;
• synchronous and enqueue-first webhook acknowledgement;
• long polling with bounded backpressure.

Minimal setup

package main

import (
    "context"
    "net/http"
    "time"

    "github.com/cloudapp3/tgbot"
    "github.com/cloudapp3/tgbot/ext"
)

func main() {
    bot, _ := tgbot.NewBot("<BOT_TOKEN>")
    app, _ := ext.NewApplication(bot)

    app.AddHandler(ext.NewCommandHandler("start", func(ctx context.Context, c *ext.Context) error {
        msg := c.EffectiveMessage()
        if msg == nil || msg.Chat == nil {
            return nil
        }
        _, err := c.Bot.SendMessage(ctx, &tgbot.SendMessageParams{
            ChatID: msg.Chat.ID,
            Text:   "hello",
        })
        return err
    }))

    mux := http.NewServeMux()
    mux.Handle("/telegram/webhook", app.WebhookHandler("<SECRET_TOKEN>"))
    server := &http.Server{
        Addr:              ":8080",
        Handler:           mux,
        ReadHeaderTimeout: 5 * time.Second,
        ReadTimeout:       15 * time.Second,
        WriteTimeout:      45 * time.Second,
        IdleTimeout:       60 * time.Second,
    }
    _ = server.ListenAndServe()
}

WebhookHandler remains synchronous: it returns 200 only after all matching handlers complete successfully.

Groups and middleware

Explicit groups run by ascending priority. At most the first matching handler in each explicit group runs. Application-level AddHandler registrations keep the legacy behavior where every matching registration runs.

app.Use(func(next ext.HandlerFunc) ext.HandlerFunc {
    return func(ctx context.Context, update *ext.Context) error {
        return next(ctx, update)
    }
})

commands := app.GroupWithPriority(-10, ext.CommandFilter())
commands.AddHandler(ext.NewCommandHandler("start", startHandler))
commands.AddHandler(ext.NewCommandHandler("help", helpHandler))

admin := commands.Group(adminFilter)
admin.Use(auditMiddleware)
handle := admin.AddHandler(ext.NewCommandHandler("status", statusHandler))
defer handle.Remove()

Child groups dynamically inherit parent filters and middleware. A handler can call Context.StopPropagation() to prevent later groups from running.

Bounded webhook dispatch

Create and own the dispatcher explicitly when a webhook should acknowledge an update after admission rather than after processing:

app, _ := ext.NewApplication(
    bot,
    ext.WithMaxConcurrentUpdates(8),
    ext.WithUpdateQueueSize(128),
    ext.WithHandlerTimeout(30*time.Second),
    ext.WithPanicHandler(func(ctx context.Context, update *ext.Context, err *ext.PanicError) {
        log.Printf("update panic: %v", err)
    }),
)

dispatcher, _ := ext.NewDispatcher(app)
defer func() {
    shutdownCtx, cancel := context.WithTimeout(context.Background(), 10*time.Second)
    defer cancel()
    _ = dispatcher.Shutdown(shutdownCtx)
}()

handler := app.WebhookHandlerWithOptions(
    "<SECRET_TOKEN>",
    ext.AckAfterEnqueue,
    ext.WithWebhookDispatcher(dispatcher),
)

AckAfterEnqueue returns 503 when the queue is full or the dispatcher is closed, so Telegram can retry. AckAfterProcess can also use a dispatcher while retaining synchronous acknowledgement. The dispatcher must be created from the same Application; a mismatched dispatcher is rejected with 503.

Enqueue waits for queue capacity. TryEnqueue returns ErrUpdateQueueFull immediately. Shutdown stops admission and drains accepted updates until its context expires. Handler timeouts cancel the handler context; handlers must observe cancellation to stop promptly.

Long polling

RunPolling owns an internal bounded dispatcher configured by the application. The default error policy processes updates concurrently up to the configured worker count while applying queue backpressure. WithContinueOnError(false) uses strict serial processing so it can stop at the first handler error.

ctx, stop := signal.NotifyContext(context.Background(), os.Interrupt, syscall.SIGTERM)
defer stop()

app, _ := ext.NewApplication(
    bot,
    ext.WithMaxConcurrentUpdates(4),
    ext.WithUpdateQueueSize(64),
)

_ = app.RunPolling(ctx,
    ext.WithPollingAllowedUpdates(
        ext.UpdateTypeMessage,
        ext.UpdateTypeCallbackQuery,
    ),
)

WithPollingNonBlockingDispatch explicitly permits the root poller to drop local updates when downstream delivery is full. Leave it disabled when every update must receive backpressure instead of being dropped.

Useful helpers

Handlers:

• NewAnyHandler
• NewTypeHandler
• NewMessageHandler
• NewCommandHandler
• NewCallbackQueryHandler

Filters:

• TextFilter
• CommandFilter
• RegexFilter
• UpdateTypeFilter
• And, Or, and Not