groundwork-method 0.0.1 → 0.10.0

package/src/generators/go-microservice/files/internal/entrypoints/api/clerk_webhook.go.template

@@ -0,0 +1,202 @@
+package api
+
+import (
+	"encoding/json"
+	"fmt"
+	"io"
+	"net/http"
+	"time"
+
+	"github.com/rs/zerolog/log"
+	svix "github.com/svix/svix-webhooks/go"
+
+	"<%= name %>/internal/core/domain"
+	"<%= name %>/internal/core/service"
+)
+
+// clerkUserPayload is the relevant subset of a Clerk user webhook event payload.
+type clerkUserPayload struct {
+	ID             string  `json:"id"`
+	FirstName      string  `json:"first_name"`
+	LastName       string  `json:"last_name"`
+	Username       *string `json:"username"`
+	EmailAddresses []struct {
+		EmailAddress string `json:"email_address"`
+		ID           string `json:"id"`
+	} `json:"email_addresses"`
+	PrimaryEmailAddressID string `json:"primary_email_address_id"`
+}
+
+// clerkWebhookEvent wraps the Clerk webhook event envelope.
+type clerkWebhookEvent struct {
+	Type string          `json:"type"`
+	Data json.RawMessage `json:"data"`
+}
+
+// ClerkWebhookHandler returns an HTTP handler for Clerk webhook events.
+// The handler verifies the Svix signature and processes user lifecycle events.
+func ClerkWebhookHandler(userService *service.UserService, webhookSigningSecret string) http.HandlerFunc {
+	return func(w http.ResponseWriter, r *http.Request) {
+		if webhookSigningSecret == "" {
+			// Fail loud: the secret is unset, so the endpoint cannot verify any
+			// signature. Reject with a clear server-misconfiguration signal rather
+			// than processing or returning a misleading "invalid signature".
+			log.Error().Msg("CLERK_WEBHOOK_SIGNING_SECRET is not configured")
+			http.Error(w, "webhook not configured", http.StatusServiceUnavailable)
+			return
+		}
+
+		// Read the request body
+		body, err := io.ReadAll(r.Body)
+		if err != nil {
+			log.Error().Err(err).Msg("Failed to read webhook body")
+			http.Error(w, "failed to read body", http.StatusBadRequest)
+			return
+		}
+
+		// Verify the Svix signature
+		wh, err := svix.NewWebhook(webhookSigningSecret)
+		if err != nil {
+			log.Error().Err(err).Msg("Failed to create Svix webhook verifier")
+			http.Error(w, "internal error", http.StatusInternalServerError)
+			return
+		}
+
+		headers := http.Header{}
+		headers.Set("svix-id", r.Header.Get("svix-id"))
+		headers.Set("svix-timestamp", r.Header.Get("svix-timestamp"))
+		headers.Set("svix-signature", r.Header.Get("svix-signature"))
+
+		if err := wh.Verify(body, headers); err != nil {
+			log.Warn().Err(err).Msg("Webhook signature verification failed")
+			http.Error(w, "invalid signature", http.StatusBadRequest)
+			return
+		}
+
+		// Parse the event envelope
+		var event clerkWebhookEvent
+		if err := json.Unmarshal(body, &event); err != nil {
+			log.Error().Err(err).Msg("Failed to parse webhook event")
+			http.Error(w, "invalid payload", http.StatusBadRequest)
+			return
+		}
+
+		log.Info().Str("type", event.Type).Msg("Received Clerk webhook event")
+
+		switch event.Type {
+		case "user.created":
+			handleUserCreated(r, userService, event.Data)
+		case "user.updated":
+			handleUserUpdated(r, userService, event.Data)
+		case "user.deleted":
+			handleUserDeleted(r, userService, event.Data)
+		default:
+			log.Debug().Str("type", event.Type).Msg("Ignoring unhandled webhook event type")
+		}
+
+		w.WriteHeader(http.StatusOK)
+		_, _ = w.Write([]byte(`{"status":"ok"}`))
+	}
+}
+
+func handleUserCreated(r *http.Request, userService *service.UserService, data json.RawMessage) {
+	var payload clerkUserPayload
+	if err := json.Unmarshal(data, &payload); err != nil {
+		log.Error().Err(err).Msg("Failed to parse user.created payload")
+		return
+	}
+
+	email := primaryEmail(payload)
+	username := buildUsername(payload)
+	clerkID := payload.ID
+
+	now := time.Now().UTC()
+	user := &domain.User{
+		ClerkID:   clerkID,
+		Username:  username,
+		Email:     email,
+		CreatedAt: now,
+		UpdatedAt: now,
+	}
+
+	// Use Save (system principal) — idempotent: if user already exists by clerk_id, this is a retry.
+	err := userService.Save(r.Context(), user)
+	if err != nil {
+		log.Error().Err(err).Str("clerk_id", clerkID).Msg("Failed to create user from webhook")
+		return
+	}
+
+	log.Info().Str("clerk_id", clerkID).Str("email", email).Msg("User created via webhook")
+}
+
+func handleUserUpdated(r *http.Request, userService *service.UserService, data json.RawMessage) {
+	var payload clerkUserPayload
+	if err := json.Unmarshal(data, &payload); err != nil {
+		log.Error().Err(err).Msg("Failed to parse user.updated payload")
+		return
+	}
+
+	clerkID := payload.ID
+
+	// Look up existing user by Clerk ID
+	existing, err := userService.GetByClerkID(r.Context(), clerkID)
+	if err != nil {
+		log.Warn().Err(err).Str("clerk_id", clerkID).Msg("User not found for update webhook — skipping")
+		return
+	}
+
+	existing.Email = primaryEmail(payload)
+	existing.Username = buildUsername(payload)
+
+	if err := userService.Update(r.Context(), existing); err != nil {
+		log.Error().Err(err).Str("clerk_id", clerkID).Msg("Failed to update user from webhook")
+		return
+	}
+
+	log.Info().Str("clerk_id", clerkID).Msg("User updated via webhook")
+}
+
+func handleUserDeleted(r *http.Request, userService *service.UserService, data json.RawMessage) {
+	// For deleted events, Clerk sends a minimal payload with just the ID
+	var payload struct {
+		ID string `json:"id"`
+	}
+	if err := json.Unmarshal(data, &payload); err != nil {
+		log.Error().Err(err).Msg("Failed to parse user.deleted payload")
+		return
+	}
+
+	clerkID := payload.ID
+
+	if err := userService.DeleteByClerkID(r.Context(), clerkID); err != nil {
+		log.Error().Err(err).Str("clerk_id", clerkID).Msg("Failed to delete user from webhook")
+		return
+	}
+
+	log.Info().Str("clerk_id", clerkID).Msg("User deleted via webhook")
+}
+
+// primaryEmail extracts the primary email from the Clerk user payload.
+func primaryEmail(p clerkUserPayload) string {
+	for _, ea := range p.EmailAddresses {
+		if ea.ID == p.PrimaryEmailAddressID {
+			return ea.EmailAddress
+		}
+	}
+	if len(p.EmailAddresses) > 0 {
+		return p.EmailAddresses[0].EmailAddress
+	}
+	return ""
+}
+
+// buildUsername constructs a username from the Clerk user payload.
+func buildUsername(p clerkUserPayload) string {
+	if p.Username != nil && *p.Username != "" {
+		return *p.Username
+	}
+	name := fmt.Sprintf("%s %s", p.FirstName, p.LastName)
+	if name == " " {
+		return p.ID // Fallback to Clerk ID
+	}
+	return name
+}

