xhttp 1.0.1

  • Readme
  • Changelog
  • Example
  • Installing
  • 50

A cross-platform HTTP library for Dart with an emphasis on composition.

pub package Build Status

This is an alternative to package:http.

Motivation #

package:http has two design choices that led to the creation of this package:

  1. Inheritance over composition.
  2. Streaming-responses in send.

These design choices make it harder to add application-specific behavior to HTTP clients. A common example is to embed authorization headers in every request:

Problem example #

Code that embeds user credentials in HTTP requests ends up being repeated often in apps with many small components, such as Flutter apps. Those components often must work properly regardless of whether a user is signed in. Ideally, we'd be able to pass each component a Client object, and the component doesn't have to know whether the Client has been configured to send credentials (user signed in) or not (user signed out).

To accomplish this we can extend package:http's BaseClient with a custom type that holds onto the credentials, and pass that to components. The downside is that we had to implement an entire client just to modify headers.

Another option is to write a Request factory that always produces requests with authentication headers, but then every component needs access to that factory object as well as the client.

Aside: Another small nitpick is that Client.send returns a StreamedResponse, so apps that specify their own headers are stuck with the streaming API when they probably don't want it, or at least they may not want every single request to be streamed. The decision to stream or not stream should be scoped to the piece of code that reads the Request body, not the code holding the Client.

XHTTP #

XHTTP solves the above problems by making Client a concrete type, and pushing platform and app specific behaviors down into smaller, focused classes. For example streaming vs. all-at-once responses are handled by the Response type; Browser vs. VM functionality is implemented by RoundTripper which sends requests and manages request resources.

RoundTripper #

The Client in package:xhttp relies on a RoundTripper to execute each Request. RoundTripper manages the underlying request resources and execution. Users that need custom client behavior can probably get by using ModifyingRoundTripper which transforms requests using a callback. Other users can subtype or compose different RoundTripper implementations as needed.

Streaming Requests #

Each Request body is a ByteStream. The stream can be read incrementally via Request.bodyBytes or all at once using Request.body.

Examples #

Stream the response body. #

Future<void> main() async {
  final client = Client();
  final response = await client.get(Uri.parse(exampleURL));
  response.bodyBytes.listen(decodeAndPrint);
  client.close();
}

Consume the response body all at once. #

Future<void> main() async {
  final client = Client();
  final response = await client.get(Uri.parse(exampleURL));
  print(await response.body);
  client.close();
}

Embed OAuth2 tokens in requests. #

const token = 'secret-auth-token';

Request authenticate(Request request) {
    final clone = Request.clone(request);
    clone.headers['Authorizaton'] = 'Bearer \$token';
    return clone;
}

final transport = ModifyingRoundTripper(authenticate);
final client = Client.withRoundTripper(transport);
client.get('https://myapp.com/protected/resource');

1.0.1 #

  • Fix browser request payload type

1.0.0 #

  • Remove Request/Response ==; this can never really be true because each object's body is async and can't be compared.

0.2.3 #

  • Add travis badge and fix broken config

0.2.2 #

  • Update readme with pub badge
  • Add travis config

0.2.1 #

  • Move example to examples/main.dart
  • Add CHANGELOG.md.

0.2.0 #

  • Added support for redirects in Request.

0.1.0 #

  • Initial commit

example/main.dart

import 'package:xhttp/xhttp.dart';

const exampleURL = 'https://postman-echo.com/get?foo1=bar1&foo2=bar2';

Future<void> main() async {
  final client = Client();
  final response = await client.get(Uri.parse(exampleURL));
  print(await response.body);
  client.close();
}

Use this package as a library

1. Depend on it

Add this to your package's pubspec.yaml file:


dependencies:
  xhttp: ^1.0.1

2. Install it

You can install packages from the command line:

with pub:


$ pub get

with Flutter:


$ flutter pub get

Alternatively, your editor might support pub get or flutter pub get. Check the docs for your editor to learn more.

3. Import it

Now in your Dart code, you can use:


import 'package:xhttp/xhttp.dart';
  
Popularity:
Describes how popular the package is relative to other packages. [more]
3
Health:
Code health derived from static analysis. [more]
100
Maintenance:
Reflects how tidy and up-to-date the package is. [more]
91
Overall:
Weighted score of the above. [more]
50
Learn more about scoring.

We analyzed this package on Jul 14, 2020, and provided a score, details, and suggestions below. Analysis was completed with status completed using:

  • Dart: 2.8.4
  • pana: 0.13.15

Maintenance suggestions

The package description is too short. (-9 points)

Add more detail to the description field of pubspec.yaml. Use 60 to 180 characters to describe the package, what it does, and its target use case.

Dependencies

Package Constraint Resolved Available
Direct dependencies
Dart SDK >=2.7.0 <3.0.0
build_runner >=1.6.2 <2.0.0 1.10.0
http_parser ^3.1.3 3.1.4
meta ^1.1.8 1.2.2 1.3.0-nullsafety
pedantic ^1.9.0 1.9.2
quiver ^2.1.2+1 2.1.3
Transitive dependencies
_fe_analyzer_shared 5.0.0
analyzer 0.39.13
args 1.6.0
async 2.4.2
build 1.3.0
build_config 0.4.2
build_daemon 2.1.4
build_resolvers 1.3.10
build_runner_core 5.2.0 6.0.0
built_collection 4.3.2
built_value 7.1.0
charcode 1.1.3
checked_yaml 1.0.2
code_builder 3.4.0
collection 1.14.13 1.15.0-nullsafety
convert 2.1.1
crypto 2.1.5
csslib 0.16.1
dart_style 1.3.6
fixnum 0.10.11
glob 1.2.0
graphs 0.2.0
html 0.14.0+3
http_multi_server 2.2.0
io 0.3.4
js 0.6.2
json_annotation 3.0.1
logging 0.11.4
matcher 0.12.9
mime 0.9.6+3
node_interop 1.1.1
node_io 1.1.1
package_config 1.9.3
path 1.7.0
pool 1.4.0
pub_semver 1.4.4
pubspec_parse 0.1.5
shelf 0.7.7
shelf_web_socket 0.2.3
source_span 1.7.0
stack_trace 1.9.5
stream_channel 2.0.0
stream_transform 1.2.0
string_scanner 1.0.5
term_glyph 1.1.0
timing 0.1.1+2
typed_data 1.2.0 1.3.0-nullsafety
watcher 0.9.7+15
web_socket_channel 1.1.0
yaml 2.2.1
Dev dependencies
build_web_compilers >=1.2.0 <3.0.0
test ^1.12.0