A pure JavaScript CORS alternative. No server configuration required -
just add a proxy.html on the domain you wish to communicate with. This
library utilizes XHook to hook all XHR, so XDomain should work in
conjunction with any library.
- Simple
- Library Agnostic
- Tested with jQuery
$.ajax(and subsequently$.get,$.post) - Tested with Angular
$httpservice
- Tested with jQuery
- Cross domain XHR just magically works
- No need to modify the server code
- No need to use IE's silly XDomainRequest Object
- Easy XHR access to file servers:
- Amazon
- Dropbox
- Includes XHook
- White-list allowed domains
- White-list paths using regular expressions (e.g. only allow API calls:
/^\/api/)
-
Development xdomain.js 16KB
-
Production xdomain.min.js 7.5KB (1.8KB Gzip)
Note: It's important to include XDomain first as other libraries may store a reference to
XMLHttpRequestbefore XHook can patch it
All except IE6/7 as they don't have postMessage
-
On your slave domain (
http://xyz.example.com), create a smallproxy.htmlfile:<!DOCTYPE HTML> <script src="http://jpillora.com/xdomain/dist/0.5/xdomain.min.js" master="http://abc.example.com"></script>
-
Then, on your master domain (
http://abc.example.com), point to your newproxy.html:<script src="http://jpillora.com/xdomain/dist/0.5/xdomain.min.js" slave="http://xyz.example.com/proxy.html"></script>
-
And that's it! Now, on your master domain, any XHR to
http://xyz.example.comwill automagically work://do some vanilla XHR var xhr = new XMLHttpRequest(); xhr.open('GET', 'http://xyz.example.com/secret/file.txt'); xhr.onreadystatechange = function(e) { if(xhr.readyState === 4) alert(xhr.responseText); }; xhr.send(); //or if we are using jQuery... $.get('http://xyz.example.com/secret/file.txt').done(function(data) { console.log("got result: ", data); });
Tip: If you enjoy being standards compliant, you can also use data-master and data-slave attributes.
The following two snippets are equivalent:
<script src="http://jpillora.com/xdomain/dist/0.5/xdomain.min.js" master="http://abc.example.com"></script><script src="http://jpillora.com/xdomain/dist/0.5/xdomain.min.js"></script>
<script>
xdomain({
masters: {
'http://abc.example.com': /.*/
}
});
</script>So, we can then add more masters or (slaves) by simply including them
in the object, see API below.
If object contains:
-
Then
xdomainwill load as a masterEach slave must be defined as:
origin->proxy fileAn object is used to list slaves to reinforce the idea that we need one proxy file per origin.
-
Then
xdomainwill load as a slaveEach master must be defined as:
origin->allowed path(RegExp)originwill also be converted to a regular expression by escaping all non alphanumeric chars, converting*into.+and wrapping with^and$.Requests that do not match both the
originand thepathregular expressions will be blocked.So you could use the following
proxy.htmlto allow all subdomains ofexample.com:<script src="/dist/0.5/xdomain.min.js" data-master="http://*.example.com"></script>
Which is equivalent to:
<script src="/dist/0.5/xdomain.min.js"></script> <script> xdomain({ masters: { "http://*.example.com": /.*/ } }); </script>
Therefore, you could allow ALL domains with the following
proxy.html:<script src="/dist/0.5/xdomain.min.js" master="*"></script>
Though this is NOT recommended.
- XDomain will create an iframe on the master to the slave's proxy.
- Master will communicate to slave iframe using postMessage.
- Slave will create XHRs on behalf of master then return the results.
XHR interception is done seemlessly via XHook.
Use the HTML5 document type <!DOCTYPE HTML> to prevent your page
from going into quirks mode. If you don't do this, XDomain will warn you about
the missing JSON and/or postMessage globals and will exit.
Q: But I love CORS
A: You shouldn't:
-
IE uses a different API (XDomainRequest) for CORS, XDomain normalizes this silliness.
-
On RESTful JSON API server, CORS will send a preflight OPTIONS request on all requests except for GET and HEAD, generating superfluous traffic.
-
Not everyone can change the HTTP headers on the server, but most people can drop in a
proxy.htmlfile. -
Google also uses iframes as postMessage proxies instead of CORS in it's Google API JS SDK:
<iframe name="oauth2relay564752183" id="oauth2relay564752183" src="https://accounts.google.com/o/oauth2/postmessageRelay?..."> </iframe>
npm install -g grunt-source serve
git clone https://github.com/jpillora/xdomain
cd xdomain
grunt-source
Will start watching src for changes and will then compile and minify into dist
cd xdomain
serve
Visit http://localhost:3000
Issues and Pull-requests welcome.
v0.5.0 - Upgraded to XHook v1.
v0.4.0 - Now setting request body, duh.
v0.3.0 - Moved to vanilla, using XHook to hook XHR instead of $.ajax
v0.2.0 - Removed PortHole, using pure postMessage, IE6/7 NOT supported
v0.1.0 - Alpha
Copyright © 2013 Jaime Pillora <[email protected]>
Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the 'Software'), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED 'AS IS', WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.