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 {
+  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);
+
+  /**
+   * Convenience method for the value for a single values header. If
+   * there is no header with the provided name null will be
+   * returned. If the header has more than one value an exception is
+   * thrown.
+   */
+  String value(String name);
+
+  /**
+   * 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. If the value is a [:List:] each element of the list will
+   * be added separately. For all other types the default [:toString:]
+   * method will be used.
+   */
+  void add(String name, Object value);
+
+  /**
+   * Sets a header. The header named [name] will have all its values
+   * cleared before the value [value] is added as its value.
+   */
+  void set(String name, Object value);
+
+  /**
+   * 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, Object 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;
 }