feat(dart_frog): allow disabling Response buffer output (#1261)

Co-authored-by: Alejandro Santiago <dev@alestiago.com>

Author: luiscib3r

packages/dart_frog/lib/src/_internal.dart

@@ -6,6 +6,7 @@ import 'dart:io';
 import 'package:dart_frog/dart_frog.dart';
 import 'package:dart_frog/src/body_parsers/body_parsers.dart';
 import 'package:http_methods/http_methods.dart' show isHttpMethod;
+import 'package:meta/meta.dart';
 import 'package:shelf/shelf.dart' as shelf;
 import 'package:shelf/shelf_io.dart' as shelf_io;
 

packages/dart_frog/lib/src/response.dart

@@ -18,17 +18,32 @@ class Response {
             encoding: encoding,
           ),
         );
+  Response._(this._response);
 
   /// Create a [Response] with a stream of bytes.
+  ///
+  /// If [bufferOutput] is `true` (the default), streamed responses will be
+  /// buffered to improve performance. If `false`, all chunks will be pushed
+  /// over the wire as they're received. Note that, disabling buffering of the
+  /// output can result in very poor performance, when writing many small
+  /// chunks.
+  ///
+  /// See also:
+  ///
+  /// * [HttpResponse.bufferOutput](https://api.flutter.dev/flutter/dart-io/HttpResponse/bufferOutput.html)
   Response.stream({
     int statusCode = 200,
     Stream<List<int>>? body,
     Map<String, Object>? headers,
+    bool bufferOutput = true,
   }) : this._(
           shelf.Response(
             statusCode,
             body: body,
             headers: headers,
+            context: !bufferOutput
+                ? {Response.shelfBufferOutputContextKey: bufferOutput}
+                : null,
           ),
         );
 
@@ -80,7 +95,15 @@ class Response {
           encoding: encoding,
         );
 
-  Response._(this._response);
+  /// A [shelf.Response.context] key used to determine if if the
+  /// [HttpResponse.bufferOutput] should be enabled or disabled.
+  ///
+  /// See also:
+  ///
+  /// * [shelf_io library](https://pub.dev/documentation/shelf/latest/shelf_io/shelf_io-library.html)
+  /// * [HttpResponse.bufferOutput](https://api.flutter.dev/flutter/dart-io/HttpResponse/bufferOutput.html)
+  @visibleForTesting
+  static const shelfBufferOutputContextKey = 'shelf.io.buffer_output';
 
   shelf.Response _response;
 
@@ -91,6 +114,12 @@ class Response {
   /// The returned map is unmodifiable.
   Map<String, String> get headers => _response.headers;
 
+  /// Extra context that can be used by for middleware and handlers.
+  ///
+  /// The value is immutable.
+  @visibleForTesting
+  Map<String, Object> get context => _response.context;
+
   /// Returns a [Stream] representing the body.
   Stream<List<int>> bytes() => _response.read();
 

packages/dart_frog/test/src/response_test.dart

@@ -107,6 +107,46 @@ void main() {
         final response = Response.stream(body: stream);
         expect(response.bytes(), emits(equals(bytes)));
       });
+
+      group('bufferOutput', () {
+        test('is omitted by default', () {
+          final response = Response.stream(
+            body: const Stream.empty(),
+            // ignore: avoid_redundant_argument_values
+            bufferOutput: true,
+          );
+
+          expect(
+            response.context,
+            isNot(contains(Response.shelfBufferOutputContextKey)),
+            reason:
+                '''The context should not have the '${Response.shelfBufferOutputContextKey}' key.''',
+          );
+        });
+
+        test('can be disabled', () {
+          final response = Response.stream(
+            body: const Stream.empty(),
+            bufferOutput: false,
+          );
+
+          expect(
+            response.context,
+            contains(Response.shelfBufferOutputContextKey),
+            reason:
+                '''The context should have the '${Response.shelfBufferOutputContextKey}' key.''',
+          );
+
+          final bufferOutput =
+              response.context[Response.shelfBufferOutputContextKey];
+          expect(
+            bufferOutput,
+            isFalse,
+            reason:
+                '''The '${Response.shelfBufferOutputContextKey}' should be 'false' when disabled.''',
+          );
+        });
+      });
     });
 
     group('formData', () {