Add an HTTP library that wraps dart:io.

pkg/http/lib/src/base_client.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.
+
+library base_client;
+
+import 'dart:io';
+import 'dart:scalarlist';
+import 'dart:uri';
+
+import 'base_request.dart';
+import 'request.dart';
+import 'response.dart';
+import 'stream_response.dart';
+import 'utils.dart';
+
+/// The abstract base class for an HTTP client. This is a mixin-style class;
+/// subclasses only need to implement [send] and maybe [close], and then they
+/// get various convenience methods for free.
+abstract class BaseClient {
+  /// Send an HTTP HEAD request with the given headers to the given URI.

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

"Send" -> "Sends" here and elsewhere. I think we use progressive tense for
method docs?

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

Done. Guess I got too used to Python's style.

+  ///
+  /// For more fine-grained control over the request, use [send] instead.
+  Future<Response> head(Uri uri, {Map<String, String> headers: null}) =>

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

The ": null" shouldn't be required here and elsewhere.

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

Done.

+    _sendNoStream("HEAD", uri, headers);

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

Since this is a line continuation, it should be indented +4. But I do like that
this isn't indented as far as the parameter lists in the methods below.

Thoughts?

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

I like indenting this +2, since it reads more like the body of the method than
like a continued expression.

+
+  /// Send an HTTP GET request with the given headers to the given URI.
+  ///
+  /// For more fine-grained control over the request, use [send] instead.
+  Future<Response> get(Uri uri, {Map<String, String> headers: null}) =>
+    _sendNoStream("GET", uri, 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"`.
+  ///
+  /// For more fine-grained control over the request, use [send] instead.
+  Future<Response> post(Uri uri,
+      {Map<String, String> headers: null,
+       Map<String, String> fields: null}) =>
+    _sendNoStream("POST", uri, headers, fields);
+
+  /// Send an HTTP PUT 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"`.
+  ///
+  /// For more fine-grained control over the request, use [send] instead.
+  Future<Response> put(Uri uri,
+      {Map<String, String> headers: null,
+       Map<String, String> fields: null}) =>
+    _sendNoStream("PUT", uri, headers, fields);
+
+  /// Send an HTTP DELETE request with the given headers to the given URI.
+  ///
+  /// For more fine-grained control over the request, use [send] instead.
+  Future<Response> delete(Uri uri, {Map<String, String> headers: null}) =>
+    _sendNoStream("DELETE", uri, 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.
+  ///
+  /// For more fine-grained control over the request and response, use [send] or
+  /// [get] instead.
+  Future<String> read(Uri uri, {Map<String, String> headers: null}) {
+    return get(uri, headers: headers).transform((response) {
+      _checkResponseSuccess(response);
+      return response.body;
+    });
+  }
+
+  /// 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.
+  ///
+  /// For more fine-grained control over the request and response, use [send] or
+  /// [get] instead.
+  Future<Uint8List> readBytes(Uri uri, {Map<String, String> headers: null}) {
+    return get(uri, headers: headers).transform((response) {
+      _checkResponseSuccess(response);
+      return response.bodyBytes;
+    });
+  }
+
+  /// Send an HTTP request and asynchronously return the response.
+  ///
+  /// Implementers should call [BaseRequest.finalize] to get the body of the
+  /// request as an [InputStream]. They shouldn't make any assumptions about the
+  /// state of the stream; it could have data written to it asynchronously at a
+  /// later point, or it could already be closed when it's returned.
+  Future<StreamResponse> send(BaseRequest request);
+
+  /// Send a non-streaming [Request] and return a non-streaming [Response].
+  Future<Response> _sendNoStream(

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

This name feels a bit strange to me. Maybe "_sendUnstreamed" or
"_sendNonstreamed"?

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

Done.

+      String method,
+      Uri uri,
+      Map<String, String> headers,

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

Nit, but how about having the required params all on one line?

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

Done.

+      [Map<String, String> fields]) {
+    // Wrap everything in a Future block so that synchronous validation errors
+    // are passed through the Future chain.
+    return new Future.immediate(null).chain((_) {

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

This can still cause errors to be sent synchronously. Do you think this should
explicitly pump the message queue to ensure it's consistently async?

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

Done.

+      var request = new Request(method, uri);
+
+      if (headers != null) mapAddAll(request.headers, headers);
+      if (fields != null && !fields.isEmpty) request.bodyFields = fields;
+
+      return send(request);
+    }).chain(Response.fromStream);
+  }
+
+  /// Throw an error if [response] is not successful.
+  void _checkResponseSuccess(Response response) {
+    if (response.statusCode < 400) return;
+    var message = "Request to $uri failed with status ${response.statusCode}";
+    if (response.reasonPhrase != null) {
+      message = "$message: ${response.reasonPhrase}";
+    }
+    throw new HttpException("$message.");

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

Pub has its own PubHttpException class specifically to expose the reason and
status code as properties. How about copying that here (and then ditching the
pub one when pub uses this)?

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

I feel like that would be more confusing than it would be worth. The vast
majority of errors thrown by this package are still going to be HttpErrors;
you'd only get that particular HTTP error with status/reason when you use read
or readBytes in particular. It would almost never be correct to catch only it
and not also the underlying HTTP errors, and in the few cases where it is right
the user can use #get manually anyway.

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

Yeah, I definitely wouldn't want to mix and match error types. But could we
consistently return a single HTTP error type that has useful fields?

I made this change in pub's io.dart because there is code in pub that looks at
the status code to give a better error message. It's nice to have the exception
object expose that directly.

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

The thing is, most HTTP errors happen because of things like the response
failing to parse or some formatting error in the request. In most cases it
doesn't make sense to add extra metadata. Really the only case where it would is
for these convenience methods, and that raises the issues I described above.

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

SGTM.

+  }
+
+  /// Close the client and clean up any resources associated with it. It's
+  /// important to close each client when it's done being used; failing to do so
+  /// can cause the Dart process to hang.
+  void close() {}
+}