feat(router)!: add build and config identities (#123)

* feat(scontext): add runtime identity providers

* feat(router)!: group application dependencies

BREAKING CHANGE: NewRouter now accepts a RouterDependencies[T, U] value instead of separate authentication and user ID callbacks.

Author: Suhaibinator

README.md

@@ -36,7 +36,7 @@ import (
 func main() {
 	r := router.NewRouter[string, string](router.RouterConfig{
 		ServiceName: "hello-service",
-	}, nil, nil)
+	}, router.RouterDependencies[string, string]{})
 
 	r.Route(router.RouteConfigBase{
 		Path:    "/hello",
@@ -58,8 +58,8 @@ func main() {
 curl http://localhost:8080/hello
 ```
 
-The authentication callbacks may be nil when every route uses `NoAuth`, as in
-this example. A nil logger is replaced by a production logger, with a no-op
+Authentication dependencies may be omitted when every route uses `NoAuth`, as
+in this example. A nil logger is replaced by a production logger, with a no-op
 fallback if logger creation fails.
 
 ## Core model
@@ -137,6 +137,8 @@ not called. A failed build is terminal for that router; later mutation panics.
   built-in authentication stage to populate identity first.
 - `TraceIDBufferSize` controls trace-ID generation. `EnableTraceLogging`
   independently enables request-summary logs.
+- Optional build and config identity providers are sampled once per request and
+  stored in the shared SRouter context.
 - Proxy headers are trusted only when explicitly configured. Review the IP
   guide before enabling them because client-IP choice affects security and
   rate-limit keys.

docs/authentication.md

@@ -31,7 +31,7 @@ A route-level value wins over its innermost group, and inner groups win over out
 
 ## Router authentication functions
 
-Built-in authentication uses the callbacks passed to `NewRouter`:
+Built-in authentication uses `RouterDependencies` passed to `NewRouter`:
 
 ```go
 func authenticate(ctx context.Context, token string) (*User, bool) {
@@ -46,15 +46,18 @@ func userID(user *User) string {
 	return user.ID
 }
 
-r := router.NewRouter[string, User](config, authenticate, userID)
+r := router.NewRouter(config, router.RouterDependencies[string, User]{
+	Authenticate: authenticate,
+	UserID:       userID,
+})
 ```
 
 On success, `authenticate` must return a usable `*User` and `true`. SRouter passes that pointer to `userID`, stores the resulting ID in `SRouterContext`, and stores the user pointer as well when `RouterConfig.AddUserObjectToCtx` is true.
 
-The callbacks are required only if at least one compiled route resolves to `AuthOptional` or `AuthRequired`. `Build` fails with a descriptive error when such a route exists and either callback is nil. A router containing only `NoAuth` routes can use:
+The authentication dependencies are required only if at least one compiled route resolves to `AuthOptional` or `AuthRequired`. `Build` fails with a descriptive error when such a route exists and either dependency is nil. A router containing only `NoAuth` routes can use:
 
 ```go
-r := router.NewRouter[string, User](config, nil, nil)
+r := router.NewRouter[string, User](config, router.RouterDependencies[string, User]{})
 ```
 
 Calling `Build` during startup is recommended so callback and route configuration errors are reported before serving traffic. Otherwise the first request triggers the build.
@@ -148,7 +151,7 @@ Choose one of these arrangements when user-based limiting must use custom authen
 - Wrap the whole router with authentication before assigning it to `http.Server.Handler`:
 
   ```go
-  r := router.NewRouter[string, User](config, nil, nil)
+  r := router.NewRouter[string, User](config, router.RouterDependencies[string, User]{})
   srv := &http.Server{Handler: corsAwareAPIKeyAuth(r)}
   ```
 

docs/configuration.md

@@ -37,10 +37,39 @@ type RouterConfig struct {
 Routes do not live inside `RouterConfig`. Add them after `NewRouter` with
 `Router.Route` and `Router.Group`.
 
-The authentication callbacks passed to `NewRouter` may be nil when every route
-resolves to `NoAuth`. If any route resolves to `AuthOptional` or `AuthRequired`,
-`Build` requires both the token-validation callback and the user-ID extraction
-callback.
+## `RouterDependencies[T, U]`
+
+Application behavior is grouped separately from static router configuration:
+
+```go
+type RouterDependencies[T comparable, U any] struct {
+	Authenticate func(context.Context, string) (*U, bool)
+	UserID       func(*U) T
+	BuildID      func() string
+	ConfigID     func() string
+}
+
+r := router.NewRouter(config, router.RouterDependencies[string, User]{
+	Authenticate: authenticate,
+	UserID:       userIDFromUser,
+	BuildID:      currentBuildID,
+	ConfigID:     currentConfigID,
+})
+```
+
+`Authenticate` and `UserID` may be nil when every route resolves to `NoAuth`.
+If any route resolves to `AuthOptional` or `AuthRequired`, `Build` requires both.
+
+`BuildID` and `ConfigID` are optional. SRouter invokes each non-nil resolver once
+per request and stores a non-empty result in the shared SRouter context. Returned
+strings are opaque, log-safe identifiers: SRouter does not parse, normalize,
+cache, or propagate them through headers. Resolvers must be concurrency-safe,
+fast, and non-panicking.
+
+This replaces the older three-argument constructor. Migrate
+`NewRouter(config, authenticate, userIDFromUser)` by wrapping the callbacks in a
+single `RouterDependencies` value as shown above. For a `NoAuth` router, pass an
+empty typed value such as `RouterDependencies[string, User]{}`.
 
 The router itself is the root group. Its fluent `Use`, `Timeout`,
 `MaxBodySize`, `RateLimit`, `AuthToken`, and `Auth` methods override global

docs/context-management.md

@@ -20,6 +20,8 @@ with the wrapper's internal lock.
 | Client IP | `WithClientIP`, `WithClientInfo` | `GetClientIP`, `GetClientIPFromRequest` |
 | User agent | `WithUserAgent`, `WithClientInfo` | `GetUserAgent`, `GetUserAgentFromRequest` |
 | Trace ID | `WithTraceID` | `GetTraceIDFromContext`, `GetTraceIDFromRequest` |
+| Build identity | `WithBuildID` | `GetBuildID`, `GetBuildIDFromRequest` |
+| Configuration identity | `WithConfigID` | `GetConfigID`, `GetConfigIDFromRequest` |
 | Database transaction | `WithTransaction` | `GetTransaction`, `GetTransactionFromRequest` |
 | Route template and path parameters | `WithRouteInfo`, `SetRouteInfo` | `GetRouteTemplateFromRequest`, `GetPathParamsFromRequest` |
 | Allowed CORS origin and credentials | `WithCORSInfo` | `GetCORSInfo`, `GetCORSInfoFromRequest` |
@@ -32,6 +34,17 @@ its zero value. The trace-ID getters instead return an empty string when no
 trace ID is set. `WithTraceID` preserves an existing ID rather than overwriting
 one propagated by an upstream service.
 
+Applications may configure `RouterDependencies.BuildID` and
+`RouterDependencies.ConfigID` to install opaque, log-safe runtime identities.
+SRouter samples each non-nil provider once at the beginning of every request,
+before CORS, routing, and middleware. Empty results remain unset; a non-empty
+local result replaces an inherited identity. Providers must be concurrency-safe,
+fast, and non-panicking.
+
+These identities are not propagated through request or response headers.
+Non-HTTP work, such as background workers, can install already-sampled values
+with `WithBuildID` and `WithConfigID`.
+
 The router populates client information and, after a route match, its route
 template and path parameters. When CORS is configured, CORS information is
 stored even when the request has no `Origin` or the origin is denied; an empty

docs/getting-started.md

@@ -36,7 +36,7 @@ func main() {
 		GlobalMaxBodySize: 1 << 20,
 	}
 
-	r := router.NewRouter[string, string](config, nil, nil)
+	r := router.NewRouter[string, string](config, router.RouterDependencies[string, string]{})
 	r.Route(router.RouteConfigBase{
 		Path:    "/hello",
 		Methods: []router.HttpMethod{router.MethodGet},
@@ -67,7 +67,7 @@ with `r.Route`; recursive path scopes are created with `r.Group`. Both root and
 group `Route` methods accept standard `RouteConfigBase` values and typed
 `RouteConfig[Req, Resp]` values.
 
-The authentication callbacks may be nil while every effective route auth level
+Authentication dependencies may be nil while every effective route auth level
 is `NoAuth`. Supply them before adding `AuthOptional` or `AuthRequired` routes.
 
 Calling `Build` during startup is recommended. It validates the full route tree

docs/logging.md

@@ -9,9 +9,14 @@ if err != nil {
 }
 defer logger.Sync()
 
-r := router.NewRouter[string, User](router.RouterConfig{
+r := router.NewRouter(router.RouterConfig{
 	Logger: logger,
-}, authenticate, userIDFromUser)
+}, router.RouterDependencies[string, User]{
+	Authenticate: authenticate,
+	UserID:       userIDFromUser,
+	BuildID:      func() string { return buildID },
+	ConfigID:     func() string { return configID },
+})
 ```
 
 ## Request summary logging
@@ -21,7 +26,17 @@ For requests that reach normal route dispatch, SRouter emits one `"Request summa
 - `TraceIDBufferSize > 0`, which enables automatic trace IDs on matched routes and request summaries.
 - `EnableTraceLogging`, which enables request summaries independently of trace IDs.
 
-The summary contains `method`, `path`, `status`, `duration`, `bytes`, `ip`, and `user_agent`. For a matched route, it also contains `trace_id` when automatic trace generation is enabled. An unmatched 404 or 405 still receives a summary, but it never enters the per-route trace middleware and therefore has no automatically generated `trace_id`.
+The summary contains `method`, `path`, `status`, `duration`, `bytes`, `ip`, and `user_agent`. It also contains configured `build_id` and `config_id` values when available. For a matched route, it contains `trace_id` when automatic trace generation is enabled. An unmatched 404 or 405 still receives a summary, but it never enters the per-route trace middleware and therefore has no automatically generated `trace_id`.
+
+SRouter adds available runtime identities to its request-bound authentication,
+timeout, panic recovery, handled HTTP error, lazy-build failure, and JSON-response
+write-failure logs. Startup and route-registration logs have no request context
+and remain unchanged.
+
+Runtime identities are opaque, log-safe application values. SRouter samples
+them once per request and does not propagate them through headers. Background
+workers may install already-sampled values with `scontext.WithBuildID` and
+`scontext.WithConfigID`.
 
 Its level is chosen in this priority order:
 
@@ -116,10 +131,13 @@ idGenerator := middleware.NewIDGenerator(1000)
 defer idGenerator.Stop()
 
 traceMiddleware := middleware.CreateTraceMiddleware[string, User](idGenerator)
-r := router.NewRouter[string, User](router.RouterConfig{
+r := router.NewRouter(router.RouterConfig{
 	Logger:             logger,
 	EnableTraceLogging: true,
-}, authenticate, userIDFromUser)
+}, router.RouterDependencies[string, User]{
+	Authenticate: authenticate,
+	UserID:       userIDFromUser,
+})
 
 handler := traceMiddleware(r)
 ```

docs/metrics.md

@@ -26,7 +26,10 @@ config := router.RouterConfig{
 	},
 }
 
-r := router.NewRouter[string, User](config, authenticate, userIDFromUser)
+r := router.NewRouter(config, router.RouterDependencies[string, User]{
+	Authenticate: authenticate,
+	UserID:       userIDFromUser,
+})
 ```
 
 With the built-in middleware, non-empty `Namespace` and `Subsystem` values become the default tags `service` and `subsystem`, respectively. They do not configure a backend's native namespace or subsystem. For example, the Prometheus adapter's namespace and subsystem are separately supplied to `prometheus.NewPrometheusRegistry` and become metric-name prefixes.

docs/middleware.md

@@ -42,9 +42,12 @@ values and concurrency rules.
 Middleware can be attached at four scopes:
 
 ```go
-r := router.NewRouter[string, User](router.RouterConfig{
+r := router.NewRouter(router.RouterConfig{
 	Middlewares: []common.Middleware{globalAudit},
-}, authenticate, userIDFromUser)
+}, router.RouterDependencies[string, User]{
+	Authenticate: authenticate,
+	UserID:       userIDFromUser,
+})
 
 r.Use(rootHeaders)
 

docs/rate-limiting.md

@@ -12,7 +12,10 @@ config := router.RouterConfig{
 	},
 }
 
-r := router.NewRouter[string, User](config, authenticate, userID)
+r := router.NewRouter(config, router.RouterDependencies[string, User]{
+	Authenticate: authenticate,
+	UserID:       userID,
+})
 
 r.Group("/account").
 	Auth(router.AuthRequired).

docs/route-groups.md

@@ -5,7 +5,10 @@ SRouter has one runtime `Router` and one underlying `httprouter` dispatcher.
 not independent HTTP handlers.
 
 ```go
-r := router.NewRouter[string, User](config, authenticate, userID)
+r := router.NewRouter(config, router.RouterDependencies[string, User]{
+	Authenticate: authenticate,
+	UserID:       userID,
+})
 
 api := r.Group("/api").
 	Timeout(3 * time.Second).