BloomResponse class

Represents an HTTP response returned from a Bloom API route handler or middleware.

Supports both buffered in-memory payloads (JSON, HTML, plain text, binary) and streaming responses (BloomResponse.stream, BloomResponse.file) for large files, Server-Sent Events (SSE), or proxied upstream streams.

Streaming Lifecycle & Consumption Contract

Single-Consumption Rule: A streaming response's body stream can be consumed exactly once via takeBodyStream. Attempting to call takeBodyStream a second time or on a buffered response throws a StateError.
Deferred Stream Consumption: The body stream remains unconsumed until the router writes bytes to the client socket. This enables downstream middleware to inspect and mutate response headers even after the route handler has returned.
Mid-Stream Failure Behavior: HTTP status code and initial headers are committed to the socket when the first chunk is sent. If an unhandled error occurs mid-stream, the socket connection is aborted/closed immediately. This ensures clients receive a truncated chunked transfer rather than silently accepting corrupted data as successful.
Chunked Encoding vs Known Content-Length: BloomResponse.stream omits content-length and uses chunked transfer encoding. In contrast, BloomResponse.file computes file length ahead of time and sets content-length, enabling download progress tracking.

Example

// Standard JSON response
router.get('/api/users', (req) async {
  return BloomResponse.json([{'id': 1, 'name': 'Alice'}]);
});

// File streaming response
router.get('/downloads/:filename', (req) async {
  final file = File('public/${req.params['filename']}');
  return BloomResponse.file(file, contentType: 'application/octet-stream');
});

// Custom chunked stream
router.get('/events', (req) async {
  final stream = eventEmitter.stream.map((e) => utf8.encode('data: $e\n\n'));
  return BloomResponse.stream(stream, contentType: 'text/event-stream');
});

Constructors

BloomResponse({int statusCode = 200, Map<String, String>? headers, Uint8List? body}): Creates a buffered BloomResponse with an optional statusCode, headers, and binary body.
BloomResponse.error(String message, {int statusCode = 500}): Helper factory constructor for HTTP 500 Internal Server Error (or custom statusCode) JSON error responses.
factory
BloomResponse.file(File file, {String? contentType, int statusCode = 200, Map<String, String>? headers}): Streams file from disk without loading its entire contents into memory.
factory
BloomResponse.forbidden([String message = 'Forbidden']): Helper factory constructor for HTTP 403 Forbidden JSON error responses.
factory
BloomResponse.html(String html, {int statusCode = 200, Map<String, String>? headers}): Helper factory constructor for HTML responses.
factory
BloomResponse.json(dynamic data, {int statusCode = 200, Map<String, String>? headers}): Helper factory constructor for JSON responses.
factory
BloomResponse.methodNotAllowed([String message = 'Method Not Allowed', Map<String, String>? headers]): Helper factory constructor for HTTP 405 Method Not Allowed JSON error responses.
factory
BloomResponse.noContent({Map<String, String>? headers}): Helper factory constructor for HTTP 204 No Content responses.
factory
BloomResponse.notFound([String message = 'Not Found']): Helper factory constructor for HTTP 404 Not Found JSON error responses.
factory
BloomResponse.payloadTooLarge([String message = 'Payload Too Large']): Helper factory constructor for HTTP 413 Payload Too Large JSON error responses.
factory
BloomResponse.redirect(String location, {int statusCode = 302}): Helper factory constructor for HTTP redirects.
factory
BloomResponse.stream(Stream<List<int>> body, {int statusCode = 200, Map<String, String>? headers, String? contentType}): Creates a streaming response whose body is written incrementally from body.
BloomResponse.text(String text, {int statusCode = 200, Map<String, String>? headers}): Helper factory constructor for plain text responses.
factory
BloomResponse.unauthorized([String message = 'Unauthorized']): Helper factory constructor for HTTP 401 Unauthorized JSON error responses.
factory

Properties

body → Uint8List: Response body binary payload for buffered responses.
final
bodyJson → dynamic: Decodes and returns the buffered body as JSON, or null if decoding fails.
no setter
bodyText → String: Decodes and returns the buffered body as a UTF-8 string.
no setter
hashCode → int: The hash code for this object.
no setterinherited
headers → Map<String, String>: Response headers map (case-insensitive keys handled during transmission).
final
isStreaming → bool: Whether this response delivers its payload incrementally via a byte stream.
no setter
runtimeType → Type: A representation of the runtime type of the object.
no setterinherited
statusCode → int: HTTP status code (e.g. 200, 204, 400, 401, 404, 500).
final

Methods

noSuchMethod(Invocation invocation) → dynamic: Invoked when a nonexistent method or property is accessed.
inherited
takeBodyStream() → Stream<List<int>>: Returns the underlying body stream, marking it as consumed.
toString() → String: A string representation of this object.
inherited

Operators

operator ==(Object other) → bool: The equality operator.
inherited