Add an HTTP library that wraps dart:io.

pkg/http/lib/http.dart

+// Copyright (c) 2012, the Dart project authors.  Please see the AUTHORS file
+// for details. All rights reserved. Use of this source code is governed by a
+// BSD-style license that can be found in the LICENSE file.
+
+/// A composable, [Future]-based library for making HTTP requests.
+///
+/// The easiest way to use this library is via the top-level functions. They
+/// allow you to make individual HTTP requests with minimal hassle:
+///
+///     import 'package:http/http.dart' as http;
+///
+///     var uri = new Uri.fromString("http://example.com/whatsit/create");

[Bob Nystrom, 2012/10/31 01:17:44]

This makes me wonder if the top-level functions should accept strings for the
first argument too.

[nweiz, 2012/10/31 18:20:59]

That makes the type signature pretty ugly, but I guess it's probably worth it
for usability. What are your thoughts on adding a "Url" or "StringOrUri" typedef
for better documentation?

[Bob Nystrom, 2012/11/01 19:53:59]

I don't think we can use typedefs for this, at least not yet. As far as I know,
typedef is still just for function types right now. I guess we should probably
just leave it typed and then document that it can take a URI or a string.

[nweiz, 2012/11/02 19:29:12]

By "leave it typed" do you mean "leave it untyped"?

[Bob Nystrom, 2012/11/02 19:35:03]

Yup, sorry.

+///     http.post(uri, fields: {"name": "doodle", "color": "blue"})
+///         .then((response) {
+///       print("Response status: ${response.statusCode}");
+///       print("Response body: ${response.body}");
+///     });
+///
+///     http.read(new Uri.fromString("http://example.com/foobar.txt"))
+///         .then((body) {

[Bob Nystrom, 2012/10/31 01:17:44]

For maximum terseness:

.then(print);

:)

[nweiz, 2012/10/31 18:20:59]

Done.

+///       print("Response body: $body");
+///     });
+///
+/// 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:

[Bob Nystrom, 2012/10/31 01:17:44]

Add, "If you do this, make sure to close the client when you are done."

[nweiz, 2012/10/31 18:20:59]

Done.

+///
+///     var client = new http.Client();
+///     var baseUri = new Uri.fromString("http://example.com/");
+///     client.post(
+///         baseUri.relative("whatsit/create",
+///         fields: {"name": "doodle", "color": "blue"})
+///       .chain((response) => client.get(response.bodyFields['uri']));
+///
+/// You can also exert more fine-grained control over your requests and
+/// responses by creating [Request] or [StreamRequest] objects yourself and
+/// passing them to [Client.send].
+///
+/// This package is designed to be composable. This makes it easy for external
+/// libraries to work with one another to add behavior to it. Libraries wishing
+/// to add behavior should create a subclass of [BaseClient] that wraps another
+/// [BaseClient] and adds the desired behavior:
+///
+///     class UserAgentClient extends http.BaseClient {
+///       final String userAgent;
+///       final HttpClient _inner;
+///
+///       UserAgentClient(this.userAgent, this._inner);
+///
+///       Future<StreamResponse> send(BaseRequest request) {
+///         request.headers[HttpHeaders.USER_AGENT] = userAgent;
+///         return _inner.send(request);
+///       }
+///     }
+///
+/// In turn, libraries using [Client] should take a [BaseClient] so that the
+/// decorated clients can be used transparently.
+
+library http;
+
+import 'dart:scalarlist';
+import 'dart:uri';
+
+import 'src/client.dart';
+import 'src/response.dart';
+
+export 'src/base_client.dart';
+export 'src/base_request.dart';
+export 'src/base_response.dart';
+export 'src/client.dart';
+export 'src/request.dart';
+export 'src/response.dart';
+export 'src/stream_request.dart';
+export 'src/stream_response.dart';

[Bob Nystrom, 2012/10/31 01:17:44]

This is really awesome.

