feat(handler): add Recover, Timeout and Logging middleware

Recover turns a handler panic into a logged 500 error instead of crashing the
update loop; Timeout scopes the handler context to a deadline; Logging records
each handled update (warn on error, debug otherwise).

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

Author: ernado

middleware.go

@@ -0,0 +1,58 @@
+package botapi
+
+import (
+	"context"
+	"runtime/debug"
+	"time"
+
+	"go.uber.org/zap"
+)
+
+// Recover wraps a handler so a panic is recovered, logged with its stack, and
+// converted into an error instead of crashing the update loop.
+func Recover() Middleware {
+	return func(next Handler) Handler {
+		return func(c *Context) (err error) {
+			defer func() {
+				if r := recover(); r != nil {
+					c.Bot.log.Error("Recovered from panic in handler",
+						zap.Any("panic", r),
+						zap.ByteString("stack", debug.Stack()),
+					)
+					err = &Error{Code: 500, Description: "Internal Server Error: handler panicked"}
+				}
+			}()
+			return next(c)
+		}
+	}
+}
+
+// Timeout wraps a handler so its context is canceled after d.
+func Timeout(d time.Duration) Middleware {
+	return func(next Handler) Handler {
+		return func(c *Context) error {
+			ctx, cancel := context.WithTimeout(c.Context, d)
+			defer cancel()
+			scoped := *c
+			scoped.Context = ctx
+			return next(&scoped)
+		}
+	}
+}
+
+// Logging wraps a handler to log each handled update at debug level, and at warn
+// level when the handler returns an error.
+func Logging() Middleware {
+	return func(next Handler) Handler {
+		return func(c *Context) error {
+			err := next(c)
+			if err != nil {
+				c.Bot.log.Warn("Update handled with error",
+					zap.Int("update_id", c.Update.UpdateID), zap.Error(err))
+			} else {
+				c.Bot.log.Debug("Update handled", zap.Int("update_id", c.Update.UpdateID))
+			}
+			return err
+		}
+	}
+}

middleware_test.go

@@ -0,0 +1,38 @@
+package botapi
+
+import (
+	"context"
+	"errors"
+	"testing"
+	"time"
+)
+
+func TestRecoverMiddleware(t *testing.T) {
+	b := newTestBot(t)
+	h := Recover()(func(c *Context) error { panic("boom") })
+
+	err := h(&Context{Context: context.Background(), Bot: b, Update: &Update{}})
+	var apiErr *Error
+	if err == nil {
+		t.Fatal("Recover must convert a panic into an error")
+	}
+	if !errors.As(err, &apiErr) || apiErr.Code != 500 {
+		t.Fatalf("Recover should yield a 500 *Error, got %v", err)
+	}
+}
+
+func TestTimeoutMiddleware(t *testing.T) {
+	b := newTestBot(t)
+	var hasDeadline bool
+	h := Timeout(time.Minute)(func(c *Context) error {
+		_, hasDeadline = c.Deadline()
+		return nil
+	})
+
+	if err := h(&Context{Context: context.Background(), Bot: b, Update: &Update{}}); err != nil {
+		t.Fatal(err)
+	}
+	if !hasDeadline {
+		t.Fatal("Timeout should give the handler context a deadline")
+	}
+}