I. Chain of Responsibility — Behavioral Pattern

The Chain of Responsibility pattern lets you pass requests along a chain of handlers. Each handler decides either to process the request or to forward it to the next handler in the chain.

This pattern decouples the sender of a request from its receivers by giving more than one object a chance to handle the request. It avoids coupling the sender to a specific receiver and allows you to build flexible pipelines at runtime.

The pattern is especially powerful in middleware-style architectures — authentication, rate limiting, logging, caching — where each concern can be isolated into its own handler and composed in any order.

II. Real-world Example

Imagine an HTTP client pipeline with three middleware layers:

1. AuthHandler — checks that a valid token is present. If the token is empty, it immediately rejects the request.

2. RateLimitHandler — uses an atomic counter to enforce a maximum number of concurrent requests. Excess requests are dropped without reaching the network.

3. FetchHandler — the terminal handler that actually performs the HTTP call and returns the response.

Each handler knows only about the next one. The client that kicks off the chain has no idea how many handlers exist or what they do.

III. Implementation

handler.go — the Handler interface and BaseHandler embed:

1package chain
2
3type Handler interface {
4	SetNext(handler Handler) Handler
5	Handle(url string) (interface{}, error)
6}
7
8type BaseHandler struct {
9	next Handler
10}
11
12func (h *BaseHandler) SetNext(handler Handler) Handler {
13	h.next = handler
14	return handler
15}
16
17func (h *BaseHandler) nextHandle(url string) (interface{}, error) {
18	if h.next == nil {
19		return nil, nil
20	}
21	return h.next.Handle(url)
22}

auth_handler.go — validates the auth token:

1package chain
2
3import "errors"
4
5type AuthHandler struct {
6	BaseHandler
7	token string
8}
9
10func NewAuthHandler(token string) *AuthHandler {
11	return &AuthHandler{token: token}
12}
13
14func (h *AuthHandler) Handle(url string) (interface{}, error) {
15	if h.token == "" {
16		return nil, errors.New("missing auth token")
17	}
18	return h.nextHandle(url)
19}

rate_limit_handler.go — enforces concurrency limits atomically:

1package chain
2
3import (
4	"errors"
5	"sync/atomic"
6)
7
8type RateLimitHandler struct {
9	BaseHandler
10	limit   int64
11	current int64
12}
13
14func NewRateLimitHandler(limit int64) *RateLimitHandler {
15	return &RateLimitHandler{limit: limit}
16}
17
18func (h *RateLimitHandler) Handle(url string) (interface{}, error) {
19	if atomic.AddInt64(&h.current, 1) > h.limit {
20		atomic.AddInt64(&h.current, -1)
21		return nil, errors.New("rate limit exceeded")
22	}
23	result, err := h.nextHandle(url)
24	if err != nil {
25		atomic.AddInt64(&h.current, -1)
26	}
27	return result, err
28}

fetch_handler.go — the terminal handler that returns a response:

1package chain
2
3import "fmt"
4
5type FetchHandler struct {
6	BaseHandler
7}
8
9func NewFetchHandler() *FetchHandler {
10	return &FetchHandler{}
11}
12
13func (h *FetchHandler) Handle(url string) (interface{}, error) {
14	return fmt.Sprintf("response from %s", url), nil
15}

main.go — wiring the chain:

1auth := chain.NewAuthHandler("secret-token")
2rateLimit := chain.NewRateLimitHandler(2)
3fetch := chain.NewFetchHandler()
4
5auth.SetNext(rateLimit).SetNext(fetch)
6
7response, err := auth.Handle("https://example.com")
8if err != nil {
9    fmt.Println("Error:", err)
10} else {
11    fmt.Println("Response:", response)
12}
13
14_, err = chain.NewAuthHandler("").Handle("https://example.com")
15if err != nil {
16    fmt.Println("Auth error:", err)
17}

IV. Explain the example above

Step 1 — Build the chain

SetNext returns the handler it received, so you can chain calls fluently: auth → rateLimit → fetch. At this point no request has been sent yet.

Step 2 — Happy path request

1auth.Handle("https://example.com")
2  → token "secret-token" ✓ → calls rateLimit.Handle
3    → current=1 ≤ limit=2 ✓ → calls fetch.Handle
4      → returns "response from https://example.com"

Output:

Response: response from https://example.com

Step 3 — Missing token

1chain.NewAuthHandler("").Handle("https://example.com")
2  → token is empty → returns error immediately

Output:

Auth error: missing auth token

Step 4 — Rate limit exceeded

If three concurrent requests hit RateLimitHandler with limit=2, the third call atomically increments current to 3, sees it exceeds the limit, decrements back to 2, and returns an error — without ever reaching FetchHandler.

Rate limit error: rate limit exceeded

Notice how FetchHandler is completely unaware of auth or rate limiting. You can add, remove, or reorder handlers without touching the others.

V. Conclusion

When to use it:

• You need to process a request through multiple independent steps (middleware pipelines, validation chains, event processing).

• The set of handlers or their order may change at runtime.

• You want each handler to have a single responsibility.

When to avoid it:

• Every request must be handled — if no handler in the chain processes it, you get a silent nil, nil return. You need to design a fallback or terminal handler.

• Deep chains make debugging harder because the execution path is dynamic and not obvious from the call site.

• For simple linear transformations, a plain function slice (e.g., []Middleware) is often clearer and cheaper.

No pattern is universally superior. Chain of Responsibility shines when you need composable, open-ended pipelines — but keep the chain short and ensure every path has a defined outcome.

VI. References

• Go Design Patterns (Mario Castro Contreras)

• Source code on GitHub