Add FirstMatch routing strategy (#47)

* move RoutableHandler to separate file routable_handler.go

* first match handler

* move RoutableHandler back to router.go

* fix

* add First Match Routing section to README.md

* make IsMatch method private

* rename methods AttrIs -> AttrValueIs, AttrKeyTypeIs -> AttrKindIs

* transmit firstMatch value in Add method

* transmit skipPredicates forward while clone RoutableHandler

* fix stop lose handler attributes

* FirstMatch to clone RoutableHandler attributes to prevent double matching

* FirstMatch wrap Handle under try

* stop double clone slice attrs & groups in WithAttr & withGroup

* fix & test

---------

Co-authored-by: sasha <sasha@MacBook-Air-sasha.local>

Author: sashaaro

README.md

@@ -15,6 +15,7 @@
 
 - **🔄 Fanout**: Distribute logs to multiple handlers in parallel
 - **🛣️ Router**: Conditionally route logs based on custom criteria
+- **🎯 First Match**: Route logs to the first matching handler only
 - **🔄 Failover**: High-availability logging with automatic fallback
 - **⚖️ Load Balancing**: Distribute load across multiple handlers
 - **🔗 Pipeline**: Transform and filter logs with middleware chains
@@ -224,6 +225,60 @@ func recordMatchRegion(region string) func(ctx context.Context, r slog.Record) b
 - Level-based routing (errors to Slack, info to console)
 - Business logic routing (user actions vs system events)
 
+### First Match Routing: `Router().FirstMatch()`
+
+Route logs to the **first matching handler only**, unlike regular routing which sends to all matching handlers. Perfect for priority-based routing where you want exactly one handler to receive each log.
+
+```go
+import (
+    slogmulti "github.com/samber/slog-multi"
+    slogslack "github.com/samber/slog-slack"
+    "log/slog"
+)
+
+func main() {
+    queryChannel := slogslack.Option{Level: slog.LevelDebug, WebhookURL: "xxx", Channel: "db-queries"}.NewSlackHandler()
+    requestChannel := slogslack.Option{Level: slog.LevelError, WebhookURL: "xxx", Channel: "service-requests"}.NewSlackHandler()
+    influxdbChannel := slogslack.Option{Level: slog.LevelInfo, WebhookURL: "xxx", Channel: "influxdb-metrics"}.NewSlackHandler()
+    fallbackChannel := slogslack.Option{Level: slog.LevelError, WebhookURL: "xxx", Channel: "logs"}.NewSlackHandler()
+
+    logger := slog.New(
+        slogmulti.Router().
+            Add(queryChannel, slogmulti.AttrKindIs("query", slog.KindString, "args", slog.KindAny)).
+            Add(requestChannel, slogmulti.AttrKindIs("method", slog.KindString, "body", slog.KindAny)).
+            Add(influxdbChannel, slogmulti.AttrValueIs("scope", "influx")).
+            Add(fallbackChannel).  // Catch-all for everything else
+            FirstMatch().           // ← Enable first-match routing
+            Handler(),
+    )
+
+    // Goes to queryChannel only (stops at first match)
+    logger.Debug("Executing SQL query", "query", "SELECT * FROM users WHERE id = ?", "args", []int{1})
+
+    // Goes to requestChannel only (stops at first match)
+    logger.Error("Incoming request failed", "method", "POST", "body", "{'name':'test'}")
+
+    // Goes to fallbackChannel (no other handlers matched)
+    logger.Error("An unexpected error occurred")
+}
+```
+
+#### Built-in Predicates
+
+**Level predicates:**
+- `LevelIs(levels ...slog.Level)` - Match specific log levels
+- `LevelIsNot(levels ...slog.Level)` - Exclude specific log levels
+
+**Message predicates:**
+- `MessageIs(msg string)` - Exact message match
+- `MessageIsNot(msg string)` - Message doesn't match
+- `MessageContains(part string)` - Message contains substring
+- `MessageNotContains(part string)` - Message doesn't contain substring
+
+**Attribute predicates:**
+- `AttrValueIs(key, value, ...)` - Check attributes have exact values
+- `AttrKindIs(key, kind, ...)` - Check attributes have specific types
+
 ### Failover: `slogmulti.Failover()`
 
 Ensure logging reliability by trying multiple handlers in order until one succeeds. Perfect for high-availability scenarios.

examples/firstmatch/example.go

@@ -0,0 +1,36 @@
+package main
+
+import (
+	"context"
+
+	"log/slog"
+
+	slogmulti "github.com/samber/slog-multi"
+	slogslack "github.com/samber/slog-slack"
+)
+
+func main() {
+	queryChannel := slogslack.Option{Level: slog.LevelDebug, WebhookURL: "xxx", Channel: "db queries"}.NewSlackHandler()
+	requestChannel := slogslack.Option{Level: slog.LevelError, WebhookURL: "xxx", Channel: "service requests"}.NewSlackHandler()
+	influxdbChannel := slogslack.Option{Level: slog.LevelInfo, WebhookURL: "xxx", Channel: "influxdb metrics"}.NewSlackHandler()
+	fallbackChannel := slogslack.Option{Level: slog.LevelError, WebhookURL: "xxx", Channel: "logs"}.NewSlackHandler()
+
+	logger := slog.New(
+		slogmulti.Router().
+			Add(influxdbChannel, slogmulti.AttrValueIs("scope", "influx")).
+			Add(queryChannel, slogmulti.AttrKindIs("query", slog.KindString, "args", slog.KindAny)).
+			Add(requestChannel, slogmulti.AttrKindIs("method", slog.KindString, "body", slog.KindAny)).
+			Add(fallbackChannel).
+			FirstMatch().
+			Handler(),
+	)
+
+	logger.Debug("Executing SQL query", "query", "SELECT * FROM users WHERE id = ?", "args", []int{1})
+	logger.Error("Incoming request failed", "method", "POST", "body", "{'name':'test'}")
+	logger.Error("An unexpected error occurred")
+
+	influxLogger := logger.With("scope", "influx")
+
+	// influx.NewClient(influxLogger) ...
+	influxLogger.Info("InfluxDB client initialized")
+}

examples/firstmatch/go.mod

@@ -0,0 +1,18 @@
+module github.com/samber/slog-multi/examples/firstmatch
+
+go 1.21
+
+require (
+	github.com/samber/slog-multi v1.0.0
+	github.com/samber/slog-slack v1.0.0
+)
+
+require (
+	github.com/gorilla/websocket v1.4.2 // indirect
+	github.com/samber/lo v1.51.0 // indirect
+	github.com/samber/slog-common v0.19.0 // indirect
+	github.com/slack-go/slack v0.12.1 // indirect
+	golang.org/x/text v0.22.0 // indirect
+)
+
+replace github.com/samber/slog-multi => ../../

firstmatch.go

@@ -0,0 +1,96 @@
+package slogmulti
+
+import (
+	"context"
+	"log/slog"
+	"slices"
+
+	"github.com/samber/lo"
+)
+
+// Ensure FirstMatchHandler implements the slog.Handler interface at compile time
+var _ slog.Handler = (*FirstMatchHandler)(nil)
+
+type FirstMatchHandler struct {
+	handlers []*RoutableHandler
+}
+
+func FirstMatch(handlers ...*RoutableHandler) *FirstMatchHandler {
+	return &FirstMatchHandler{handlers: lo.Map(handlers, func(h *RoutableHandler, _ int) *RoutableHandler {
+		return &RoutableHandler{
+			predicates:     h.predicates,
+			handler:        h.handler,
+			groups:         slices.Clone(h.groups),
+			attrs:          slices.Clone(h.attrs),
+			skipPredicates: true, // prevent double matching
+		}
+	})}
+}
+
+// Enabled checks if any of the underlying handlers are enabled for the given log level.
+// This method implements the slog.Handler interface requirement.
+// See FanoutHandler.WithAttrs for details.
+func (h *FirstMatchHandler) Enabled(ctx context.Context, l slog.Level) bool {
+	for i := range h.handlers {
+		if h.handlers[i].Enabled(ctx, l) {
+			return true
+		}
+	}
+
+	return false
+}
+
+// Handle distributes a log record to the first matching handler.
+// This method implements the slog.Handler interface requirement.
+//
+// The method:
+// 1. Iterates through each child handler.
+// 2. Checks if the handler's predicates match the record.
+// 3. If a match is found, it checks if the handler is enabled for the record's level.
+// 4. If enabled, it forwards the record to that handler and returns.
+// 5. If no handlers match, it returns nil.
+func (h *FirstMatchHandler) Handle(ctx context.Context, r slog.Record) error {
+	for i := range h.handlers {
+		record, ok := h.handlers[i].isMatch(ctx, r)
+		if ok {
+			if h.handlers[i].Enabled(ctx, record.Level) {
+				return try(func() error {
+					return h.handlers[i].Handle(ctx, r)
+				})
+			}
+
+			return nil // Handler matched but is not enabled; do not proceed further
+		}
+	}
+
+	return nil
+}
+
+// WithAttrs creates a new FirstMatchHandler with additional attributes added to all child handlers.
+// This method implements the slog.Handler interface requirement.
+// See FanoutHandler.WithAttrs for details.
+func (h *FirstMatchHandler) WithAttrs(attrs []slog.Attr) slog.Handler {
+	handlers := lo.Map(h.handlers, func(h *RoutableHandler, _ int) *RoutableHandler {
+		return h.WithAttrs(slices.Clone(attrs)).(*RoutableHandler)
+	})
+	return newFirstMatch(handlers...)
+}
+
+// WithGroup creates a new FirstMatchHandler with a group name applied to all child handlers.
+// This method implements the slog.Handler interface requirement.
+// See FanoutHandler.WithGroup for details.
+func (h *FirstMatchHandler) WithGroup(name string) slog.Handler {
+	// https://cs.opensource.google/go/x/exp/+/46b07846:slog/handler.go;l=247
+	if name == "" {
+		return h
+	}
+
+	handlers := lo.Map(h.handlers, func(h *RoutableHandler, _ int) *RoutableHandler {
+		return h.WithGroup(name).(*RoutableHandler)
+	})
+	return newFirstMatch(handlers...)
+}
+
+func newFirstMatch(handlers ...*RoutableHandler) *FirstMatchHandler {
+	return &FirstMatchHandler{handlers: handlers}
+}

firstmatch_test.go

@@ -0,0 +1,92 @@
+package slogmulti
+
+import (
+	"bytes"
+	"log/slog"
+	"strings"
+	"testing"
+)
+
+var remoteTimeReplaceAttr = func(groups []string, a slog.Attr) slog.Attr {
+	if a.Key == slog.TimeKey {
+		return slog.Attr{}
+	}
+	return a
+}
+
+func TestFirstMatch(t *testing.T) {
+	t.Parallel()
+
+	t.Run("routes to first matching handler", func(t *testing.T) {
+		queryBuf := bytes.NewBufferString("")
+
+		queryH := slog.NewTextHandler(queryBuf, &slog.HandlerOptions{
+			Level:       slog.LevelInfo,
+			ReplaceAttr: remoteTimeReplaceAttr,
+		})
+
+		commonBuf := bytes.NewBufferString("")
+		commonH := slog.NewTextHandler(commonBuf, &slog.HandlerOptions{
+			Level:       slog.LevelDebug,
+			ReplaceAttr: remoteTimeReplaceAttr,
+		})
+
+		handler := Router().
+			Add(queryH, AttrKindIs("query", slog.KindString, "args", slog.KindAny)).
+			Add(commonH).
+			FirstMatch().
+			Handler()
+
+		logger := slog.New(handler).With("user_id", 123)
+		// Test 1: Log matching first handler should only go to queryBuf
+		logger.Info("get user by id", "query", "SELECT * FROM users id = ?", "args", []int{1})
+		// Test 2: Debug level filtered by queryH, should not match any handler
+		logger.Debug("get users", "query", "SELECT * FROM users", "args", []int{})
+		// Test 3: Log not matching first handler should go to commonBuf
+		logger.Warn("cache miss", "key", "user_1")
+
+		if strings.TrimSpace(queryBuf.String()) != `level=INFO msg="get user by id" user_id=123 query="SELECT * FROM users id = ?" args=[1]` {
+			t.Fatalf("query log buffer did not match")
+		}
+
+		if strings.TrimSpace(commonBuf.String()) != `level=WARN msg="cache miss" user_id=123 key=user_1` {
+			t.Fatalf("common log buffer did not match")
+		}
+	})
+
+	t.Run("stops at first match", func(t *testing.T) {
+		buf1, buf2, buf3 := bytes.NewBufferString(""), bytes.NewBufferString(""), bytes.NewBufferString("")
+
+		h1 := slog.NewTextHandler(buf1, &slog.HandlerOptions{
+			ReplaceAttr: remoteTimeReplaceAttr,
+		})
+		h2 := slog.NewTextHandler(buf2, &slog.HandlerOptions{
+			ReplaceAttr: remoteTimeReplaceAttr,
+		})
+		h3 := slog.NewTextHandler(buf3, &slog.HandlerOptions{
+			Level:       slog.LevelDebug,
+			ReplaceAttr: remoteTimeReplaceAttr,
+		})
+
+		handler := Router().
+			Add(h1, AttrValueIs("type", "error")).
+			Add(h2, AttrValueIs("type", "error")). // Also matches, but should not receive
+			Add(h3). // Fallback handler
+			FirstMatch().
+			Handler()
+
+		logger := slog.New(handler).With("user_id", 123)
+		logger.Info("test", "type", "error")
+		logger.Debug("other_log", "type", "not_error")
+
+		if buf1.String() != "level=INFO msg=test user_id=123 type=error\n" {
+			t.Errorf("expected buf1 to contain log")
+		}
+		if buf2.Len() != 0 {
+			t.Errorf("expected buf2 to NOT contain log (should stop at first match)")
+		}
+		if buf3.String() != "level=DEBUG msg=other_log user_id=123 type=not_error\n" {
+			t.Errorf("expected buf3 to contain log")
+		}
+	})
+}