package/src/generators/go-microservice/files/internal/entrypoints/api/clerk_webhook_test.go.template

@@ -0,0 +1,82 @@
+<% if (auth === 'clerk') { %>package api
+
+import (
+	"crypto/hmac"
+	"crypto/sha256"
+	"encoding/base64"
+	"fmt"
+	"net/http"
+	"net/http/httptest"
+	"strings"
+	"testing"
+	"time"
+
+	"github.com/stretchr/testify/require"
+)
+
+// testSecret is a Svix-format signing secret ("whsec_" + base64). The body of the
+// secret after the prefix must be valid base64 because the verifier decodes it.
+const testSecret = "whsec_MfKQ9r8GKYqrTwjUPD8ILPZIo2LaLaSw"
+
+// signSvix produces a valid v1 Svix signature for the given id/timestamp/payload,
+// matching what svix.Webhook.Verify expects: HMAC-SHA256 over "id.timestamp.body"
+// keyed by the base64-decoded secret, base64-encoded and prefixed with "v1,".
+func signSvix(t *testing.T, secret, msgID string, ts time.Time, payload []byte) string {
+	t.Helper()
+	secretBytes, err := base64.StdEncoding.DecodeString(strings.TrimPrefix(secret, "whsec_"))
+	require.NoError(t, err)
+	toSign := fmt.Sprintf("%s.%d.%s", msgID, ts.Unix(), string(payload))
+	mac := hmac.New(sha256.New, secretBytes)
+	_, _ = mac.Write([]byte(toSign))
+	sig := base64.StdEncoding.EncodeToString(mac.Sum(nil))
+	return "v1," + sig
+}
+
+func TestClerkWebhook_MissingSecretReturns503(t *testing.T) {
+	// An unset signing secret is a server misconfiguration: the handler fails loud
+	// with 503 rather than processing or returning a misleading "invalid signature".
+	h := ClerkWebhookHandler(nil, "")
+	rr := httptest.NewRecorder()
+	h.ServeHTTP(rr, httptest.NewRequest(http.MethodPost, "/webhooks/clerk", strings.NewReader("{}")))
+	require.Equal(t, http.StatusServiceUnavailable, rr.Code)
+}
+
+func TestClerkWebhook_MissingSignatureReturns400(t *testing.T) {
+	h := ClerkWebhookHandler(nil, testSecret)
+	rr := httptest.NewRecorder()
+	req := httptest.NewRequest(http.MethodPost, "/webhooks/clerk", strings.NewReader("{}"))
+	// No svix-* headers set.
+	h.ServeHTTP(rr, req)
+	require.Equal(t, http.StatusBadRequest, rr.Code)
+}
+
+func TestClerkWebhook_BadSignatureReturns400(t *testing.T) {
+	h := ClerkWebhookHandler(nil, testSecret)
+	rr := httptest.NewRecorder()
+	req := httptest.NewRequest(http.MethodPost, "/webhooks/clerk", strings.NewReader("{}"))
+	req.Header.Set("svix-id", "msg_test")
+	req.Header.Set("svix-timestamp", fmt.Sprintf("%d", time.Now().Unix()))
+	req.Header.Set("svix-signature", "v1,deadbeefnotavalidsignature")
+	h.ServeHTTP(rr, req)
+	require.Equal(t, http.StatusBadRequest, rr.Code)
+}
+
+func TestClerkWebhook_ValidSignatureReturns200(t *testing.T) {
+	// Use an unhandled event type so the handler verifies the signature and
+	// returns 200 without invoking the (nil) UserService.
+	payload := []byte(`{"type":"session.created","data":{}}`)
+	msgID := "msg_valid"
+	ts := time.Now()
+
+	h := ClerkWebhookHandler(nil, testSecret)
+	rr := httptest.NewRecorder()
+	req := httptest.NewRequest(http.MethodPost, "/webhooks/clerk", strings.NewReader(string(payload)))
+	req.Header.Set("svix-id", msgID)
+	req.Header.Set("svix-timestamp", fmt.Sprintf("%d", ts.Unix()))
+	req.Header.Set("svix-signature", signSvix(t, testSecret, msgID, ts, payload))
+	h.ServeHTTP(rr, req)
+
+	require.Equal(t, http.StatusOK, rr.Code)
+	require.Contains(t, rr.Body.String(), `"status":"ok"`)
+}
+<% } %>

