Introduce HttpHeaders interface

[DartBot]

This issue was originally filed by @seaneagan

---

Currently the Http[Client]{Request,Response} interfaces all have:

Map get headers();
int get contentLength();
bool get keepAlive();

There is a bunch of other header-specific functionality which would be useful to add as well:

* more dedicated fields for specific headers, especially those which represent Dates, Durations, ints, Cookies, MimeTypes, Links, etc.

• static constants for standard header names
• helper functions to convert to and from http dates etc.

Thus it seems to deserve its own dedicated interface, which might look something like...

interface HttpHeaders extends MultiMap<String, String> {
  // helper methods for converting to and from http dates
  static String fromDate(Date date);
  static Date toDate(String headerValue);

  bool keepAlive; // Keep-Alive
  int contentLength; // Content-Length

  // additional useful header fields
  MimeType contentType; // Content-Type
  bool noCache; // Cache-Control : no-cache / Pragma: no-cache
  Date date; // Date
  List<Cookie>cookies; // Cookie / Set-Cookie
}

Many headers though, are request-specific or response-specific, so there probably should be dedicated interfaces for each...

interface HttpResponseHeaders extends HttpHeaders {
  // valid request header names
  static final String AGE/* = 'Age'/;
  //...
  static final String CONTENT_LENGTH/ = 'Content-Length'*/;
  //...

  Duration age; // Age
  Duration maxAge; // Max-Age
  Duration retryAfter; // Retry-After
  Date lastModified; // Last-Modified
  Date expires; // Expires
  String fileName; // Content-Disposition: attachment; filename= ...
  List<Link> links; // Link
}

interface HttpRequestHeaders {
  // valid request header names
  static final String ACCEPT/* = 'Accept'/;
  //...
  static final String CONTENT_LENGTH/ = 'Content-Length'*/;
  //...

  Date ifModifiedSince; // If-Modified-Since
  int maxForwards; // Max-Forwards
  List<MimeType> accept; // Accept
}

These could then be surfaced as follows...

interface HttpRequest {
  //...
  final HttpRequestHeaders headers;
}

interface HttpClientRequest {
  //...
  HttpRequestHeaders headers;
}

interface HttpResponse {
  //...
  final HttpResponseHeaders headers;
}

interface HttpClientResponse {
  //...
  HttpResponseHeaders headers;
}

[madsager]

cc @sgjesse.
Added Area-IO, Triaged labels.

[DartBot]

This comment was originally written by @seaneagan

---

Also, HttpHeaders#toString should return the headers formatted as they would be in an http message, and it might be useful to have a constructor which takes a string of all headers as formatted in an http message as well for creating the headers object on the receiving end:

HttpRequestHeaders.fromString(String headerString);
HttpResponseHeaders.fromString(String headerString);

[jmesserly]

Also, HttpHeaders should be a Map, or at least support enumeration of headers. dartbug.com/2785

[jmesserly]

Issue #2785 has been merged into this issue.

[sgjesse]

The HttpHeaders interface was introduced in https://code.google.com/p/dart/source/detail?r=6567.

---

Set owner to @sgjesse.
Added Started label.

[DartBot]

This comment was originally written by @seaneagan

---

I noticed header enumeration was added in:

https://code.google.com/p/dart/source/detail?r=7377

via:

void forEach(void f(String name, List<String> values));

I agree with comment 3 that it would be better to just extend Map. HttpHeaders is missing many useful methods of Maps, such as "containsKey". So one would have to do:

  bool hasHeader = false;
  headers.forEach((String h, List<String> values) { if(h = header) hasHeader = true;});

instead of just:

bool hasHeader = headers.containsKey(header);

or to use composition instead of inheritance, HttpHeaders could have a "raw" getter:

Map<String, List<String>> get raw();

As far as the case-insensitive issue, just do the same thing you are doing already of converting all header name inputs to lower case.

Dealing with individual header values is not perfect when using a Map<String, List<String>>, as it should really be a MultiMap<String, String>, but I think on balance it is still better than the current solution, and hopefully MultiMap will be added to dart:core with the upcoming collections refresh.

[sgjesse]

The containsKey could just be

  headers[name.toLowerCase()] != null

I agree that there are useful methods on Map which will also be useful on HttpHeaders. We will consider making HttpHeaders extend Map<String, List<String>> and implement the missing methods.

I would rather not add the "raw" getter as the HttpHeaders instance would loose control of its content. I think that we still need to add special handling of headers which are single valued (e.g. Date) so that for them set and add will be the same - and using operator []= with a list of more than one element will throw an exception.

[DartBot]

This comment was originally written by er...@codesmithtools.com

---

Why isn't there a case insensitive map?

[sgjesse]

Proposed content type handling in https://chromiumcodereview.appspot.com/10407002.

[madsager]

Added this to the M1 milestone.

[madsager]

http://api.dartlang.org/docs/continuous/dart_io/HttpHeaders.html

---

Added Fixed label.

[kevmoo]

Removed Area-IO label.
Added Area-Library, Library-IO labels.