+
+/// Send an HTTP HEAD request with the given headers to the given URI.
+///
+/// This automatically initializes a new [Client] and closes that client once
+/// the request is complete. If you're planning on making multiple requests to
+/// the same server, you should use a single [Client] for all of those requests.
+///
+/// For more fine-grained control over the request, use [Request] instead.
+Future<Response> head(Uri uri, {Map<String, String> headers: null}) =>
+  _withClient((client) => client.head(uri, headers: headers));
+
+/// Send an HTTP GET request with the given headers to the given URI.
+///
+/// This automatically initializes a new [Client] and closes that client once
+/// the request is complete. If you're planning on making multiple requests to
+/// the same server, you should use a single [Client] for all of those requests.
+///
+/// For more fine-grained control over the request, use [Request] instead.
+Future<Response> get(Uri uri, {Map<String, String> headers: null}) =>
+  _withClient((client) => client.get(uri, headers: headers));
+
+/// Send an HTTP POST request with the given headers and fields to the given
+/// URI. If any fields are specified, the content-type is automatically set to
+/// `"application/x-www-form-urlencoded"`.
+///
+/// This automatically initializes a new [Client] and closes that client once
+/// the request is complete. If you're planning on making multiple requests to
+/// the same server, you should use a single [Client] for all of those requests.
+///
+/// For more fine-grained control over the request, use [Request] or
+/// [StreamRequest] instead.
+Future<Response> post(Uri uri,
+    {Map<String, String> headers: null,
+     Map<String, String> fields: null}) =>
+  _withClient((client) => client.post(uri, headers: headers, fields: fields));
+
+/// Send an HTTP POST request with the given headers and fields to the given
+/// URI. If any fields are specified, the content-type is automatically set to
+/// `"application/x-www-form-urlencoded"`.
+///
+/// This automatically initializes a new [Client] and closes that client once
+/// the request is complete. If you're planning on making multiple requests to
+/// the same server, you should use a single [Client] for all of those requests.
+///
+/// For more fine-grained control over the request, use [Request] or
+/// [StreamRequest] instead.
+Future<Response> put(Uri uri,
+    {Map<String, String> headers: null,
+     Map<String, String> fields: null}) =>
+  _withClient((client) => client.put(uri, headers: headers, fields: fields));
+
+/// Send an HTTP DELETE request with the given headers to the given URI.
+///
+/// This automatically initializes a new [Client] and closes that client once
+/// the request is complete. If you're planning on making multiple requests to
+/// the same server, you should use a single [Client] for all of those requests.
+///
+/// For more fine-grained control over the request, use [Request] instead.
+Future<Response> delete(Uri uri, {Map<String, String> headers: null}) =>
+  _withClient((client) => client.delete(uri, headers: headers));
+
+/// Send an HTTP GET request with the given headers to the given URI, and return
+/// a Future that completes to the body of the response as a String.
+///
+/// The Future will emit an [HttpException] if the response doesn't have a
+/// success status code.
+///
+/// This automatically initializes a new [Client] and closes that client once
+/// the request is complete. If you're planning on making multiple requests to
+/// the same server, you should use a single [Client] for all of those requests.
+///
+/// For more fine-grained control over the request and response, use [Request]
+/// instead.
+Future<String> read(Uri uri, {Map<String, String> headers: null}) =>
+  _withClient((client) => client.read(uri, headers: headers));
+
+/// Send an HTTP GET request with the given headers to the given URI, and
+/// return a Future that completes to the body of the response as a list of
+/// bytes.
+///
+/// The Future will emit an [HttpException] if the response doesn't have a
+/// success status code.
+///
+/// This automatically initializes a new [Client] and closes that client once
+/// the request is complete. If you're planning on making multiple requests to
+/// the same server, you should use a single [Client] for all of those requests.
+///
+/// For more fine-grained control over the request and response, use [Request]
+/// instead.
+Future<Uint8List> readBytes(Uri uri, {Map<String, String> headers: null}) =>
+  _withClient((client) => client.readBytes(uri, headers: headers));
+
+Future _withClient(Future fn(Client)) {
+  var client = new Client();
+  var future = fn(client);
+  future.onComplete((_) => client.close());
+  return future;
+}