Start refactoring of the HTTP header handling

runtime/bin/http.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.
 
 /**
  * HTTP status codes.
  */
 interface HttpStatus {
   static final int CONTINUE = 100;
   static final int SWITCHING_PROTOCOLS = 101;
@@ skipping 82 matching lines @@
   void set onRequest(void callback(HttpRequest, HttpResponse));
 
   /**
    * Sets the error handler that is called when a connection error occurs.
    */
   void set onError(void callback(Exception e));
 }
 
 
 /**
+ * Access to the HTTP headers for requests and responses. In some
+ * situations the headers will be imutable and the mutating methods
+ * will then throw exceptions.
+ *
+ * For all operation on HTTP headers the header name is
+ * case-insensitive.
+ */
+interface HttpHeaders default _HttpHeaders {

[Anders Johnsen, 2012/04/13 11:47:53]

Very neat, I like how you expose all normal headers, including categories!
Should headers related WebSockets be grouped together?

[Søren Gjesse, 2012/04/16 11:37:16]

They should, but maybe they should be part of the WebSocket interfaces/classes
and not HttpHeaders.

+  static final ACCEPT = "Accept";
+  static final ACCEPT_CHARSET = "Accept-Charset";
+  static final ACCEPT_ENCODING = "Accept-Encoding";
+  static final ACCEPT_LANGUAGE = "Accept-Language";
+  static final ACCEPT_RANGES = "Accept-Ranges";
+  static final AGE = "Age";
+  static final ALLOW = "Allow";
+  static final AUTHORIZATION = "Authorization";
+  static final CACHE_CONTROL = "Cache-Control";
+  static final CONNECTION = "Connection";
+  static final CONTENT_ENCODING = "Content-Encoding";
+  static final CONTENT_LANGUAGE = "Content-Language";
+  static final CONTENT_LENGTH = "Content-Length";
+  static final CONTENT_LOCATION = "Content-Location";
+  static final CONTENT_MD5 = "Content-MD5";
+  static final CONTENT_RANGE = "Content-Range";
+  static final CONTENT_TYPE = "Content-Type";
+  static final DATE = "Date";
+  static final ETAG = "ETag";
+  static final EXPECT = "Expect";
+  static final EXPIRES = "Expires";
+  static final FROM = "From";
+  static final HOST = "Host";
+  static final IF_MATCH = "If-Match";
+  static final IF_MODIFIED_SINCE = "If-Modified-Since";
+  static final IF_NONE_MATCH = "If-None-Match";
+  static final IF_RANGE = "If-Range";
+  static final IF_UNMODIFIED_SINCE = "If-Unmodified-Since";
+  static final LAST_MODIFIED = "Last-Modified";
+  static final LOCATION = "Location";
+  static final MAX_FORWARDS = "Max-Forwards";
+  static final PRAGMA = "Pragma";
+  static final PROXY_AUTHENTICATE = "Proxy-Authenticate";
+  static final PROXY_AUTHORIZATION = "Proxy-Authorization";
+  static final RANGE = "Range";
+  static final REFERER = "Referer";
+  static final RETRY_AFTER = "Retry-After";
+  static final SERVER = "Server";
+  static final TE = "TE";
+  static final TRAILER = "Trailer";
+  static final TRANSFER_ENCODING = "Transfer-Encoding";
+  static final UPGRADE = "Upgrade";
+  static final USER_AGENT = "User-Agent";
+  static final VARY = "Vary";
+  static final VIA = "Via";
+  static final WARNING = "Warning";
+  static final WWW_AUTHENTICATE = "WWW-Authenticate";
+
+  static final GENERAL_HEADERS = const [CACHE_CONTROL,
+                                        CONNECTION,
+                                        DATE,
+                                        PRAGMA,
+                                        TRAILER,
+                                        TRANSFER_ENCODING,
+                                        UPGRADE,
+                                        VIA,
+                                        WARNING];
+
+  static final ENTITY_HEADERS = const [ALLOW,
+                                       CONTENT-ENCODING,
+                                       CONTENT-LANGUAGE,
+                                       CONTENT-LENGTH,
+                                       CONTENT-LOCATION,
+                                       CONTENT-MD5,
+                                       CONTENT-RANGE,
+                                       CONTENT-TYPE,
+                                       EXPIRES,
+                                       LAST-MODIFIED];
+
+
+  static final RESPONSE_HEADERS = const [ACCEPT-RANGES,
+                                         AGE,
+                                         ETAG,
+                                         LOCATION,
+                                         PROXY-AUTHENTICATE,
+                                         RETRY-AFTER,
+                                         SERVER,
+                                         VARY,
+                                         WWW-AUTHENTICATE];
+
+  static final REQUEST_HEADERS = const [ACCEPT,
+                                        ACCEPT-CHARSET,
+                                        ACCEPT-ENCODING,
+                                        ACCEPT-LANGUAGE,
+                                        AUTHORIZATION,
+                                        EXPECT,
+                                        FROM,
+                                        HOST,
+                                        IF-MATCH,
+                                        IF-MODIFIED-SINCE,
+                                        IF-NONE-MATCH,
+                                        IF-RANGE,
+                                        IF-UNMODIFIED-SINCE,
+                                        MAX-FORWARDS,
+                                        PROXY-AUTHORIZATION,
+                                        RANGE,
+                                        REFERER,
+                                        TE,
+                                        USER-AGENT];
+
+  /**
+   * Returns the list of values for the header named [name]. If there
+   * is no headers with the provided name null will be returned.
+   */
+  List<String> operator[](String name);

[Anders Johnsen, 2012/04/13 11:47:53]

Now we have no trivial way of getting the only header available (the most common
case). I'm not saying it's bad, since the user should consider all cases. I'm
just not convinced it's ideal. What do you think?

[Søren Gjesse, 2012/04/16 11:37:16]

I agree, in the tests I had to use [0] in quite a few places which was annoying.
However I have no good suggestion other than adding an additional method to
return a string.

[Anders Johnsen, 2012/04/16 11:50:46]

I think we should just do that, and throw an exception if we have multiple
values.

[Søren Gjesse, 2012/04/16 12:17:31]

Added method value for now.

+
+  /**
+   * Adds a header value. The header named [name] will have the value
+   * [value] added to its list of values. Some headers are single
+   * values and for these adding a value will replace the previous
+   * value. If the value is of type Date a HTTP date format will be
+   * applied to all other types the default toString method will be
+   * used.
+   */
+  void add(String name, value);

[Anders Johnsen, 2012/04/13 11:47:53]

Would it be better to say either var or Object? Having no type is kind of
catching the eye, giving everything else is types.

[Søren Gjesse, 2012/04/16 11:37:16]

Added type Object

+
+  /**
+   * Sets a header. The header named [name] will have the value
+   * [value] set as its only value. All previous values in its list
+   * will be removed. Some headers have system supplied values and for
+   * these the system supplied values will still be added to the
+   * collection of values for the header. If the value is of type Date
+   * a HTTP date format will be applied to all other types the default
+   * toString method will be used.
+   */
+  void set(String name, value);

[Anders Johnsen, 2012/04/13 11:47:53]

Can value be a List?

[Søren Gjesse, 2012/04/16 11:37:16]

That should be fine. It should then add each element. That has been added. Same
for add where adding a List will add as separate elements.

[Anders Johnsen, 2012/04/16 11:50:46]

Ty!

+
+  /**
+   * Removes a specific value for a header name. Some headers have
+   * system supplied values and for these the system supplied values
+   * will still be added to the collection of values for the header.
+   */
+  void remove(String name, value);
+
+  /**
+   * Remove all values for the specified header name. Some headers
+   * have system supplied values and for these the system supplied
+   * values will still be added to the collection of values for the
+   * header.
+   */
+  void removeAll(String name);
+}
+
+
+/**
  * Http request delivered to the HTTP server callback.
  */
 interface HttpRequest default _HttpRequest {
   /**
    * Returns the content length of the request body. If the size of
    * the request body is not known in advance this -1.
    */
   int get contentLength();
 
   /**
@@ skipping 17 matching lines @@
   String get queryString();
 
   /**
    * Returns the parsed query string.
    */
   Map<String, String> get queryParameters();
 
   /**
    * Returns the request headers.
    */
-  Map<String, String> get headers();
+  HttpHeaders get headers();
 
   /**
    * Returns the input stream for the request. This is used to read
    * the request data.
    */
   InputStream get inputStream();
 }
 
 
 /**
@@ skipping 20 matching lines @@
    */
   String reasonPhrase;
 
   /**
    * Gets and sets the expiry date. The value of this property will
    * reflect the "Expires" header
    */
   Date expires;
 
   /**
-   * Sets a header on the response. NOTE: If the same header name is
-   * set more than once only the last value will be part of the
-   * response.
-   */
-  void setHeader(String name, String value);
-
-  /**
    * Returns the response headers.
    */
