feat(handler): add handler Groups with scoped middleware

Routes now carry their own middleware, applied inside the global middleware.
Group bundles shared predicates and middleware: handlers registered via a group
inherit its predicates as additional guards and its middleware scope. Adds
Group.Use/Handle/OnMessage/OnCallbackQuery/OnCommand. Shared kind predicates are
factored out and reused by Bot.On* and Group.On*.

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

Author: ernado

group.go

@@ -0,0 +1,51 @@
+package botapi
+
+// Group is a set of handlers that share predicates and middleware. Every handler
+// registered through the group inherits the group's predicates (as additional
+// guards) and its middleware (applied inside the global middleware).
+//
+// Create one with Bot.Group:
+//
+//	admin := bot.Group(ChatTypeIs(ChatTypeSupergroup))
+//	admin.Use(Recover())
+//	admin.OnCommand("ban", banHandler)
+type Group struct {
+	bot   *Bot
+	preds []Predicate
+	mws   []Middleware
+}
+
+// Group returns a new handler group guarded by the given predicates.
+func (b *Bot) Group(predicates ...Predicate) *Group {
+	return &Group{bot: b, preds: predicates}
+}
+
+// Use adds middleware applied to every handler registered through this group.
+// Returns the group for chaining.
+func (g *Group) Use(mws ...Middleware) *Group {
+	g.mws = append(g.mws, mws...)
+	return g
+}
+
+// Handle registers a handler in the group with optional extra predicates.
+func (g *Group) Handle(h Handler, predicates ...Predicate) {
+	preds := make([]Predicate, 0, len(g.preds)+len(predicates))
+	preds = append(preds, g.preds...)
+	preds = append(preds, predicates...)
+	g.bot.onWith(h, g.mws, preds)
+}
+
+// OnMessage registers a message handler in the group.
+func (g *Group) OnMessage(h Handler, predicates ...Predicate) {
+	g.Handle(h, prepend(hasMessage, predicates)...)
+}
+
+// OnCallbackQuery registers a callback-query handler in the group.
+func (g *Group) OnCallbackQuery(h Handler, predicates ...Predicate) {
+	g.Handle(h, prepend(hasCallbackQuery, predicates)...)
+}
+
+// OnCommand registers a command handler in the group.
+func (g *Group) OnCommand(name string, h Handler, predicates ...Predicate) {
+	g.OnMessage(h, prepend(Command(name), predicates)...)
+}

group_test.go

@@ -0,0 +1,47 @@
+package botapi
+
+import (
+	"context"
+	"testing"
+)
+
+func TestGroupPredicatesGuardHandlers(t *testing.T) {
+	b := newTestBot(t)
+	var fired bool
+	g := b.Group(ChatTypeIs(ChatTypeSupergroup))
+	g.OnMessage(func(c *Context) error { fired = true; return nil })
+
+	// Wrong chat type: group predicate fails, handler must not fire.
+	b.route(context.Background(), &Update{Message: &Message{Chat: Chat{Type: ChatTypePrivate}}})
+	if fired {
+		t.Fatal("group predicate should have blocked the handler")
+	}
+
+	// Right chat type: handler fires.
+	b.route(context.Background(), &Update{Message: &Message{Chat: Chat{Type: ChatTypeSupergroup}}})
+	if !fired {
+		t.Fatal("handler should fire when group predicate matches")
+	}
+}
+
+func TestGroupMiddlewareScopedAndOrdered(t *testing.T) {
+	b := newTestBot(t)
+	var order []string
+	b.Use(func(next Handler) Handler {
+		return func(c *Context) error { order = append(order, "global"); return next(c) }
+	})
+	g := b.Group()
+	g.Use(func(next Handler) Handler {
+		return func(c *Context) error { order = append(order, "group"); return next(c) }
+	})
+	g.OnMessage(func(c *Context) error { order = append(order, "handler"); return nil })
+
+	b.route(context.Background(), &Update{Message: &Message{}})
+
+	want := []string{"global", "group", "handler"}
+	for i := range want {
+		if i >= len(order) || order[i] != want[i] {
+			t.Fatalf("order = %v, want %v (global outermost, group inside)", order, want)
+		}
+	}
+}

