dart_http2_flutter_sse #

A production-ready HTTP/2 client package for Dart and Flutter. Provides a clean, developer-friendly API similar to dio or http, with robust HTTP/2 support.

Features #

• ✅ HTTP/2 requests: GET, POST, PUT, PATCH, DELETE
• ✅ Request/response headers, query parameters, JSON body, form body, raw bytes, and streaming body
• ✅ Response streaming for large downloads
• ✅ Connection reuse, multiplexing, and connection pooling
• ✅ TLS/ALPN where available (native platforms)
• ✅ Timeout support: connect, send, receive timeouts
• ✅ Cancellation tokens for cancelling active requests
• ✅ Retry policy with exponential backoff and jitter
• ✅ Interceptors for request, response, and error handling
• ✅ Logging interceptor with safe redaction for tokens/passwords
• ✅ Certificate pinning support (native platforms)
• ✅ Graceful fallback — HTTP/1.1 on Web, with clear platform documentation
• ✅ Strong typing, null safety, no unnecessary dependencies
• ✅ Fully tested with unit and integration tests

Platform Support #

Installation #

Add to your pubspec.yaml:

dependencies:
  dart_http2_flutter_sse: ^1.0.0

Then run:

flutter pub get

Quick Start #

import 'package:dart_http2_flutter_sse/dart_http2_flutter_sse.dart';

final client = Http2Client();

final response = await client.get(
  'https://api.example.com/users',
  queryParameters: {'page': 1},
);

print(response.statusCode); // 200
print(response.data);        // Decoded JSON body

Usage #

Basic Requests #

// GET
final getRes = await client.get('https://api.example.com/items');

// POST with JSON body
final postRes = await client.post(
  'https://api.example.com/items',
  body: {'name': 'New Item', 'price': 29.99},
);

// POST with form data
final formRes = await client.post(
  'https://api.example.com/login',
  body: {'username': 'john', 'password': 'secret'},
  bodyType: BodyType.form,
);

// PUT
final putRes = await client.put(
  'https://api.example.com/items/1',
  body: {'name': 'Updated Item'},
);

// PATCH
final patchRes = await client.patch(
  'https://api.example.com/items/1',
  body: {'price': 19.99},
);

// DELETE
final deleteRes = await client.delete('https://api.example.com/items/1');

Query Parameters & Headers #

final response = await client.get(
  'https://api.example.com/search',
  queryParameters: {
    'q': 'flutter',
    'page': 1,
    'limit': 20,
  },
  headers: {
    'Authorization': 'Bearer your-token',
    'X-Custom': 'value',
  },
);

Response Handling #

final response = await client.get('https://api.example.com/data');

print(response.statusCode);    // 200
print(response.isOk);          // true
print(response.bodyString);    // Raw body string
print(response.data);          // Auto-decoded JSON (Map, List, or String)
print(response.dataAsMap);     // Null-safe JSON map access
print(response.headers);       // Response headers
print(response.contentLength); // Content-Length from headers
print(response.duration);      // Request duration

Streaming Download #

final request = Http2Request.get('https://example.com/large-file.zip');

int totalBytes = 0;
await for (final chunk in client.streamResponse(request)) {
  totalBytes += chunk.bodyBytes?.length ?? 0;
  print('Received $totalBytes bytes so far...');
}
print('Download complete: $totalBytes bytes');

Streaming Upload #

final fileStream = File('large-file.txt').openRead();

final response = await client.post(
  'https://api.example.com/upload',
  body: fileStream,
  bodyType: BodyType.stream,
  onSendProgress: (sent, total) {
    print('Uploaded $sent of $total bytes');
  },
);

Timeouts #

final client = Http2Client(
  timeoutConfiguration: const TimeoutConfiguration(
    connectTimeout: Duration(seconds: 10),
    sendTimeout: Duration(seconds: 30),
    receiveTimeout: Duration(seconds: 30),
  ),
);

// Or use the factory for all-equal timeouts:
final client2 = Http2Client(
  timeoutConfiguration: TimeoutConfiguration.all(
    Duration(seconds: 15),
  ),
);

Cancellation #

final cts = CancellationTokenSource();

// Start a request
final future = client.get(
  'https://api.example.com/slow-endpoint',
  cancellationToken: cts.token,
);

// Cancel it later
cts.cancel();

try {
  await future;
} on CancelledException catch (e) {
  print('Request was cancelled: $e');
}

Retry with Exponential Backoff #

final client = Http2Client(
  retryConfig: const RetryConfig(
    maxRetries: 3,
    baseDelay: Duration(seconds: 1),
    maxDelay: Duration(seconds: 30),
    useJitter: true,     // Adds randomness to avoid thundering herd
    retryableStatusCodes: {
      408, // Request Timeout
      429, // Too Many Requests
      500, // Internal Server Error
      502, // Bad Gateway
      503, // Service Unavailable
      504, // Gateway Timeout
    },
    retryOnConnectionErrors: true,
  ),
);

