Unleash / unleash / 22951360660 / 1

86%

master: 91%

push

github

chore: provide an alternative to conditional middleware (#11523)

## Summary
This change introduces a clearer feature-gating API:
`requireFeatureEnabled(flagResolver, flagName)` for route-level
middleware, and deprecates `conditionalMiddleware` for feature-flag
gating.

## Why
The previous pattern made feature gating less ergonomic and encouraged
custom per-controller middleware functions for a common behavior.
We want a single explicit helper that:

- keeps route registration/discovery stable
- evaluates flags at request time
- is easy to apply directly in `this.route({ middleware: [...] })`

This improves readability and consistency across controllers while
avoiding broad mount-path gating pitfalls.

## What changed
- Added new middleware helper: `requireFeatureEnabled(flagResolver,
flagName)`.
- Deprecated `conditionalMiddleware` for feature-flag route gating
(still available for generic conditional middleware use cases).
- Added function-level guidance in middleware docs/comments.
- Expanded test coverage to focus on the new helper while keeping
compatibility coverage for deprecated `conditionalMiddleware`.

## Migration guidance
### Before (main branch)
`app.use(path, conditionalMiddleware(() =>
config.flagResolver.isEnabled('myFlag'), router));`

### After
`this.route({ method: 'get', path: '/:projectId/actions', handler:
this.getActions, middleware: [requireFeatureEnabled(config.flagResolver,
'myFlag'), openApiService.validPath({...})] });`

## Validation
Tests run and passing:

- `src/test/e2e/api/admin/conditional-middleware.e2e.test.ts`
  - enabled flag allows guarded route
  - disabled flag returns 404 for guarded route
  - disabled guarded subpath does not block sibling/base routes
  - middleware ordering behavior remains predictable
  - deprecated `conditionalMiddleware` compatibility still works
  - guarded routes remain discoverable in OpenAPI when flag is disabled
- `src/lib/middleware/conditional-middleware.test.ts`
  - `conditionalMi... (continued)

1759 of 1986 branches covered (88.57%)

14691 of 17062 relevant lines covered (86.1%)

933.95 hits per line