Introduce new HttpBodyHandler to easily extract full body of HttpRequest and HttpClientResponse.

sdk/lib/io/http_body.dart

+// Copyright (c) 2013, 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.
+
+part of dart.io;
+
+/**
+ * A helper-class for HTTP library, for parsing and collecting HTTP message

[Mads Ager (google), 2013/04/10 08:20:26]

Simplify to:

[HttpBodyHandler] is a helper class for parsing and collecting HTTP message data
in an easy-to-use [HttpBody] object.

[Anders Johnsen, 2013/04/10 12:52:49]

Done.

+ * data, in a easy-to-use [HttpBody] structure.
+ *
+ * To use with the [HttpServer] for request messages, [HttpBodyHandler] can be
+ * used as either a [StreamTransformer] or as a per-request handler (see
+ * [processRequest]).

[Mads Ager (google), 2013/04/10 08:20:26]

How about adding the actual code for the two approaches to make it trivial for
users to plug this in?

[Anders Johnsen, 2013/04/10 12:52:49]

Done.

+ *
+ * To use with the [HttpClient] for response messages, [HttpBodyHandler] can be
+ * used as a per-request handler (see [processResponse]).
+ *
+ * The content body is parsed, depending on the set 'Content-Type' header field.

[Søren Gjesse, 2013/04/10 07:09:11]

Remove 'set'.

I think we should enumerate the mime types which are handled, and add that other
mime types will be handled as binary.

[Mads Ager (google), 2013/04/10 08:20:26]

How about integrating this sentence in the first paragraph instead?

[Anders Johnsen, 2013/04/10 12:52:49]

Done.

+ */
+class HttpBodyHandler

[Søren Gjesse, 2013/04/10 07:09:11]

I like the transformer class with static methods for handling one object.

However I came to think of one thing. Do we want to support configuring this
class e.g. configure that Content-type text/json should be handled as JSON as
well or that application/json should be handled as BINARY. Without an instance
it is difficult to do this for processRequest and processResponse unless we add
a configuration object which can be passed.

var handler = new HttpBodyHandler();
handler.configureContentType(new ContentType("text/json"), HttpBody.JSON);
handler.configureContentType(new ContentType("application/json"),
HttpBody.BINARY);

...

handler.processRequest(...);

vs.

var cfg = new HttpBodyHandlerConfiguration();
cfg.configureContentType(new ContentType("text/json"), HttpBody.JSON);
cfg.configureContentType(new ContentType("application/json"), HttpBody.BINARY);

...

HttpBodyHandler.processRequest(..., configuration: cfg);

Maybe that flexibility is not needed.

[Anders Johnsen, 2013/04/10 12:52:49]

As discussed offline, this will serve as a great addition down the road. (post
M4).

+    implements StreamTransformer<HttpRequest, HttpRequestBody> {
+  factory HttpBodyHandler() => new _HttpBodyHandler();
+
+  /**
+   * Process and parse an incoming [HttpRequest]. The returned [HttpRequestBody]
+   * contains a [response] field for accessing the [HttpResponse].
+   */
+  static Future<HttpRequestBody> processRequest(HttpRequest request) {
+    return _HttpBodyHandler.processRequest(request);
+  }
+
+  /**
+   * Process and parse an incoming [HttpClientResponse].
+   */
+  static Future<HttpBody> processResponse(HttpClientResponse response) {
+    return _HttpBodyHandler.processResponse(response);
+  }
+}
+
+/**
+ * A HTTP content body produced by [HttpBodyHandler] for either [HttpRequest]
+ * or [HttpClientResponse].
+ */
+abstract class HttpBody {
+  static int BINARY = 0;

[Mads Ager (google), 2013/04/10 08:20:26]

Make this a real HttpBodyType type instead of an int using the usual enum
pattern?

That way, the type of the 'type' getter can be restricted from int to
HttpBodyType. 

[Anders Johnsen, 2013/04/10 12:52:49]

Done.

+  static int TEXT = 1;
+  static int JSON = 2;
+  static int FORM = 3;
+
+  /**
+   * The content type e.g. application/json, application/octet-stream,
+   * application/x-www-form-urlencoded, text/plain.
+   */
+  String get mimeType;
+
+  /**
+   * A high-level type value, that reflects how the body was parsed, e.g.
+   * [JSON], [BINARY], [FORM], [TEXT].
+   */
+  int get type;

[Mads Ager (google), 2013/04/10 08:20:26]

HttpBodyType get type;

?

[Anders Johnsen, 2013/04/10 12:52:49]

Done.

+
+  /**
+   * The actual body. The type depends on [type] ([Map] for [JSON] and [FROM],

[Søren Gjesse, 2013/04/10 07:09:11]

FROM -> FORM

[Anders Johnsen, 2013/04/10 12:52:49]

Done.

+   * [List<int>] for [BINARY] etc.
+   */
+  dynamic get body;
+
+  /**
+   * [Map] if [JSON], null otherwise.

[Mads Ager (google), 2013/04/10 08:20:26]

[Map] if [type] equals [JSON], null otherwise.

?

Ditto for the ones below.

[Anders Johnsen, 2013/04/10 12:52:49]

These are removed.

+   */
+  Map get json;
+
+  /**
+   * [List<int>] if [BINARY], null otherwise.
+   */
+  List<int> get binary;
+
+  /**
+   * [Map] if [FORM], null otherwise.
+   */
+  Map get form;
+
+  /**
+   * [String] if [TEXT], null otherwise.
+   */
+  String get text;

[Søren Gjesse, 2013/04/10 07:09:11]

Should we add isBinary, isJson, etc. as well?

[Anders Johnsen, 2013/04/10 12:52:49]

No (due to offline chat).

+}
+
+abstract class HttpRequestBody extends HttpBody {

[Mads Ager (google), 2013/04/10 08:20:26]

Add a top level comment for HttpRequestBody explaining that it is for a request
and gives access to the response object. Maybe add example code?

[Anders Johnsen, 2013/04/10 12:52:49]

Done.

+  /**
+   * The [HttpResponse] used for responding to the client.
+   */
+  HttpResponse get response;
+}