re #224 feat(module): MiddlewareProviderInterface — modules contribute PSR-15 middleware

[tonydspaniard]

Closes #224.

Goal

Let a module self-register PSR-15 middleware into the HTTP pipeline the same way it already contributes routes, entities, and migrations. Previously the Relay pipeline was hand-assembled in the host's public/index.php, so any feature needing a guard (auth, rate-limit, tenant resolution, an action-aware idempotency check) forced the host to hand-edit the front controller — defeating the self-registering-module value proposition.

What changed

New contract — Altair\Module\Contracts\MiddlewareProviderInterface (mirrors RoutesProviderInterface):

/** @return list<array{middleware: class-string<MiddlewareInterface>|MiddlewareInterface, priority: int}> */
public function middleware(): array;

A module opts in by also implementing it. univeros/module gains a psr/http-server-middleware dependency (a stable PSR interface package).

Ordering — integer priority with documented bands. Altair\Http\Support\MiddlewarePriority exposes the framework's own stages as anchors so module middleware can slot relative to them:

Anchor	Value	Stage
EXCEPTION_HANDLER	0	outermost; throwable → problem+json response
DISPATCHER	500	matches the route, records the action on the request
ACTION	1000	innermost; resolves and runs the matched action

Pre-routing guards slot below DISPATCHER; action-aware guards between DISPATCHER and ACTION. Boundaries are documented: ACTION is terminal on a matched route (priority >= ACTION never runs), and a priority below EXCEPTION_HANDLER runs outside the exception handler (reserved for a deliberate outermost wrapper).

Pickup at bootstrap — Altair\Http\Support\ModuleMiddleware mirrors ModuleRoutes: it collects altair.module-tagged modules' middleware(), stable-sorts the merged queue by priority (equal priorities keep input order — base entries first, then registration order, so the result is deterministic), and returns the flat list. entries() exposes the sorted entries so a host can bind a MiddlewareCollection that bin/altair middleware:list reads. The skeleton public/index.php now assembles its base pipeline as prioritised entries, merges module middleware, and hands the queue to Relay with a ContainerResolver (class-string middleware are autowired).

Acceptance criteria

• MiddlewareProviderInterface under Altair\Module\Contracts, same doc/style as RoutesProviderInterface.
• A module's middleware is merged into the Relay pipeline at bootstrap, ordered deterministically by priority, resolved via the container.
• Framework stages (exception handler / dispatcher / action) have documented priorities so module middleware can position relative to them.
• bin/altair middleware listing (Introspection commands — container, routes, events, middleware, manifests, config #71) shows module-contributed middleware in resolved order (covered by a PipelineInspector test over the merged collection).
• Docs: extending.md gains a "Middleware — automatic" section; a module can register an action-aware guard without the host editing public/index.php.
• Tests: a fixture module contributes middleware; order + real Relay execution + determinism asserted.

Test plan

• composer cs — clean
• composer stan (PHPStan level 8, no baseline) — no errors
• composer rector (whole-tree dry-run) — no changes
• vendor/bin/phpunit tests/Http/Support/ModuleMiddlewareTest.php — 9/9 pass (merge order, sorting, equal-priority determinism, negative-priority outermost boundary, container resolution, real Relay execution order, introspection listing, service-only no-op, entries() ordering)
• tests/Http tests/Bootstrap tests/Introspection tests/Mcp — 396 pass

Note: 5 MongoSessionHandlerTest errors in the full suite are pre-existing (missing local ext-mongodb) and reproduce on clean master — unrelated to this change.

Notes

• The module skeleton (module:new) is intentionally left unchanged to avoid shipping a sample middleware; the capability is fully documented in extending.md.
• bin/altair middleware:list reflects module middleware when the host binds the merged collection as its MiddlewareCollection; introspection is not wired into the default skeleton, so this is documented as the host-side hook.