feat(handler): add handler framework core (router, middleware, context)

Handler, Context (embeds the request context plus Bot and Update), Predicate
and Middleware types, and a concurrency-safe router on Bot. Bot.Use registers
global middleware (outermost-first); route dispatches to the first matching
handler wrapped in middleware and contains handler errors by logging them. The
dispatcher wiring and On* registration come next.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

Author: ernado

bot.go

@@ -30,6 +30,8 @@ type Bot struct {
 	gaps   *updates.Manager
 	disp   tg.UpdateDispatcher
 
+	router router
+
 	onStart func(ctx context.Context)
 
 	self *tg.User

handler.go

@@ -0,0 +1,90 @@
+package botapi
+
+import (
+	"context"
+	"sync"
+
+	"go.uber.org/zap"
+)
+
+// Context is passed to a Handler. It embeds the request context (so it can be
+// passed straight to Bot methods) and carries the Bot and the Update.
+type Context struct {
+	context.Context
+
+	Bot    *Bot
+	Update *Update
+}
+
+// Handler processes a single update.
+type Handler func(c *Context) error
+
+// Predicate reports whether a Handler should run for an update. A Handler runs
+// only if all of its predicates return true.
+type Predicate func(u *Update) bool
+
+// Middleware wraps a Handler, returning a new one. Middleware registered with
+// Bot.Use runs for every handled update, outermost first.
+type Middleware func(next Handler) Handler
+
+type route struct {
+	handler    Handler
+	predicates []Predicate
+}
+
+func (r route) matches(u *Update) bool {
+	for _, p := range r.predicates {
+		if !p(u) {
+			return false
+		}
+	}
+	return true
+}
+
+// router holds the registered routes and global middleware. The zero value is
+// ready to use and safe for concurrent registration and routing.
+type router struct {
+	mu     sync.RWMutex
+	routes []route
+	mws    []Middleware
+}
+
+// Use registers global middleware applied to every handled update. Middleware
+// runs outermost-first in registration order. Call before Run.
+func (b *Bot) Use(mws ...Middleware) {
+	b.router.mu.Lock()
+	defer b.router.mu.Unlock()
+	b.router.mws = append(b.router.mws, mws...)
+}
+
+// on registers a handler guarded by the given predicates.
+func (b *Bot) on(handler Handler, predicates ...Predicate) {
+	b.router.mu.Lock()
+	defer b.router.mu.Unlock()
+	b.router.routes = append(b.router.routes, route{handler: handler, predicates: predicates})
+}
+
+// route dispatches an update to the first matching handler, wrapped in the
+// global middleware. Handler errors are logged, not propagated to the update
+// loop, so one failing handler does not tear down the bot.
+func (b *Bot) route(ctx context.Context, u *Update) {
+	b.router.mu.RLock()
+	routes := b.router.routes
+	mws := b.router.mws
+	b.router.mu.RUnlock()
+
+	for _, r := range routes {
+		if !r.matches(u) {
+			continue
+		}
+		h := r.handler
+		for i := len(mws) - 1; i >= 0; i-- {
+			h = mws[i](h)
+		}
+		c := &Context{Context: ctx, Bot: b, Update: u}
+		if err := h(c); err != nil {
+			b.log.Error("Handler error", zap.Error(err))
+		}
+		return
+	}
+}

handler_test.go

@@ -0,0 +1,60 @@
+package botapi
+
+import (
+	"context"
+	"errors"
+	"testing"
+)
+
+func TestRouterFirstMatchWins(t *testing.T) {
+	b := newTestBot(t)
+	var calls []string
+	b.on(func(c *Context) error { calls = append(calls, "skipped"); return nil }, func(u *Update) bool { return false })
+	b.on(func(c *Context) error { calls = append(calls, "matched"); return nil })
+	b.on(func(c *Context) error { calls = append(calls, "second-match"); return nil })
+
+	b.route(context.Background(), &Update{UpdateID: 1})
+
+	if len(calls) != 1 || calls[0] != "matched" {
+		t.Fatalf("expected only the first matching handler, got %v", calls)
+	}
+}
+
+func TestMiddlewareOrder(t *testing.T) {
+	b := newTestBot(t)
+	var order []string
+	b.Use(func(next Handler) Handler {
+		return func(c *Context) error {
+			order = append(order, "outer-in")
+			defer func() { order = append(order, "outer-out") }()
+			return next(c)
+		}
+	})
+	b.Use(func(next Handler) Handler {
+		return func(c *Context) error {
+			order = append(order, "inner-in")
+			defer func() { order = append(order, "inner-out") }()
+			return next(c)
+		}
+	})
+	b.on(func(c *Context) error { order = append(order, "handler"); return nil })
+
+	b.route(context.Background(), &Update{})
+
+	want := []string{"outer-in", "inner-in", "handler", "inner-out", "outer-out"}
+	if len(order) != len(want) {
+		t.Fatalf("order = %v, want %v", order, want)
+	}
+	for i := range want {
+		if order[i] != want[i] {
+			t.Fatalf("order = %v, want %v", order, want)
+		}
+	}
+}
+
+func TestRouterHandlerErrorIsContained(t *testing.T) {
+	b := newTestBot(t)
+	b.on(func(c *Context) error { return errors.New("boom") })
+	// Must not panic or propagate; the error is logged.
+	b.route(context.Background(), &Update{})
+}