handler.go

@@ -30,6 +30,7 @@ type Middleware func(next Handler) Handler
 type route struct {
 	handler    Handler
 	predicates []Predicate
+	mws        []Middleware
 }
 
 func (r route) matches(u *Update) bool {
@@ -59,9 +60,15 @@ func (b *Bot) Use(mws ...Middleware) {
 
 // on registers a handler guarded by the given predicates.
 func (b *Bot) on(handler Handler, predicates ...Predicate) {
+	b.onWith(handler, nil, predicates)
+}
+
+// onWith registers a handler with route-scoped middleware (applied inside the
+// global middleware) and predicates.
+func (b *Bot) onWith(handler Handler, mws []Middleware, predicates []Predicate) {
 	b.router.mu.Lock()
 	defer b.router.mu.Unlock()
-	b.router.routes = append(b.router.routes, route{handler: handler, predicates: predicates})
+	b.router.routes = append(b.router.routes, route{handler: handler, predicates: predicates, mws: mws})
 }
 
 // route dispatches an update to the first matching handler, wrapped in the
@@ -78,6 +85,9 @@ func (b *Bot) route(ctx context.Context, u *Update) {
 			continue
 		}
 		h := r.handler
+		for i := len(r.mws) - 1; i >= 0; i-- {
+			h = r.mws[i](h)
+		}
 		for i := len(mws) - 1; i >= 0; i-- {
 			h = mws[i](h)
 		}

on.go

@@ -64,29 +64,37 @@ func (b *Bot) dispatchMessage(ctx context.Context, msg tg.MessageClass, edited b
 	b.route(ctx, u)
 }
 
+// Kind predicates select an update by which field it carries. They are shared
+// by Bot.On* and Group.On*.
+func hasMessage(u *Update) bool       { return u.Message != nil }
+func hasEditedMessage(u *Update) bool { return u.EditedMessage != nil }
+func hasChannelPost(u *Update) bool   { return u.ChannelPost != nil }
+func hasCallbackQuery(u *Update) bool { return u.CallbackQuery != nil }
+func hasInlineQuery(u *Update) bool   { return u.InlineQuery != nil }
+
 // OnMessage registers a handler for new messages matching the predicates.
 func (b *Bot) OnMessage(h Handler, predicates ...Predicate) {
-	b.on(h, prepend(func(u *Update) bool { return u.Message != nil }, predicates)...)
+	b.on(h, prepend(hasMessage, predicates)...)
 }
 
 // OnEditedMessage registers a handler for edited messages.
 func (b *Bot) OnEditedMessage(h Handler, predicates ...Predicate) {
-	b.on(h, prepend(func(u *Update) bool { return u.EditedMessage != nil }, predicates)...)
+	b.on(h, prepend(hasEditedMessage, predicates)...)
 }
 
 // OnChannelPost registers a handler for new channel posts.
 func (b *Bot) OnChannelPost(h Handler, predicates ...Predicate) {
-	b.on(h, prepend(func(u *Update) bool { return u.ChannelPost != nil }, predicates)...)
+	b.on(h, prepend(hasChannelPost, predicates)...)
 }
 
 // OnCallbackQuery registers a handler for callback queries from inline keyboards.
 func (b *Bot) OnCallbackQuery(h Handler, predicates ...Predicate) {
-	b.on(h, prepend(func(u *Update) bool { return u.CallbackQuery != nil }, predicates)...)
+	b.on(h, prepend(hasCallbackQuery, predicates)...)
 }
 
 // OnInlineQuery registers a handler for inline queries.
 func (b *Bot) OnInlineQuery(h Handler, predicates ...Predicate) {
-	b.on(h, prepend(func(u *Update) bool { return u.InlineQuery != nil }, predicates)...)
+	b.on(h, prepend(hasInlineQuery, predicates)...)
 }
 
 // prepend returns p followed by rest, without mutating rest.