package/src/generators/go-microservice/files/internal/entrypoints/api/health_handler.go.template

@@ -0,0 +1,80 @@
+package api
+
+import (
+	"context"
+
+	"github.com/danielgtaylor/huma/v2"
+<% if (websockets) { %>
+	"<%= name %>/internal/websocket"
+<% } %>
+)
+
+// DBPinger is satisfied by *postgres.DB (via its embedded *sql.DB) and test doubles.
+type DBPinger interface {
+	PingContext(ctx context.Context) error
+}
+
+type HealthCheck struct {
+	Status string `json:"status" example:"ok" enum:"ok,degraded"`
+	Checks struct {
+		DB  string `json:"db"  example:"ok" enum:"ok,error"`
+<% if (websockets) { %>
+		Hub string `json:"hub" example:"ok" enum:"ok,error"`
+<% } %>
+	} `json:"checks"`
+<% if (websockets) { %>
+	ConnectedUsers int `json:"connected_users"`
+<% } %>
+}
+
+type HealthResponse struct {
+	Body HealthCheck
+}
+
+<% if (websockets) { %>
+func RegisterHealthHandler(api huma.API, db DBPinger, hub *websocket.Hub) {
+<% } else { %>
+func RegisterHealthHandler(api huma.API, db DBPinger) {
+<% } %>
+	huma.Register(api, huma.Operation{
+		OperationID: "get-health",
+		Method:      "GET",
+		Path:        "/health",
+		Summary:     "Health check",
+		Description: "Check if the service is healthy",
+		Tags:        []string{"System"},
+	}, func(ctx context.Context, input *struct{}) (*HealthResponse, error) {
+		var body HealthCheck
+
+		// --- DB check ---
+		if err := db.PingContext(ctx); err != nil {
+			body.Checks.DB = "error"
+		} else {
+			body.Checks.DB = "ok"
+		}
+
+<% if (websockets) { %>
+		// --- Hub check ---
+		if hub != nil {
+			body.Checks.Hub = "ok"
+			body.ConnectedUsers = hub.ConnectedUsers()
+		} else {
+			body.Checks.Hub = "error"
+		}
+
+		if body.Checks.DB == "ok" && body.Checks.Hub == "ok" {
+			body.Status = "ok"
+		} else {
+			body.Status = "degraded"
+		}
+<% } else { %>
+		if body.Checks.DB == "ok" {
+			body.Status = "ok"
+		} else {
+			body.Status = "degraded"
+		}
+<% } %>
+
+		return &HealthResponse{Body: body}, nil
+	})
+}

package/src/generators/go-microservice/files/internal/entrypoints/api/idempotency/middleware.go.template

@@ -0,0 +1,87 @@
+package idempotency
+
+import (
+	"bytes"
+	"net/http"
+
+	"github.com/rs/zerolog/log"
+)
+
+// responseRecorder intercepts the HTTP response so we can store it.
+type responseRecorder struct {
+	http.ResponseWriter
+	status int
+	body   *bytes.Buffer
+}
+
+func (r *responseRecorder) WriteHeader(status int) {
+	r.status = status
+	r.ResponseWriter.WriteHeader(status)
+}
+
+func (r *responseRecorder) Write(b []byte) (int, error) {
+	r.body.Write(b)
+	return r.ResponseWriter.Write(b)
+}
+
+// Middleware ensures that POST/PUT/PATCH/DELETE requests containing an
+// Idempotency-Key header are executed exactly once.
+func Middleware(repo Repository) func(http.Handler) http.Handler {
+	return func(next http.Handler) http.Handler {
+		return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+			// Only apply to mutating requests
+			if r.Method == http.MethodGet || r.Method == http.MethodOptions {
+				next.ServeHTTP(w, r)
+				return
+			}
+
+			idemKey := r.Header.Get("Idempotency-Key")
+			if idemKey == "" {
+				// Not strict-enforced here to allow flexibility.
+				next.ServeHTTP(w, r)
+				return
+			}
+
+			// In a real app, you might extract userID from context.
+			userID := "anonymous"
+
+			ctx := r.Context()
+			cached, err := repo.Get(ctx, idemKey, userID)
+			if err == nil && cached != nil {
+				log.Debug().Str("idempotency_key", idemKey).Msg("Returning cached idempotency response")
+				for k, v := range cached.Header {
+					for _, val := range v {
+						w.Header().Add(k, val)
+					}
+				}
+				w.WriteHeader(cached.Status)
+				w.Write(cached.Body)
+				return
+			}
+
+			// Record the response
+			rec := &responseRecorder{
+				ResponseWriter: w,
+				status:         http.StatusOK,
+				body:           &bytes.Buffer{},
+			}
+
+			next.ServeHTTP(rec, r)
+
+			// If successful (e.g. 2xx), save the response
+			if rec.status >= 200 && rec.status < 300 {
+				log.Debug().Str("idempotency_key", idemKey).Msg("Saving idempotency response")
+				
+				respToCache := &CachedResponse{
+					Status: rec.status,
+					Header: w.Header(),
+					Body:   rec.body.Bytes(),
+				}
+				
+				if err := repo.Save(ctx, idemKey, userID, respToCache); err != nil {
+					log.Error().Err(err).Msg("Failed to save idempotency response")
+				}
+			}
+		})
+	}
+}

