Add initial version of http_base package

dart/pkg/http_base/lib/http_base.dart

+// Copyright (c) 2014, 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 http_base;
+
+import 'dart:async';
+
+/**
+ * Representation of a set of HTTP headers.
+ */
+abstract class Headers {
+  /**
+   * Returns the names of all header fields.
+   */
+  Iterable<String> get names;
+
+  /**
+   * Returns `true` if a header field of the specified [name] exist.
+   */
+  bool contains(String name);
+
+  /**
+   * Returns the value for the header field named [name].
+   *
+   * The HTTP standard supports multiple values for each header field name.
+   * Header fields with multiple values can be represented as a
+   * comma-separated list. If a header has multiple values the returned string
+   * is the comma-separated list of all these values.
+   *
+   * For header field-names which do not allow combining multiple values with
+   * comma, this index operator will throw `IllegalArgument`.
+   * This is currently the case for the 'Cookie' and 'Set-Cookie' headers. Use
+   * `getMultiple` method to iterate over the header values for these.
+   */
+  String operator [](String name);
+
+  /**
+   * Returns the values for the header field named [name].
+   *
+   * The order in which the values for the field name appear is the same
+   * as the order in which they are to be send or was received.
+   */
+  Iterable<String> getMultiple(String name);
+}
+
+
+/**
+ * Representation of a HTTP request.
+ */
+abstract class Request {
+  /**
+   * Request method.
+   */
+  String get method;
+
+  /**
+   * Request url.
+   */
+  Uri get url;
+
+  /**
+   * Request headers.
+   */
+  Headers get headers;
+
+  /**
+   * Request body.
+   */
+  Stream<List<int>> read();
+}
+
+
+/**
+ * Representation of a HTTP response.
+ */
+abstract class Response {
+  /**
+   * Response status code.
+   */
+  int get status;
+
+  /**
+   * Response headers.
+   */
+  Headers get headers;
+
+  /**
+   * Response body.
+   */
+  Stream<List<int>> read();
+}
+
+
+
+/**
+ * Function for performing a HTTP request.
+ *
+ * The [Client] may use any transport mechanism it wants
+ * (e.g. HTTP/1.1, HTTP/2.0, SPDY) to perform the HTTP request.
+ *
+ * [Client]s are composable. E.g. A [Client] may add an 'Authorization'
+ * header to [request] and forward to another [Client].
+ *
+ * A [Client] may ignore connection specific headers in [request] and may
+ * not present them in the [Response] object.
+ *
+ * Connection specific headers:
+ *    'Connection', 'Upgrade', 'Keep-Alive', 'Transfer-Encoding'
+ */
+typedef Future<Response> Client(Request request);
+
+/**
+ * Function for handling a HTTP request.
+ *
+ * The [RequestHandler] should not react on any connection specific headers
+ * in [request] and connection specific headers in it's [Response] may be
+ * ignored by a HTTP Server.
+ *
+ * [RequestHandler]s are composable. E.g. A [RequestHandler] may call another
+ * [RequestHandler] and augment the headers with e.g. a 'Set-Cookie' header.
+ *
+ * Connection specific headers:
+ *    'Connection', 'Upgrade', 'Keep-Alive', 'Transfer-Encoding'
+ */
+typedef Future<Response> HttpRequestHandler(Request request);