-  Map<String, String> get headers();
+  HttpHeaders get headers();
 
   /**
    * Returns the output stream for the response. This is used to write
    * the response data. When all response data has been written close
    * the stream to indicate the end of the response.
    *
    * When this is accessed for the first time the response header is
    * send. Calling any methods that will change the header after
    * having retrieved the output stream will throw an exception.
    */
@@ skipping 109 matching lines @@
   String host;
 
   /**
    * Gets and sets the port part of the "Host" header for the
    * connection. By default this will be set to the value of the port
    * used when initiating the connection.
    */
   int port;
 
   /**
-   * Sets a header on the request. NOTE: If the same header name is
-   * set more than once only the last value set will be part of the
-   * request.
-   */
-  void setHeader(String name, String value);
-
-  /**
    * Returns the request headers.
    */
-  Map<String, String> get headers();
+  HttpHeaders get headers();
 
   /**
    * Returns the output stream for the request. This is used to write
    * the request data. When all request data has been written close
    * the stream to indicate the end of the request.
    *
    * When this is accessed for the first time the request header is
    * send. Calling any methods that will change the header after
    * having retrieved the output stream will throw an exception.
    */
@@ skipping 25 matching lines @@
    * Returns the date value for the "Expires" header. Returns null if
    * the response has no "Expires" header. Throws a HttpException if
    * the response has an "Expires" header which is not formatted as a
    * valid HTTP date.
    */
   Date get expires();
 
   /**
    * Returns the response headers.
    */
-  Map<String, String> get headers();
+  HttpHeaders get headers();
 
   /**
    * Returns the input stream for the response. This is used to read
    * the response data.
    */
   InputStream get inputStream();
 }
 
 
 class HttpException implements Exception {
   const HttpException([String this.message = ""]);
   String toString() => "HttpException: $message";
   final String message;
 }