rhttp 0.4.0

Make HTTP requests using Rust for Flutter developers. It uses FFI to call Rust functions from Dart. On the Rust side, it uses reqwest to make HTTP requests.

rhttp

Make HTTP requests using Rust for Flutter developers.

About

The default HTTP client in Dart is part of dart:io, which lacks configurability and performance compared to other HTTP clients. Furthermore, HTTP/2 and HTTP/3 are either missing or not supported by default. This package uses FFI with flutter_rust_bridge to call Rust code. This allows you to use a faster and more efficient HTTP client. On Rust's side, the reqwest crate is used to make the requests.

Why shouldn't I use cronet_http or cupertino_http? These packages for instance only support Android or iOS, while rhttp supports all platforms (except web currently) with a single configuration.

Features

• ✅ HTTP/1, HTTP/1.1, HTTP/2, and HTTP/3 support
• ✅ TLS 1.2 and 1.3 support
• ✅ Connection pooling
• ✅ Strong type safety
• ✅ Optional compatibility layer for the http package

Benchmark

rhttp is much faster at downloading large files and a bit faster at downloading small files compared to the default HTTP client in Dart.

Referred packages: dio (5.5.0+1), http (1.2.2), rhttp (0.3.0)

Checkout the benchmark code here.

Getting Started

➤ Installation

1. Install Rust via rustup.
   • Rust 1.80.0 or later is required.
2. Add rhttp to pubspec.yaml:

dependencies:
  rhttp: <version>

➤ Initialization

import 'package:rhttp/rhttp.dart';

void main() async {
  await Rhttp.init(); // add this
  runApp(MyApp());
}

➤ Usage

import 'package:rhttp/rhttp.dart';

void main() async {
  await Rhttp.init();
  
  // Make a GET request
  HttpTextResponse response = await Rhttp.get('https://example.com');
  
  // Read the response
  int statusCode = response.statusCode;
  String body = response.body;
}

Alternatively, you can use the RhttpCompatibleClient that implements the Client of the http package.

For more information, see Compatibility Layer.

import 'package:rhttp/rhttp.dart';
import 'package:http/http.dart' as http;

void main() async {
  await Rhttp.init();
  
  http.Client client = await RhttpCompatibleClient.create();
  http.Response response = await client.get(Uri.parse('https://example.com'));

  print(response.statusCode);
  print(response.body);
}

Features

➤ HTTP methods

You can make requests using different HTTP methods:

// Pass the method as an argument
await Rhttp.request(method: HttpMethod.post, url: 'https://example.com');

// Use the helper methods
await Rhttp.post('https://example.com');

➤ Request query parameters

You can add query parameters to the URL:

await Rhttp.get('https://example.com', query: {'key': 'value'});

➤ Request Headers

You can add headers to the request:

await Rhttp.request(
  method: HttpMethod.get,
  url: 'https://example.com',
  headers: const HttpHeaders.map({
    HttpHeaderName.contentType: 'application/json',
  }),
);

➤ Request Body

You can add a body to the request. There are different types of bodies you can use:

Text

Pass a string to the HttpBody.text constructor.

// Raw body
await Rhttp.request(
  method: HttpMethod.post,
  url: 'https://example.com',
  body: HttpBody.text('raw body'),
);

JSON

Pass JSON map to the HttpBody.json constructor.

The Content-Type header will be set to application/json if not provided.

// JSON body
await Rhttp.request(
  method: HttpMethod.post,
  url: 'https://example.com',
  body: HttpBody.json({'key': 'value'}),
);

Binary

Pass a Uint8List to the HttpBody.bytes constructor.

// Binary body
await Rhttp.request(
  method: HttpMethod.post,
  url: 'https://example.com',
  body: HttpBody.bytes(Uint8List.fromList([0, 1, 2])),
);

Form

Pass a flat map to the HttpBody.form constructor.

The Content-Type header will be set to application/x-www-form-urlencoded if not provided.

// Form body
await Rhttp.request(
  method: HttpMethod.post,
  url: 'https://example.com',
  body: HttpBody.form({'key': 'value'}),
);

Multipart

Pass a map of MultipartItem to the HttpBody.multipart constructor.

The Content-Type header will be overridden to multipart/form-data with a random boundary.

