From a9e2f15f21f7bb42286c59d5635fa71047077af7 Mon Sep 17 00:00:00 2001
From: Pawel Kozlowski <pkozlowski.opensource@gmail.com>
Date: Fri, 3 Apr 2015 12:27:27 +0200
Subject: [PATCH] docs($http): clarify side effects of transformRequest
 functions

Closes #11438
---
 CHANGELOG.md        | 28 ++++++++++++++++++++++++++++
 test/ng/httpSpec.js | 17 +++++++++++++++++
 2 files changed, 45 insertions(+)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 898ef13e925d..18891fa8bed7 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -249,6 +249,34 @@ end of the container containing the ngMessages directive).
 </div>
 ```
 
+- **$http:** due to [5da1256](https://github.com/angular/angular.js/commit/5da1256fc2812d5b28fb0af0de81256054856369),
+
+`transformRequest` functions can no longer modify request headers.
+
+Before this commit `transformRequest` could modify request headers, ex.:
+
+```javascript
+function requestTransform(data, headers) {
+    headers = angular.extend(headers(), {
+      'X-MY_HEADER': 'abcd'
+    });
+  }
+  return angular.toJson(data);
+}
+```
+
+This behavior was unintended and undocumented, so the change should affect very few applications. If one
+needs to dynamically add / remove headers it should be done in a header function, for example:
+
+```javascript
+$http.get(url, {
+  headers: {
+    'X-MY_HEADER': function(config) {
+      return 'abcd'; //you've got access to a request config object to specify header value dynamically
+    }
+  }
+})
+```
 
 <a name="1.3.14"></a>
 # 1.3.14 instantaneous-browserification (2015-02-24)
diff --git a/test/ng/httpSpec.js b/test/ng/httpSpec.js
index a73f2ae75e5f..79078321c3b6 100644
--- a/test/ng/httpSpec.js
+++ b/test/ng/httpSpec.js
@@ -1128,6 +1128,23 @@ describe('$http', function() {
           expect(callback).toHaveBeenCalledOnce();
         });
 
+        it('should not allow modifications to headers in a transform functions', function() {
+          var config = {
+            headers: {'Accept': 'bar'},
+            transformRequest: function(data, headers) {
+              angular.extend(headers(), {
+                'Accept': 'foo'
+              });
+            }
+          };
+
+          $httpBackend.expect('GET', '/url', undefined, {Accept: 'bar'}).respond(200);
+          $http.get('/url', config).success(callback);
+          $httpBackend.flush();
+
+          expect(callback).toHaveBeenCalledOnce();
+        });
+
         it('should pipeline more functions', function() {
           function first(d, h) {return d + '-first' + ':' + h('h1');}
           function second(d) {return uppercase(d);}