1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
|
/**
* @workInProgress
* @ngdoc service
* @name angular.service.$xhr
* @function
* @requires $browser $xhr delegates all XHR requests to the `$browser.xhr()`. A mock version
* of the $browser exists which allows setting expectaitions on XHR requests
* in your tests
* @requires $xhr.error $xhr delegates all non `2xx` response code to this service.
* @requires $log $xhr delegates all exceptions to `$log.error()`.
* @requires $updateView After a server response the view needs to be updated for data-binding to
* take effect.
*
* @description
* Generates an XHR request. The $xhr service delegates all requests to
* {@link angular.service.$browser $browser.xhr()} and adds error handling and security features.
* While $xhr service provides nicer api than raw XmlHttpRequest, it is still considered a lower
* level api in angular. For a higher level abstraction that utilizes `$xhr`, please check out the
* {@link angular.service$resource $resource} service.
*
* # Error handling
* All XHR responses with response codes other then `2xx` are delegated to
* {@link angular.service.$xhr.error $xhr.error}. The `$xhr.error` can intercept the request
* and process it in application specific way, or resume normal execution by calling the
* request callback method.
*
* # Security Considerations
* When designing web applications your design needs to consider security threats from
* {@link http://haacked.com/archive/2008/11/20/anatomy-of-a-subtle-json-vulnerability.aspx
* JSON Vulnerability} and {@link http://en.wikipedia.org/wiki/Cross-site_request_forgery XSRF}.
* Both server and the client must cooperate in order to eliminate these threats. Angular comes
* pre-configured with strategies that address these issues, but for this to work backend server
* cooperation is required.
*
* ## JSON Vulnerability Protection
* A {@link http://haacked.com/archive/2008/11/20/anatomy-of-a-subtle-json-vulnerability.aspx
* JSON Vulnerability} allows third party web-site to turn your JSON resource URL into
* {@link http://en.wikipedia.org/wiki/JSON#JSONP JSONP} request under some conditions. To
* counter this your server can prefix all JSON requests with following string `")]}',\n"`.
* Angular will automatically strip the prefix before processing it as JSON.
*
* For example if your server needs to return:
* <pre>
* ['one','two']
* </pre>
*
* which is vulnerable to attack, your server can return:
* <pre>
* )]}',
* ['one','two']
* </pre>
*
* angular will strip the prefix, before processing the JSON.
*
*
* ## Cross Site Request Forgery (XSRF) Protection
* {@link http://en.wikipedia.org/wiki/Cross-site_request_forgery XSRF} is a technique by which an
* unauthorized site can gain your user's private data. Angular provides following mechanism to
* counter XSRF. When performing XHR requests, the $xhr service reads a token from a cookie
* called `XSRF-TOKEN` and sets it as the HTTP header `X-XSRF-TOKEN`. Since only JavaScript that
* runs on your domain could read the cookie, your server can be assured that the XHR came from
* JavaScript running on your domain.
*
* To take advantage of this, your server needs to set a token in a JavaScript readable session
* cookie called `XSRF-TOKEN` on first HTTP GET request. On subsequent non-GET requests the server
* can verify that the cookie matches `X-XSRF-TOKEN` HTTP header, and therefore be sure that only
* JavaScript running on your domain could have read the token. The token must be unique for each
* user and must be verifiable by the server (to prevent the JavaScript making up its own tokens).
* We recommend that the token is a digest of your site's authentication cookie with
* {@link http://en.wikipedia.org/wiki/Rainbow_table salt for added security}.
*
* @param {string} method HTTP method to use. Valid values are: `GET`, `POST`, `PUT`, `DELETE`, and
* `JSON`. `JSON` is a special case which causes a
* [JSONP](http://en.wikipedia.org/wiki/JSON#JSONP) cross domain request using script tag
* insertion.
* @param {string} url Relative or absolute URL specifying the destination of the request. For
* `JSON` requests, `url` should include `JSON_CALLBACK` string to be replaced with a name of an
* angular generated callback function.
* @param {(string|Object)=} post Request content as either a string or an object to be stringified
* as JSON before sent to the server.
* @param {function(number, (string|Object))} callback A function to be called when the response is
* received. The callback will be called with:
*
* - {number} code [HTTP status code](http://en.wikipedia.org/wiki/List_of_HTTP_status_codes) of
* the response. This will currently always be 200, since all non-200 responses are routed to
* {@link angular.service.$xhr.error} service.
* - {string|Object} response Response object as string or an Object if the response was in JSON
* format.
*
* @example
<doc:example>
<doc:source>
<script>
function FetchCntl($xhr) {
var self = this;
this.fetch = function() {
self.clear();
$xhr(self.method, self.url, function(code, response) {
self.code = code;
self.response = response;
});
};
this.clear = function() {
self.code = null;
self.response = null;
};
}
FetchCntl.$inject = ['$xhr'];
</script>
<div ng:controller="FetchCntl">
<select name="method">
<option>GET</option>
<option>JSON</option>
</select>
<input type="text" name="url" value="index.html" size="80"/><br/>
<button ng:click="fetch()">fetch</button>
<button ng:click="clear()">clear</button>
<a href="" ng:click="method='GET'; url='index.html'">sample</a>
<a href="" ng:click="method='JSON'; url='https://www.googleapis.com/buzz/v1/activities/googlebuzz/@self?alt=json&callback=JSON_CALLBACK'">buzz</a>
<pre>code={{code}}</pre>
<pre>response={{response}}</pre>
</div>
</doc:source>
</doc:example>
*/
angularServiceInject('$xhr', function($browser, $error, $log, $updateView){
return function(method, url, post, callback){
if (isFunction(post)) {
callback = post;
post = _null;
}
if (post && isObject(post)) {
post = toJson(post);
}
$browser.xhr(method, url, post, function(code, response){
try {
if (isString(response)) {
if (response.match(/^\)\]\}',\n/)) response=response.substr(6);
if (/^\s*[\[\{]/.exec(response) && /[\}\]]\s*$/.exec(response)) {
response = fromJson(response, true);
}
}
if (200 <= code && code < 300) {
callback(code, response);
} else {
$error(
{method: method, url:url, data:post, callback:callback},
{status: code, body:response});
}
} catch (e) {
$log.error(e);
} finally {
$updateView();
}
}, {
'X-XSRF-TOKEN': $browser.cookies()['XSRF-TOKEN']
});
};
}, ['$browser', '$xhr.error', '$log', '$updateView']);
|