package/src/generators/go-microservice/files/internal/entrypoints/api/idempotency/middleware_test.go.template

@@ -0,0 +1,76 @@
+package idempotency
+
+import (
+	"context"
+	"net/http"
+	"net/http/httptest"
+	"sync/atomic"
+	"testing"
+
+	"github.com/stretchr/testify/require"
+)
+
+// fakeRepo is an in-memory Repository for testing the middleware without a DB.
+type fakeRepo struct {
+	store map[string]*CachedResponse
+}
+
+func newFakeRepo() *fakeRepo { return &fakeRepo{store: map[string]*CachedResponse{}} }
+
+func (f *fakeRepo) Get(ctx context.Context, key, userID string) (*CachedResponse, error) {
+	return f.store[key+":"+userID], nil
+}
+
+func (f *fakeRepo) Save(ctx context.Context, key, userID string, resp *CachedResponse) error {
+	f.store[key+":"+userID] = resp
+	return nil
+}
+
+func TestIdempotencyMiddleware_DuplicateKeyReplaysCached(t *testing.T) {
+	repo := newFakeRepo()
+
+	var calls int32
+	handler := http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		atomic.AddInt32(&calls, 1)
+		w.Header().Set("Content-Type", "application/json")
+		w.WriteHeader(http.StatusCreated)
+		_, _ = w.Write([]byte(`{"id":"abc"}`))
+	})
+	h := Middleware(repo)(handler)
+
+	// First POST executes the handler and caches the 201 response.
+	rr1 := httptest.NewRecorder()
+	req1 := httptest.NewRequest(http.MethodPost, "/api/v1/entities", nil)
+	req1.Header.Set("Idempotency-Key", "key-1")
+	h.ServeHTTP(rr1, req1)
+	require.Equal(t, http.StatusCreated, rr1.Code)
+	require.Equal(t, `{"id":"abc"}`, rr1.Body.String())
+
+	// Duplicate POST with the same key replays the cached response; handler not re-run.
+	rr2 := httptest.NewRecorder()
+	req2 := httptest.NewRequest(http.MethodPost, "/api/v1/entities", nil)
+	req2.Header.Set("Idempotency-Key", "key-1")
+	h.ServeHTTP(rr2, req2)
+	require.Equal(t, http.StatusCreated, rr2.Code)
+	require.Equal(t, `{"id":"abc"}`, rr2.Body.String())
+
+	require.Equal(t, int32(1), atomic.LoadInt32(&calls), "handler must execute exactly once for a repeated key")
+}
+
+func TestIdempotencyMiddleware_GetBypassesCache(t *testing.T) {
+	repo := newFakeRepo()
+	var calls int32
+	h := Middleware(repo)(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		atomic.AddInt32(&calls, 1)
+		w.WriteHeader(http.StatusOK)
+	}))
+
+	for i := 0; i < 2; i++ {
+		rr := httptest.NewRecorder()
+		req := httptest.NewRequest(http.MethodGet, "/api/v1/entities", nil)
+		req.Header.Set("Idempotency-Key", "key-2")
+		h.ServeHTTP(rr, req)
+		require.Equal(t, http.StatusOK, rr.Code)
+	}
+	require.Equal(t, int32(2), atomic.LoadInt32(&calls), "GET must never be deduplicated")
+}

