ci: bump Go version to 1.27 (#118)

* ci: bump Go version to 1.27

Update Go version to 1.27 in GitHub Actions workflows and project documentation. Also update loop syntax in tests to use the `for range` idiom.

* refactor: unify route registration

* Add custom rune scroll codec example

* docs: update docs for recursive route group architecture

- Document the new recursive `RouteGroup` tree replacing the old SubRouter hierarchy.
- Update middleware execution order to Recovery → Auth → RateLimit → Global → groups → Route → Timeout → Handler.
- Replace imperative registration methods with `r.Route()` and `group.Route()`.
- Update README description to highlight recursive route groups and type-safe handling.

* refactor: finalize typed route groups

* test: cover router edge cases

Author: Suhaibinator

.github/workflows/tests.yml

@@ -12,7 +12,7 @@ jobs:
     runs-on: ubuntu-latest
     strategy:
       matrix:
-        go-version: ['1.26.3']
+        go-version: ['1.27']
         os: [ubuntu-latest, macos-latest, windows-latest]
       fail-fast: true
 
@@ -60,11 +60,11 @@ jobs:
     - name: Set up Go
       uses: actions/setup-go@v4
       with:
-        go-version: '1.26.3'
+        go-version: '1.27.0'
         cache: true
 
     - name: Install golangci-lint
-      run: go install github.com/golangci/golangci-lint/cmd/golangci-lint@latest
+      run: go install github.com/golangci/golangci-lint/v2/cmd/golangci-lint@v2.13.0
 
     - name: Run golangci-lint
       run: golangci-lint run --timeout=5m
@@ -74,7 +74,7 @@ jobs:
     runs-on: ubuntu-latest
     strategy:
       matrix:
-        go-version: ['1.26.3']
+        go-version: ['1.27.0']
         os: [ubuntu-latest, macos-latest, windows-latest]
 
     steps:
@@ -100,7 +100,7 @@ jobs:
     - name: Set up Go
       uses: actions/setup-go@v4
       with:
-        go-version: '1.26.3'
+        go-version: '1.27.0'
         cache: true
 
     - name: Run benchmarks
@@ -116,7 +116,7 @@ jobs:
     - name: Set up Go
       uses: actions/setup-go@v4
       with:
-        go-version: '1.26.3'
+        go-version: '1.27.0'
         cache: true
 
     - name: Build simple example

AGENTS.md

@@ -41,7 +41,7 @@ golangci-lint run
 
 ## Architecture Overview
 
-SRouter is a high-performance HTTP router framework built on `julienschmidt/httprouter` with Go generics support (requires Go 1.26.0+). The codebase follows a layered architecture with clear separation of concerns.
+SRouter is a high-performance HTTP router framework built on `julienschmidt/httprouter` with Go generics support (requires Go 1.27+). The codebase follows a layered architecture with clear separation of concerns.
 
 ### Core Type Parameters
 Throughout the codebase, `T` represents the UserID type (must be comparable) and `U` represents the User object type. These generic parameters enable type-safe authentication and context management.
@@ -60,12 +60,12 @@ Throughout the codebase, `T` represents the UserID type (must be comparable) and
 3. Client IP extraction based on IPConfig
 4. Metrics and trace ID injection
 5. httprouter path matching
-6. Middleware chain execution (Recovery → Auth → RateLimit → Route-specific → Global → Timeout → Handler)
+6. Middleware chain execution (Recovery → Auth → RateLimit → Global → outer groups → inner groups → Route → Timeout → Handler)
 7. Generic handler marshaling/unmarshaling (if applicable)
 
 ### Key Design Patterns
 - **Middleware Chain**: Composable middleware with configurable execution order
-- **Configuration Hierarchy**: Global → SubRouter → Route with cascading overrides
+- **Route Tree**: `Router.Group` creates recursive `RouteGroup` handles; policy inherits Global → outer groups → inner groups → Route
 - **Generic Routes**: Type-safe handlers with automatic codec-based marshaling
 - **Context Wrapper**: Single SRouterContext avoids deep context nesting
 
@@ -91,13 +91,15 @@ Flexible rate limiting with strategies:
 Uses Uber's ratelimit library with leaky bucket algorithm.
 
 ### Generic Route Registration
-Generic routes should be registered using `NewGenericRouteDefinition` within SubRouterConfig.Routes for declarative configuration:
+Generic `RouteConfig` values can be registered directly on a `Router` or `RouteGroup`:
 ```go
-router.NewGenericRouteDefinition[ReqType, RespType, UserIDType, UserType](
-    router.RouteConfig[ReqType, RespType]{...}
-)
+router.RouteConfig[ReqType, RespType]{...}
 ```
 
+Call `r.Route(route)` for root routes or retain a group handle and call
+`group.Route(route)`. Both methods accept standard and typed routes. Route trees
+freeze at `Build` or the first request.
+
 ### Context Access
 Always use scontext package helpers for type-safe context access:
 ```go
@@ -115,4 +117,4 @@ Generic routes automatically store handler errors in the request context, allowi
 - Error metrics collection
 
 ### Trace ID Generation
-Enable trace ID generation by setting `TraceIDBufferSize > 0` in RouterConfig. This creates a background ID generator for efficient UUID generation and automatic request correlation.
+Enable trace ID generation by setting `TraceIDBufferSize > 0` in RouterConfig. This creates a background ID generator for efficient UUID generation and automatic request correlation.

CLAUDE.md

@@ -41,7 +41,7 @@ golangci-lint run
 
 ## Architecture Overview
 
-SRouter is a high-performance HTTP router framework built on `julienschmidt/httprouter` with Go generics support (requires Go 1.26.0+). The codebase follows a layered architecture with clear separation of concerns.
+SRouter is a high-performance HTTP router framework built on `julienschmidt/httprouter` with Go generics support (requires Go 1.27+). The codebase follows a layered architecture with clear separation of concerns.
 
 ### Core Type Parameters
 Throughout the codebase, `T` represents the UserID type (must be comparable) and `U` represents the User object type. These generic parameters enable type-safe authentication and context management.
@@ -60,12 +60,12 @@ Throughout the codebase, `T` represents the UserID type (must be comparable) and
 3. Client IP extraction based on IPConfig
 4. Metrics and trace ID injection
 5. httprouter path matching
-6. Middleware chain execution (Recovery → Auth → RateLimit → Route-specific → Global → Timeout → Handler)
+6. Middleware chain execution (Recovery → Auth → RateLimit → Global → outer groups → inner groups → Route → Timeout → Handler)
 7. Generic handler marshaling/unmarshaling (if applicable)
 
 ### Key Design Patterns
 - **Middleware Chain**: Composable middleware with configurable execution order
-- **Configuration Hierarchy**: Global → SubRouter → Route with cascading overrides
+- **Route Tree**: `Router.Group` creates recursive `RouteGroup` handles; policy inherits Global → outer groups → inner groups → Route
 - **Generic Routes**: Type-safe handlers with automatic codec-based marshaling
 - **Context Wrapper**: Single SRouterContext avoids deep context nesting
 
@@ -91,13 +91,15 @@ Flexible rate limiting with strategies:
 Uses Uber's ratelimit library with leaky bucket algorithm.
 
 ### Generic Route Registration
-Generic routes should be registered using `NewGenericRouteDefinition` within SubRouterConfig.Routes for declarative configuration:
+Generic `RouteConfig` values can be registered directly on a `Router` or `RouteGroup`:
 ```go
-router.NewGenericRouteDefinition[ReqType, RespType, UserIDType, UserType](
-    router.RouteConfig[ReqType, RespType]{...}
-)
+router.RouteConfig[ReqType, RespType]{...}
 ```
 
+Call `r.Route(route)` for root routes or retain a group handle and call
+`group.Route(route)`. Both methods accept standard and typed routes. Route trees
+freeze at `Build` or the first request.
+
 ### Context Access
 Always use scontext package helpers for type-safe context access:
 ```go
@@ -115,4 +117,4 @@ Generic routes automatically store handler errors in the request context, allowi
 - Error metrics collection
 
 ### Trace ID Generation
-Enable trace ID generation by setting `TraceIDBufferSize > 0` in RouterConfig. This creates a background ID generator for efficient UUID generation and automatic request correlation.
+Enable trace ID generation by setting `TraceIDBufferSize > 0` in RouterConfig. This creates a background ID generator for efficient UUID generation and automatic request correlation.