Merge pull request #15 from StudioLambda/refactor/correlation-package

refactor(framework): extract correlation into dedicated package

Author: ConsoleTVs

.agents/skills/lambda-cosmos/SKILL.md

@@ -172,6 +172,14 @@ middleware.HTTP(stdlibMiddleware)        // adapt stdlib middleware
 
 ## Subpackages
 
+### Correlation
+
+```go
+app.Use(correlation.Middleware())           // ensures correlation ID on every request
+logger := slog.New(correlation.Handler(h))  // injects correlation_id into log records
+id := correlation.From(r)                   // retrieve from request context
+```
+
 ### Sessions
 
 ```go

.agents/skills/lambda-cosmos/references/framework.md

@@ -76,6 +76,7 @@ func (handler Handler) ServeHTTP(w http.ResponseWriter, r *http.Request) {
 ```
 
 Key points:
+
 - Uses `errors.As` (not type assertions) for wrapped error support.
 - `problem.Problem` implements both `HTTPStatus` and `http.Handler`,
   so it takes the `http.Handler` branch and renders itself.
@@ -304,17 +305,17 @@ func handler(w http.ResponseWriter, r *http.Request) error {
 - Sessions are loaded from the driver at the start of each request.
 - Changes are persisted via a BeforeWriteHeader hook (fires just
   before the HTTP status line).
-- New sessions get a UUID v7 ID and are marked as changed.
+- New sessions get a unique ID and are marked as changed.
 - `ExpirationDelta` controls automatic session extension: if the
   session expires within `delta` of the current time, it is
   automatically extended.
 
 ### Constants
 
-| Constant | Value |
-|---|---|
-| `DefaultCookie` | `"cosmos.session"` |
-| `DefaultTTL` | `2 * time.Hour` |
+| Constant                 | Value              |
+| ------------------------ | ------------------ |
+| `DefaultCookie`          | `"cosmos.session"` |
+| `DefaultTTL`             | `2 * time.Hour`    |
 | `DefaultExpirationDelta` | `15 * time.Minute` |
 
 ---
@@ -414,6 +415,7 @@ The nonce is randomly generated for each `Encrypt` call and prepended
 to the output. `Decrypt` reads the nonce from the front.
 
 Sentinel errors:
+
 - `crypto.ErrMismatchedAESNonceSize` — ciphertext too short for AES.
 - `crypto.ErrMismatchedChaCha20NonceSize` — ciphertext too short for
   ChaCha20.
@@ -525,13 +527,13 @@ Package: `github.com/studiolambda/cosmos/framework/event`
 
 ### Broker Implementations
 
-| Broker | Backend | Constructor |
-|---|---|---|
-| `MemoryBroker` | In-memory | `NewMemoryBroker()` |
-| `RedisBroker` | Redis Pub/Sub | `NewRedisBroker(options)` |
-| `NATSBroker` | NATS | `NewNATSBroker(url)` |
-| `AMQPBroker` | RabbitMQ | `NewAMQPBroker(url)` |
-| `MQTTBroker` | MQTT v5 | `NewMQTTBroker(url)` |
+| Broker         | Backend       | Constructor               |
+| -------------- | ------------- | ------------------------- |
+| `MemoryBroker` | In-memory     | `NewMemoryBroker()`       |
+| `RedisBroker`  | Redis Pub/Sub | `NewRedisBroker(options)` |
+| `NATSBroker`   | NATS          | `NewNATSBroker(url)`      |
+| `AMQPBroker`   | RabbitMQ      | `NewAMQPBroker(url)`      |
+| `MQTTBroker`   | MQTT v5       | `NewMQTTBroker(url)`      |
 
 All implement `contract.Events`.
 
@@ -558,11 +560,11 @@ err := broker.Publish(ctx, "user.42.created", user)
 
 ### Wildcard Syntax
 
-| Pattern | Meaning | MemoryBroker | Redis | NATS | AMQP | MQTT |
-|---|---|---|---|---|---|---|
-| `*` | Single token | `*` | `*` | `*` | `*` | `+` (auto-converted) |
-| `#` | Zero or more tokens | `#` | `*` (auto-converted) | `>` (auto-converted) | `#` | `#` |
-| `.` | Token separator | `.` | `.` | `.` | `.` | `/` (auto-converted) |
+| Pattern | Meaning             | MemoryBroker | Redis                | NATS                 | AMQP | MQTT                 |
+| ------- | ------------------- | ------------ | -------------------- | -------------------- | ---- | -------------------- |
+| `*`     | Single token        | `*`          | `*`                  | `*`                  | `*`  | `+` (auto-converted) |
+| `#`     | Zero or more tokens | `#`          | `*` (auto-converted) | `>` (auto-converted) | `#`  | `#`                  |
+| `.`     | Token separator     | `.`          | `.`                  | `.`                  | `.`  | `/` (auto-converted) |
 
 Write patterns using `*` and `#` with `.` separators. The broker
 translates to the native wildcard syntax automatically.

AGENTS.md

@@ -150,6 +150,12 @@ Available in `framework/middleware`:
 - `Provide(key, value)` / `ProvideWith(fn)` — context injection
 - `HTTP(func(http.Handler) http.Handler)` — stdlib middleware adapter
 
+Correlation ID in `framework/correlation`:
+
+- `Middleware()` / `MiddlewareWith(opts)` — ensures every request has a correlation ID (W3C traceparent, header, or generated)
+- `Handler(next)` — slog handler decorator that injects correlation ID into log records
+- `From(r)` — retrieves correlation ID from request context
+
 Session middleware in `framework/session`:
 
 - `Middleware(driver)` / `MiddlewareWith(driver, opts)` — session lifecycle
@@ -220,6 +226,7 @@ Session middleware in `framework/session`:
 - Framework hooks: framework/hooks.go, framework/hooks_writer.go
 - Router: router/router.go
 - Problem: problem/problem.go
+- Correlation: framework/correlation/middleware.go, framework/correlation/handler.go
 - Middleware: framework/middleware/\*.go
 - Session: framework/session/\*.go
 - Cache: framework/cache/memory.go, framework/cache/redis.go

contract/correlation.go

@@ -0,0 +1,8 @@
+package contract
+
+// correlationIDKey is a private type used as a context key to avoid collisions.
+type correlationIDKey struct{}
+
+// CorrelationIDKey is the context key used to store and retrieve
+// the correlation ID from a context.Context.
+var CorrelationIDKey = correlationIDKey{}

contract/request/correlation_id.go

@@ -0,0 +1,16 @@
+package request
+
+import (
+	"net/http"
+
+	"github.com/studiolambda/cosmos/contract"
+)
+
+// CorrelationID retrieves the correlation ID from the request
+// context. Returns an empty string if no correlation ID middleware
+// was applied to the request.
+func CorrelationID(r *http.Request) string {
+	id, _ := r.Context().Value(contract.CorrelationIDKey).(string)
+
+	return id
+}

contract/request/correlation_id_test.go

@@ -0,0 +1,29 @@
+package request_test
+
+import (
+	"context"
+	"net/http/httptest"
+	"testing"
+
+	"github.com/studiolambda/cosmos/contract"
+	"github.com/studiolambda/cosmos/contract/request"
+
+	"github.com/stretchr/testify/require"
+)
+
+func TestCorrelationIDReturnsValueFromContext(t *testing.T) {
+	t.Parallel()
+
+	ctx := context.WithValue(context.Background(), contract.CorrelationIDKey, "abc123")
+	r := httptest.NewRequest("GET", "/", nil).WithContext(ctx)
+
+	require.Equal(t, "abc123", request.CorrelationID(r))
+}
+
+func TestCorrelationIDReturnsEmptyWhenMissing(t *testing.T) {
+	t.Parallel()
+
+	r := httptest.NewRequest("GET", "/", nil)
+
+	require.Empty(t, request.CorrelationID(r))
+}

framework/correlation/handler.go

@@ -0,0 +1,60 @@
+package correlation
+
+import (
+	"context"
+	"log/slog"
+
+	"github.com/studiolambda/cosmos/contract"
+)
+
+// Handler wraps a [slog.Handler] to automatically
+// include the correlation ID in every log record whose context
+// carries one. This enables transparent correlation ID propagation
+// across all log calls without requiring manual attribute injection.
+//
+// Usage: wrap your existing handler when constructing the logger:
+//
+//	handler := slog.NewJSONHandler(os.Stdout, nil)
+//	logger := slog.New(correlation.Handler(handler))
+//
+// Then use context-aware logging methods in your handlers:
+//
+//	logger.InfoContext(r.Context(), "processing request")
+//	// Output automatically includes: correlation_id=<value>
+//
+// If no correlation ID is present in the context, the log record
+// is passed through unmodified.
+func Handler(next slog.Handler) slog.Handler {
+	return handler{next: next}
+}
+
+// handler is a [slog.Handler] decorator that enriches
+// log records with the correlation ID from context.
+type handler struct {
+	next slog.Handler
+}
+
+// Enabled delegates to the wrapped handler.
+func (handler handler) Enabled(ctx context.Context, level slog.Level) bool {
+	return handler.next.Enabled(ctx, level)
+}
+
+// Handle adds the correlation ID attribute to the record if present
+// in the context, then delegates to the wrapped handler.
+func (handler handler) Handle(ctx context.Context, record slog.Record) error {
+	if id, ok := ctx.Value(contract.CorrelationIDKey).(string); ok && id != "" {
+		record.AddAttrs(slog.String("correlation_id", id))
+	}
+
+	return handler.next.Handle(ctx, record)
+}
+
+// WithAttrs returns a new handler with the given attributes.
+func (handler handler) WithAttrs(attrs []slog.Attr) slog.Handler {
+	return Handler(handler.next.WithAttrs(attrs))
+}
+
+// WithGroup returns a new handler with the given group name.
+func (handler handler) WithGroup(name string) slog.Handler {
+	return Handler(handler.next.WithGroup(name))
+}

framework/correlation/handler_test.go

@@ -0,0 +1,118 @@
+package correlation_test
+
+import (
+	"bytes"
+	"context"
+	"log/slog"
+	"testing"
+
+	"github.com/studiolambda/cosmos/contract"
+	"github.com/studiolambda/cosmos/framework/correlation"
+
+	"github.com/stretchr/testify/require"
+)
+
+func TestHandlerAddsIDFromContext(t *testing.T) {
+	t.Parallel()
+
+	var buf bytes.Buffer
+	handler := correlation.Handler(slog.NewTextHandler(&buf, nil))
+	logger := slog.New(handler)
+
+	ctx := context.WithValue(context.Background(), contract.CorrelationIDKey, "trace-abc-123")
+	logger.InfoContext(ctx, "test message")
+
+	output := buf.String()
+	require.Contains(t, output, "correlation_id")
+	require.Contains(t, output, "trace-abc-123")
+}
+
+func TestHandlerOmitsWhenMissing(t *testing.T) {
+	t.Parallel()
+
+	var buf bytes.Buffer
+	handler := correlation.Handler(slog.NewTextHandler(&buf, nil))
+	logger := slog.New(handler)
+
+	logger.InfoContext(context.Background(), "test message")
+
+	output := buf.String()
+	require.NotContains(t, output, "correlation_id")
+}
+
+func TestHandlerOmitsWhenEmpty(t *testing.T) {
+	t.Parallel()
+
+	var buf bytes.Buffer
+	handler := correlation.Handler(slog.NewTextHandler(&buf, nil))
+	logger := slog.New(handler)
+
+	ctx := context.WithValue(context.Background(), contract.CorrelationIDKey, "")
+	logger.InfoContext(ctx, "test message")
+
+	output := buf.String()
+	require.NotContains(t, output, "correlation_id")
+}
+
+func TestHandlerPreservesExistingAttrs(t *testing.T) {
+	t.Parallel()
+
+	var buf bytes.Buffer
+	handler := correlation.Handler(slog.NewTextHandler(&buf, nil))
+	logger := slog.New(handler)
+
+	ctx := context.WithValue(context.Background(), contract.CorrelationIDKey, "id-456")
+	logger.InfoContext(ctx, "test", "extra", "value")
+
+	output := buf.String()
+	require.Contains(t, output, "correlation_id")
+	require.Contains(t, output, "id-456")
+	require.Contains(t, output, "extra")
+	require.Contains(t, output, "value")
+}
+
+func TestHandlerWithAttrsPreservesWrapping(t *testing.T) {
+	t.Parallel()
+
+	var buf bytes.Buffer
+	handler := correlation.Handler(slog.NewTextHandler(&buf, nil))
+	logger := slog.New(handler).With("service", "api")
+
+	ctx := context.WithValue(context.Background(), contract.CorrelationIDKey, "id-789")
+	logger.InfoContext(ctx, "test")
+
+	output := buf.String()
+	require.Contains(t, output, "service")
+	require.Contains(t, output, "api")
+	require.Contains(t, output, "correlation_id")
+	require.Contains(t, output, "id-789")
+}
+
+func TestHandlerWithGroupPreservesWrapping(t *testing.T) {
+	t.Parallel()
+
+	var buf bytes.Buffer
+	handler := correlation.Handler(slog.NewTextHandler(&buf, nil))
+	logger := slog.New(handler).WithGroup("request")
+
+	ctx := context.WithValue(context.Background(), contract.CorrelationIDKey, "id-group")
+	logger.InfoContext(ctx, "test")
+
+	output := buf.String()
+	require.Contains(t, output, "id-group")
+}
+
+func TestHandlerRespectsLevel(t *testing.T) {
+	t.Parallel()
+
+	var buf bytes.Buffer
+	handler := correlation.Handler(
+		slog.NewTextHandler(&buf, &slog.HandlerOptions{Level: slog.LevelError}),
+	)
+	logger := slog.New(handler)
+
+	ctx := context.WithValue(context.Background(), contract.CorrelationIDKey, "id-level")
+	logger.InfoContext(ctx, "should not appear")
+
+	require.Empty(t, buf.String())
+}