package/src/generators/go-microservice/files/internal/entrypoints/api/idempotency/repository.go.template

@@ -0,0 +1,37 @@
+package idempotency
+
+import (
+	"context"
+	"database/sql"
+)
+
+// CachedResponse represents a previously recorded HTTP response.
+type CachedResponse struct {
+	Status int
+	Header map[string][]string
+	Body   []byte
+}
+
+// Repository defines the contract for storing and retrieving idempotent responses.
+type Repository interface {
+	Get(ctx context.Context, key string, userID string) (*CachedResponse, error)
+	Save(ctx context.Context, key string, userID string, resp *CachedResponse) error
+}
+
+type PostgresRepository struct {
+	db *sql.DB
+}
+
+func NewPostgresRepository(db *sql.DB) *PostgresRepository {
+	return &PostgresRepository{db: db}
+}
+
+func (r *PostgresRepository) Get(ctx context.Context, key string, userID string) (*CachedResponse, error) {
+	// STUB
+	return nil, nil
+}
+
+func (r *PostgresRepository) Save(ctx context.Context, key string, userID string, resp *CachedResponse) error {
+	// STUB
+	return nil
+}

package/src/generators/go-microservice/files/internal/entrypoints/api/middleware_auth.go.template

@@ -0,0 +1,40 @@
+<% if (auth === 'clerk') { %>package api
+
+import (
+	"net/http"
+	"strings"
+
+	"github.com/clerk/clerk-sdk-go/v2"
+	clerkhttp "github.com/clerk/clerk-sdk-go/v2/http"
+)
+
+// AuthMiddleware wraps the Clerk RequireHeaderAuthorization middleware
+// and adds custom checks for User Impersonation or specific Role Claims.
+func AuthMiddleware() func(http.Handler) http.Handler {
+	return func(next http.Handler) http.Handler {
+		// Use Clerk's built-in HTTP middleware to verify the session
+		clerkHandler := clerkhttp.RequireHeaderAuthorization()(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+			claims, ok := clerk.SessionClaimsFromContext(r.Context())
+			if !ok {
+				http.Error(w, "Unauthorized", http.StatusUnauthorized)
+				return
+			}
+
+
+
+			r.Header.Set("X-User-ID", claims.Subject)
+			next.ServeHTTP(w, r)
+		}))
+
+		return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+			// Allow bypassing auth for specific routes like /health or webhooks
+			if strings.HasPrefix(r.URL.Path, "/health") || strings.HasPrefix(r.URL.Path, "/webhooks") {
+				next.ServeHTTP(w, r)
+				return
+			}
+
+			clerkHandler.ServeHTTP(w, r)
+		})
+	}
+}
+<% } %>

