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';
+
+/**

[kevmoo, 2014/05/23 21:22:24]

All packages are moving towards triple-slash "///" doc comments.

See tools/line_doc_comments.dart

[Søren Gjesse, 2014/05/26 07:12:46]

In my opinion the "///" doc comments are harder to read, and does not stand out
as much in an editor. But maybe I am just old fashioned. Nothing in our style
guide to suggest one over the other.

[kustermann, 2014/05/26 09:12:31]

If you say "All packages are moving towards triple-slash". May I ask who started
this and for what reason?
And why do we say to our users in the style guide we've got 2 different
equivalent ways of commenting but we pick the triple-slash way?

+ * 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.

[kevmoo, 2014/05/23 21:22:24]

`true`

[kustermann, 2014/05/26 09:12:31]

Done.

+   */
+  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 the 'Cookie' and 'Set-Cookie' headers the comma-separated list

[kevmoo, 2014/05/23 21:22:24]

We should not specify an undefined behavior for a base interface.

Specifying either `null` or throw InvalidSomething... is better.

I'd likely lean towards throw. Meaning, it always throws, even if the cookie
header is not set w/ a clear message telling the caller to use getMultiple

[Søren Gjesse, 2014/05/26 07:12:46]

If we should specify something here lets go for throwing. Something like "For
header field-names which does not allow combining multiple values with comma
using this index operator will throw `IllegalArgument`. This is currently the
case for header field-names 'Cookie' and 'Set-Cookie'. Use the `getMultiple`
method to iterate the header values for these".

[kustermann, 2014/05/26 09:12:31]

Done.

+   * representation does not work, and for these headers using this method is
+   * undefined. Use the `getMultiple` method for these headers.
+   */
+  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>> get body;

[kevmoo, 2014/05/23 21:22:24]

Use a method here: read()

In many cases, the body can only be accessed once. Documentation should
highlight this.

See
https://github.com/dart-lang/bleeding_edge/blob/master/dart/pkg/shelf/lib/src...

[kustermann, 2014/05/26 09:12:31]

Done.

[kustermann, 2014/05/26 09:12:31]

Done.

+}
+
+
+/**
+ * Representation of a HTTP response.
+ */
+abstract class Response {
+  /**
+   * Response status code.
+   */
+  int get statusCode;

[Søren Gjesse, 2014/05/26 07:12:46]

If we remove reasonPhrase lets change this to just 'status'. In SPDY and
HTTP/2.0 it is the header-field name ':status'.

[kustermann, 2014/05/26 09:12:31]

Done.

[kustermann, 2014/05/26 09:12:31]

Done.

+
+  /**
+   * Response reason phrase.
+   */
+  String get reasonPhrase;

[kevmoo, 2014/05/23 21:22:24]

Can we skip this?

It's not supported in HTTP 2.0 - http://http2.github.io/http2-spec/#HttpHeaders

We could create an class in a helper package (http_parser?) that has exposes the
Map<int, String> for each StatusCode

[Søren Gjesse, 2014/05/26 07:12:46]

I am OK with that - I does not add much value.

The HTTP status code enumeration could be in this package - it is pretty basic.
We already have it once in dart:io. Lets think about it before we add to much
here for now.

For HTTP 1.1 and SPDY a server should add a reason phrase. It can be empty, but
can cause issues if it is.

[kustermann, 2014/05/26 09:12:31]

Removed.

+
+  /**
+   * Response headers.
+   */
+  Headers get headers;
+
+  /**
+   * Response body.
+   */
+  Stream<List<int>> get body;

[kevmoo, 2014/05/23 21:22:24]

read() here, too. Same as above.

[kustermann, 2014/05/26 09:12:31]

Done.

+}
+
+
+
+/**
+ * Function for performing an http request.

[Søren Gjesse, 2014/05/23 12:25:30]

http -> HTTP

Here is says 'an HTTP', and other places 'a HTTP'. It should be consistent.

[kustermann, 2014/05/26 09:12:31]

Done.

+ *
+ * The [HttpClient] may use any transport mechanism it wants
+ * (e.g. HTTP/1.1, HTTP/2.0, SPDY) to perform the http request.
+ *
+ * [HttpClient]s are composable. E.g. A [HttpClient] may add an
+ * 'Authorization' header to [request] and forward to another [HttpClient].
+ *
+ * A [HttpClient] handler 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> HttpClient(Request request);

[kevmoo, 2014/05/23 21:22:24]

We must not export two identical typedefs. Not worth the confusion.

Happy to have a conversation about a name that works well on both sides.

For now, I'd argue that we get rid of HttpRequestHandler

[kevmoo, 2014/05/23 21:22:24]

There is already an HttpClient in dart:io. We DON'T want to collide w/ that
type.

[kevmoo, 2014/05/23 22:07:05]

Requester?

[Søren Gjesse, 2014/05/26 07:12:46]

I agree that this can be confusing. However the "client" side will be sending
the request over some network transport having some server actually handle the
request. A "client" might "decorate" the request object to handle e.g.
authentication before sending the request.

The "server" side is supposed to actually perform the processing of the request.

HttpClient could just be Client. However a client is not really handling the
request - some server is.

[kustermann, 2014/05/26 09:12:31]

Removed the prefix, users should use prefix imports (since the name Client is
very ambiguous).
I agree with Soeren: These typedef names will be used by functions, and it makes
it much clearer (in terms of documentation) whether something should be a
HttpClient or something is a HttpRequestHandler.

I'll keep the two typedefs for now.

+
+/**
+ * Function for handling an http request.

[Søren Gjesse, 2014/05/23 12:25:30]

http -> HTTP

[kustermann, 2014/05/26 09:12:31]

Done.

[kustermann, 2014/05/26 09:12:31]

Done.

+ *
+ * The [HttpRequestHandler] should not react on any connection specific headers
+ * in [request] and connection specific headers in it's [Response] may be
+ * ignored by an Http Server.

[Søren Gjesse, 2014/05/23 12:25:30]

Http -> HTTP

[kustermann, 2014/05/26 09:12:31]

Done.

[kustermann, 2014/05/26 09:12:31]

Done.

+ *
+ * [HttpRequestHandler]s are composable. E.g. A [HttpRequestHandler] may call
+ * another [HttpRequestHandler] and augment the headers with a 'Set-Cookie'

[Søren Gjesse, 2014/05/23 12:25:30]

with -> with e.g.

[kustermann, 2014/05/26 09:12:31]

Done.

[kustermann, 2014/05/26 09:12:31]

Done.

+ * header.
+ *
+ * Connection specific headers:
+ *    'Connection', 'Upgrade', 'Keep-Alive', 'Transfer-Encoding'
+ */
+typedef Future<Response> HttpRequestHandler(Request request);

[kevmoo, 2014/05/23 22:07:05]

Eliminate this typedef. We only have confusion if we have two identical types.

[kustermann, 2014/05/26 09:12:31]

Not done. See above.