From 58f87c32c4ddcab934233869cf2369a849785929 Mon Sep 17 00:00:00 2001 From: Brian Quinlan Date: Fri, 1 Dec 2023 11:13:52 -0800 Subject: [PATCH] Update README.md --- pkgs/http/README.md | 128 +++++++++++++++++++++++++++++++++----------- 1 file changed, 97 insertions(+), 31 deletions(-) diff --git a/pkgs/http/README.md b/pkgs/http/README.md index d655f98f5e..152e8965d0 100644 --- a/pkgs/http/README.md +++ b/pkgs/http/README.md @@ -4,16 +4,11 @@ A composable, Future-based library for making HTTP requests. This package contains a set of high-level functions and classes that make it -easy to consume HTTP resources. It's multi-platform, and supports mobile, desktop, -and the browser. +easy to consume HTTP resources. It's multi-platform (mobile, desktop, and +browser) and supports multiple implementations. ## Using -> [!TIP] -> The Dart [Fetch data from the internet](https://dart.dev/tutorials/server/fetch-data) and Flutter -> [Networking Cookbook](https://docs.flutter.dev/data-and-backend/networking) have more detailed -> examples. - The easiest way to use this library is via the top-level functions. They allow you to make individual HTTP requests with minimal hassle: @@ -28,6 +23,11 @@ print('Response body: ${response.body}'); print(await http.read(Uri.https('example.com', 'foobar.txt'))); ``` +> [!NOTE] +> Flutter applications may require +> [additional configuration](https://docs.flutter.dev/data-and-backend/networking#platform-notes) +> to make HTTP requests. + If you're making multiple requests to the same server, you can keep open a persistent connection by using a [Client][] rather than making one-off requests. If you do this, make sure to close the client when you're done: @@ -46,6 +46,11 @@ try { } ``` +> [!TIP] +> For detailed background information and practical usage examples, see: +> - [Dart Development: Fetch data from the internet](https://dart.dev/tutorials/server/fetch-data) +> - [Flutter Cookbook: Fetch data from the internet](https://docs.flutter.dev/cookbook/networking/fetch-data) + You can also exert more fine-grained control over your requests and responses by creating [Request][] or [StreamedRequest][] objects yourself and passing them to [Client.send][]. @@ -108,10 +113,10 @@ the [`RetryClient()`][new RetryClient] constructor. ## Choosing an implementation -There are multiple implementations of the `package:http` `Client` interface. -You can chose which implementation to use based on the needs of your -application. You can change implementations without changing your application -code, except for a few lines of [configuration](). +There are multiple implementations of the `package:http` [`Client`][client] interface. By default, `package:http` uses [`BrowserClient`][browserclient] on the web and [`IOClient`][ioclient] on all other platforms. You an choose a different [`Client`][client] implementation based on the needs of your application. + +You can change implementations without changing your application code, except +for a few lines of [configuration](). Some well supported implementations are: @@ -123,32 +128,93 @@ Some well supported implementations are: | [`package:cronet_http`][cronethttp] — [`CronetClient`][cronetclient] | Android | Flutter | ✅︎ | ✅︎ | ― | | [`package:fetch_client`][fetch] — [`FetchClient`][fetchclient] | Web | Dart, Flutter | ✅︎ | ✅︎ | ✅︎ | - -[ioclient]: https://pub.dev/documentation/http/latest/io_client/IOClient-class.html -[browserclient]: https://pub.dev/documentation/http/latest/browser_client/BrowserClient-class.html -[cupertinohttp]: https://pub.dev/packages/cupertino_http -[cupertinoclient]: https://pub.dev/documentation/cupertino_http/latest/cupertino_http/CupertinoClient-class.html -[cronethttp]: https://pub.dev/packages/cronet_http -[cronetclient]: https://pub.dev/documentation/cronet_http/latest/cronet_http/CronetClient-class.html -[fetch]: https://pub.dev/packages/fetch_client -[fetchclient]: https://pub.dev/documentation/fetch_client/latest/fetch_client/FetchClient-class.html +> [!TIP] +> If you are writing a Dart package or Flutter pluggin that uses +> `package:http`, you should not depend on a particular [`Client`][client] +> implementation. Let the application author decide what implementation is +> best for their project. You can make that easier by accepting an explicit +> [`Client`][client] argument. For example: +> +> ```dart +> Future fetchAlbum({Client? client}) async { +> client ??= Client(); +> ... +> } +> ``` ## Configuration +To use a HTTP client implementation other than the default, you must: +1. Add the HTTP client as a dependency. +2. Configure the HTTP client. +3. Connect it to the code that uses it. + +### 1. Add the HTTP client as a dependency. + +To add a package compatible with the Dart SDK to your project, use `dart pub add`. + +For example: + ```terminal -flutter pub add http +# Replace "fetch_client" with the package that you want to use. +dart pub add fetch_client ``` +To add a package that requires the Flutter SDK, use `flutter pub add`. +For example: + +```terminal +# Replace "cupertino_http" with the package that you want to use. +flutter pub add cupertino_http ``` -late Client client; -if (Platform.isIOS) { - final config = URLSessionConfiguration.ephemeralSessionConfiguration() - ..allowsCellularAccess = false - ..allowsConstrainedNetworkAccess = false - ..allowsExpensiveNetworkAccess = false; - client = CupertinoClient.fromSessionConfiguration(config); -} else { - client = IOClient(); // Uses an HTTP client based on dart:io + +### 2. Configure the HTTP client. + +Different `package:http` [`Client`][client] implementations may require +different configuration options. + +Add a function that returns a correctly configured [`Client`][client]. You can +return a different [`Client`][client] on different platforms. + +For example: + +```dart +Client httpClient() { + if (Platform.isIOS || Platform.isMacOS) { + final config = URLSessionConfiguration.ephemeralSessionConfiguration() + ..cache = URLCache.withCapacity(memoryCapacity: 1000000); + return CupertinoClient.fromSessionConfiguration(config); + } + return Client(); // Return the default client for all other platforms. } -``` \ No newline at end of file +``` + + + +`runWithClient` +import 'package:provider/provider.dart'; + + + +https://github.com/dart-lang/http/tree/master/pkgs/flutter_http_example + + +For example: + +```terminal +flutter pub add cupertino_http +``` + +https://github.com/dart-lang/http/tree/master/pkgs/flutter_http_example + + +[client]: https://pub.dev/documentation/http/latest/http/Client-class.html +[ioclient]: https://pub.dev/documentation/http/latest/io_client/IOClient-class.html +[browserclient]: https://pub.dev/documentation/http/latest/browser_client/BrowserClient-class.html +[cupertinohttp]: https://pub.dev/packages/cupertino_http +[cupertinoclient]: https://pub.dev/documentation/cupertino_http/latest/cupertino_http/CupertinoClient-class.html +[cronethttp]: https://pub.dev/packages/cronet_http +[cronetclient]: https://pub.dev/documentation/cronet_http/latest/cronet_http/CronetClient-class.html +[fetch]: https://pub.dev/packages/fetch_client +[fetchclient]: https://pub.dev/documentation/fetch_client/latest/fetch_client/FetchClient-class.html \ No newline at end of file