Custom Retry Logic #

final client = Http2Client(
  retryConfig: RetryConfig(
    maxRetries: 2,
    retryOnError: (error) {
      // Only retry on specific conditions
      if (error is TimeoutException) return true;
      if (error is HttpStatusException && error.statusCode == 429) return true;
      return false;
    },
  ),
);

Interceptors #

// Logging interceptor (safe redaction built-in)
final client = Http2Client(
  interceptors: [
    LoggingInterceptor(const LoggingConfig(
      logRequest: true,
      logResponse: true,
      logRequestBody: false,  // Off by default for security
      logResponseBody: false, // Off by default for security
      logErrors: true,
    )),
  ],
);

// Custom interceptor
class AuthInterceptor extends Interceptor {
  final String token;

  AuthInterceptor(this.token);

  @override
  void onRequest(Http2Request request, RequestHandler handler) {
    request.headers['Authorization'] = 'Bearer $token';
    handler.next(request);
  }

  @override
  void onResponse(Http2Response response, ResponseHandler handler) {
    print('Response: ${response.statusCode}');
    handler.next(response);
  }

  @override
  void onError(Http2Exception error, ErrorHandler handler) {
    print('Error: $error');
    handler.next(error);
  }
}

final client = Http2Client(
  interceptors: [
    AuthInterceptor('your-token'),
    LoggingInterceptor(),
  ],
);

Certificate Pinning #

final client = Http2Client(
  enableCertificatePinning: true,
  pinnedCertificates: {
    'api.example.com': [
      '-----BEGIN CERTIFICATE-----\nMIIF...',
    ],
  },
);

Note: Certificate pinning is only supported on native platforms (Android, iOS, macOS, Linux, Windows). Not available on Web.

Error Handling #

try {
  final response = await client.get('https://api.example.com/data');
} on HttpStatusException catch (e) {
  print('HTTP error: ${e.statusCode} - ${e.message}');
  print('Response body: ${e.response?.bodyString}');
} on TimeoutException catch (e) {
  print('${e.timeoutType} timeout exceeded');
} on ConnectionException catch (e) {
  print('Connection failed to ${e.host}: ${e.message}');
} on CancelledException catch (e) {
  print('Request was cancelled');
} on CertificatePinningException catch (e) {
  print('Certificate pin mismatch for ${e.hostname}');
} on Http2Exception catch (e) {
  print('Other HTTP/2 error: ${e.message}');
}

Progress Tracking #

final response = await client.get(
  'https://api.example.com/large-file',
  onReceiveProgress: (received, total) {
    final progress = total > 0 ? (received / total * 100).toStringAsFixed(1) : '?';
    print('Downloaded $received / $total bytes ($progress%)');
  },
);

Architecture #

lib/
├── dart_http2_flutter_sse.dart      # Barrel export
├── src/
│   ├── client.dart                  # Http2Client public API
│   ├── models/
│   │   ├── http2_request.dart       # Request model with body serialization
│   │   ├── http2_response.dart      # Response model with JSON decoding
│   │   └── http2_exceptions.dart    # Typed exception hierarchy
│   ├── interceptors/
│   │   ├── interceptor.dart         # Interceptor interface + chain
│   │   ├── logging_interceptor.dart # Request/response logging with redaction
│   │   └── retry_interceptor.dart   # Retry with exponential backoff
│   ├── transport/
│   │   ├── transport.dart           # Abstract transport interface
│   │   ├── http2_transport.dart     # HTTP/2 transport (native)
│   │   ├── http1_fallback_transport.dart # HTTP/1.1 fallback
│   │   └── web_transport_stub.dart  # Web platform transport
│   └── utils/
│       ├── cancellation_token.dart  # Cancellation token system
│       ├── timeout_manager.dart     # Timeout enforcement
│       └── connection_pool.dart     # Connection pooling

Comparison: HTTP/2 vs HTTP/1.1 #

Comparison with Dio #

Running Tests #

# Run unit tests
flutter test

# Run integration tests (requires network)
flutter test --dart-define=RUN_INTEGRATION_TESTS=true integration_test/

Limitations #

• Web platform: HTTP/2 is not directly controllable from Dart on the web. The browser may negotiate HTTP/2 with the server, but this package falls back to HTTP/1.1 semantics. Certificate pinning and streaming uploads are not available on Web.
• ALPN negotiation: On native platforms, ALPN (Application-Layer Protocol Negotiation) is handled by the underlying TLS library. If the server does not support HTTP/2, the connection falls back to HTTP/1.1.
• Server push: While HTTP/2 supports server push, this client does not currently expose a push-specific API. Pushed resources are handled transparently.
• Flow control: HTTP/2 stream flow control is handled by the underlying implementation and is not directly configurable through this package.

Contributing #

Contributions are welcome! Please see CONTRIBUTING.md for guidelines.

License #

This project is licensed under the MIT License - see the LICENSE file for details.