BloomApiRouter class

High-performance server router for Bloom API routes, WebSocket gateways, and SSR endpoints.

Architectural Contract

• Provides unified route registration (get, post, put, delete, patch, all) with nested or route-scoped middleware pipelines and global pipeline hooks (use).
• Supports path parameter matching (/api/tasks/:id), wildcard captures (/*), and automatic OpenAPI 3.1 schema specification generation and interactive Scalar / Swagger UI mounting (enableOpenApi).
• Bridges native dart:io HttpRequest to typed, testable BloomRequest and BloomResponse abstractions.

Concurrency & Shutdown Model

• Non-blocking asynchronous request handling across server isolates.
• Tracks active requests via in-flight request completers to support graceful zero-downtime shutdown via close, draining active connections within a configurable timeout before force-closing sockets.
• Rejects incoming requests with HTTP 503 Service Unavailable during shutdown drain phase.

Specificity-Based Route Sorting

Routes are sorted by specificity score (exact static matches > parameterized segments > wildcard routes) so registration order does not cause unintentional route shadowing.

Streaming Request Guards & Response Backpressure

• handleIoRequest checks byte stream length against maxRequestBodyBytes before buffering full payloads, short-circuiting oversized payload attacks with HTTP 413 Payload Too Large.
• Incremental responses use addStream to propagate backpressure from the client socket directly to the byte producer.

Example

final router = BloomApiRouter();

// Global middleware
router.use(BloomCorsMiddleware());

// Route definitions
router.get('/api/health', (req) async => BloomResponse.json({'status': 'ok'}));
router.get('/api/users/:id', (req) async {
  final id = req.params['id']!;
  return BloomResponse.json({'id': id, 'name': 'User $id'});
});

// Bind and listen
final server = await router.serve(port: 8080);