package/src/generators/go-microservice/files/internal/entrypoints/api/middleware_loadshed.go.template

@@ -0,0 +1,38 @@
+package api
+
+import (
+	"net/http"
+	"time"
+)
+
+// LoadSheddingMiddleware bounds the number of concurrent in-flight requests.
+// If the server is at capacity, it immediately returns a 503 Service Unavailable 
+// rather than queueing requests forever and risking memory/CPU exhaustion.
+func LoadSheddingMiddleware(maxConcurrent int) func(http.Handler) http.Handler {
+	// A buffered channel acts as a semaphore for concurrent requests.
+	semaphore := make(chan struct{}, maxConcurrent)
+
+	return func(next http.Handler) http.Handler {
+		return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+			select {
+			case semaphore <- struct{}{}:
+				// Acquired a slot
+				defer func() { <-semaphore }()
+				next.ServeHTTP(w, r)
+			default:
+				// Failed to acquire a slot instantly; shed the load.
+				w.Header().Set("Retry-After", "5") // Suggest retrying in 5 seconds
+				http.Error(w, "Service Unavailable (Load Shedding)", http.StatusServiceUnavailable)
+			}
+		})
+	}
+}
+
+// TimeoutMiddleware ensures no single HTTP request hangs indefinitely.
+// Note: While http.Server ReadTimeout/WriteTimeout protects the TCP layer,
+// this protects the application logic layer and cancels the request context.
+func TimeoutMiddleware(timeout time.Duration) func(http.Handler) http.Handler {
+	return func(next http.Handler) http.Handler {
+		return http.TimeoutHandler(next, timeout, "Request Timeout")
+	}
+}

package/src/generators/go-microservice/files/internal/entrypoints/api/middleware_logging.go.template

@@ -0,0 +1,40 @@
+package api
+
+import (
+	"context"
+	"net/http"
+
+	"github.com/rs/zerolog"
+	"github.com/rs/zerolog/log"
+	"go.opentelemetry.io/otel/trace"
+)
+
+type loggerCtxKey struct{}
+
+// LoggerFromContext returns the request-scoped logger (carrying trace_id/span_id
+// when a span is active), or the global logger as a fallback. Handlers call this
+// to emit logs that are joinable to traces.
+func LoggerFromContext(ctx context.Context) *zerolog.Logger {
+	if l, ok := ctx.Value(loggerCtxKey{}).(*zerolog.Logger); ok {
+		return l
+	}
+	return &log.Logger
+}
+
+// TraceLoggingMiddleware stores a request-scoped logger in the context, enriched
+// with the active span's trace_id and span_id. Must be registered AFTER the
+// otelhttp middleware so the span context is populated.
+func TraceLoggingMiddleware(next http.Handler) http.Handler {
+	return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		l := log.Logger
+		sc := trace.SpanContextFromContext(r.Context())
+		if sc.IsValid() {
+			l = l.With().
+				Str("trace_id", sc.TraceID().String()).
+				Str("span_id", sc.SpanID().String()).
+				Logger()
+		}
+		ctx := context.WithValue(r.Context(), loggerCtxKey{}, &l)
+		next.ServeHTTP(w, r.WithContext(ctx))
+	})
+}