Clarify that some headers may not be sent/received (#1768)

Author: brianquinlan

pkgs/http/CHANGELOG.md

@@ -1,3 +1,7 @@
+## 1.4.1
+
+* Clarify that some header names may not be sent/received.
+
 ## 1.4.0
 
 * Fixed default encoding for application/json without a charset

pkgs/http/lib/src/base_request.dart

@@ -81,7 +81,13 @@ abstract class BaseRequest {
 
   // TODO(nweiz): automatically parse cookies from headers
 
-  // TODO(nweiz): make this a HttpHeaders object
+  /// The HTTP headers sent to the server.
+  ///
+  /// Header names are converted to lowercase when sent to the server.
+  ///
+  /// Some headers may not be sent by the [Client] for security or privacy
+  /// reasons. For example, browser-based clients may only sent headers in the
+  /// CORS safelist or specifically allowed by the server.
   final Map<String, String> headers;
 
   /// Whether [finalize] has been called.

pkgs/http/lib/src/base_response.dart

@@ -52,6 +52,10 @@ abstract class BaseResponse {
   /// If a header value contains whitespace then that whitespace may be replaced
   /// by a single space. Leading and trailing whitespace in header values are
   /// always removed.
+  ///
+  /// Some headers may be excluded by the [Client] for security or privacy
+  /// reasons. For example, browser-based clients can only return headers in the
+  /// CORS safelist or specifically allowed by the server.
   final Map<String, String> headers;
 
   final bool isRedirect;

pkgs/http/pubspec.yaml

@@ -1,5 +1,5 @@
 name: http
-version: 1.4.0
+version: 1.4.1-wip
 description: A composable, multi-platform, Future-based API for HTTP requests.
 repository: https://github.com/dart-lang/http/tree/master/pkgs/http