await Rhttp.request(
  method: HttpMethod.post,
  url: 'https://example.com',
  body: HttpBody.multipart({
    'name': const MultipartItem.text(
      text: 'Tom',
    ),
    'profile_image': MultipartItem.bytes(
      bytes: Uint8List.fromList(bytes),
      fileName: 'image.jpeg',
    ),
  }),
)

➤ Response Body

To let Rust do most of the work, you must specify the expected response body type before making the request.

Most convenience functions (e.g. Rhttp.get, Rhttp.request) return a HttpTextResponse.

HttpTextResponse response = await Rhttp.getText('https://example.com');
String body = response.body;

HttpBytesResponse response = await Rhttp.getBytes('https://example.com');
Uint8List body = response.body;

HttpStreamResponse response = await Rhttp.getStream('https://example.com');
Stream<Uint8List> body = response.body;

➤ Connection Reuse

To improve performance, it is recommended to create a client and reuse it for multiple requests.

This allows you to reuse connections (with same servers). Furthermore, it avoids the overhead of creating a new client for each request.

final client = await RhttpClient.create();

await client.get('https://example.com');

You can dispose the client when you are done with it:

client.dispose();

➤ Cancel Requests

You can cancel a request by providing a CancelToken:

final cancelToken = CancelToken();
final request = Rhttp.get(
   'https://example.com',
   cancelToken: cancelToken,
);

// Cancel the request
cancelToken.cancel();

// Will throw a `RhttpCancelException`
await request;

➤ Error Handling

All exceptions are subclasses of RhttpException.

The following exceptions can be thrown:

Exception	Description
RhttpCancelException	Request was canceled.
RhttpTimeoutException	Request timed out.
RhttpStatusCodeException	Response has 4xx or 5xx status code.
RhttpInvalidCertificateException	Server certificate is invalid.
RhttpInvalidClientException	Request is made with an invalid client.
RhttpUnknownException	Unknown error occurred.

➤ Timeout

You can specify the timeout for the request:

await Rhttp.get(
  'https://example.com',
  settings: const ClientSettings(
    timeout: Duration(seconds: 10),
    connectTimeout: Duration(seconds: 5),
  ),
);

➤ Throw on Status Code

By default, an exception is thrown if the response has a 4xx or 5xx status code. You can disable this behavior by setting throwOnStatusCode to false.

await Rhttp.get(
  'https://example.com',
  settings: const ClientSettings(
    throwOnStatusCode: false,
  ),
);

➤ HTTP version

You can specify the HTTP version to use for the request. HTTP/1, HTTP/1.1, HTTP/2, and HTTP/3 are currently supported.

await Rhttp.get(
  'https://example.com',
  settings: const ClientSettings(
    httpVersionPref: HttpVersionPref.http3,
  ),
);

➤ TLS version

You can specify the TLS version to use for the request. Only TLS 1.2 and 1.3 are currently supported.

await Rhttp.get(
  'https://example.com',
  settings: const ClientSettings(
    tlsSettings: TlsSettings(
      minTlsVersion: TlsVersion.tls12,
      maxTlsVersion: TlsVersion.tls13,
    ),
  ),
);

➤ Disable certificate verification

This is very insecure and should only be used for testing purposes.

await Rhttp.get(
  'https://example.com',
  settings: const ClientSettings(
    tlsSettings: TlsSettings(
      verifyCertificates: false,
    ),
  ),
);

➤ Compatibility Layer

You can use the RhttpCompatibleClient that implements the Client of the http package, thereby exposing the same API as the default HTTP client in the Dart ecosystem.

This comes with some downsides, such as:

• inferior type safety due to the flaw that body is of type Object? instead of a sane supertype.
• body of type Map is implicitly interpreted as x-www-form-urlencoded that is only documented in StackOverflow (as of writing this).
• no support for cancellation
• no out-of-the-box support for multipart requests

import 'package:rhttp/rhttp.dart';
import 'package:http/http.dart' as http;

void main() async {
  await Rhttp.init();
  
  http.Client client = await RhttpCompatibleClient.create();
  http.Response response = await client.get(Uri.parse('https://example.com'));

  print(response.statusCode);
  print(response.body);
}

License

MIT License

Copyright (c) 2024 Tien Do Nam

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.