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
will work seamlessly with any library.
Features
Simple
Library Agnostic
With jQuery$.ajax (and subsequently $.get, $.post)
Note: It'simportantto include XDomain before any other library. When XDomain loads, XHook replaces the current window.XMLHttpRequest. So if another library saves a reference to the original window.XMLHttpRequest and uses that, XHook won't be able to intercept those requests.
On your slave domain (http://xyz.example.com), create a small proxy.html file:
And that's it! Now, on your master domain, any XHR to http://xyz.example.com will automagically work:
//do some vanilla XHRvarxhr=newXMLHttpRequest();xhr.open("GET","http://xyz.example.com/secret/file.txt");xhr.onreadystatechange=function(e){if(xhr.readyState===4)console.log("got result: ",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.
Each of the masters must be defined as: origin: path
origin and path are converted to a regular expression by escaping all non-alphanumeric chars, then converting * into .* and finally wrapping it with ^ and $. path can also be a RegExp literal.
Requests that do not match both the origin and the path regular
expressions will be blocked.
So you could use the following proxy.html to allow all subdomains of example.com:
Where "/api/*.json" becomes the RegExp /^\/api\/.*\.json$/
Therefore, you could allow ALL domains with the following proxy.html:
<!-- BEWARE: VERY INSECURE --><scriptsrc="/dist/xdomain.min.js" master="*"></script>
xdomain.debug = false
When true, XDomain will log actions to console
xdomain.timeout = 15e3ms (15 seconds)
Number of milliseconds until XDomains gives up waiting for an iframe to respond
xdomain.on(event, handler)
event may be log, warn or timeout. When listening for log and warn events, handler with contain the message as the first parameter. The timeout event fires when an iframe exeeds the xdomain.timeout time limit.
xdomain.cookies
WARNING⚠️ Chrome and possibly other browsers appear to be blocking access to the iframe's document.cookie property. This means Slave-Cookies are no longer supported in some browsers.
When withCredentials is set to true for a given request, the cookies of the master and slave are sent to the server using these names. If one is set to null, it will not be sent.
Note, if you use "Cookie" as your cookie name, it will be removed by browsers with Disable 3rd Party Cookies switched on - this includes all Safari users and many others who purposefully enable it.
Conceptual Overview
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.
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.
If you need a CORS Polyfill and you're here because of IE, give this XHook CORS polyfill a try, however, be mindful of the restrictions listed below.
FAQ / Troubleshooting
Q: But I love CORS
A: You shouldn't. You should use XDomain because:
IE uses a different API (XDomainRequest) for CORS, XDomain normalizes this silliness. XDomainRequest also has many restrictions:
Requests must be GET or POST
Requests must use the same protocol as the page http -> http
Requests only emit progress,timeout and error
Requests may only use the Content-Type header
The CORS spec is not as simple as it seems, XDomain allows you to use plain XHR instead.
On a RESTful JSON API server, CORS will generate superfluous traffic by sending a
preflight OPTIONS request preceding various types of requests.
Not everyone is able to modify HTTP headers on the server, but most can upload a proxy.html file.
Google also uses iframes as postMessage proxies instead of CORS in its Google API JS SDK:
A: XDomain attempts to perfectly implement XMLHttpRequest2
so there should be no differences. If there is a difference, create an issue. Note however, one purposeful
difference affects some libraries under IE. Many use the presence of 'withCredentials' in new XMLHttpRequest()
to determine if the browser supports CORS.
The most notable library that does this is jQuery, so XHook purposefully defines withCredentials to trick jQuery into thinking the browser supports
CORS, thereby allowing XDomain to function seamlessly in IE. However, this fix is detrimental to
other libraries like: MixPanel, FB SDK, Intercom as they will incorrectly attempt CORS on domains
which don't have a proxy.html. So, if you are using any of these libraries which implement their own CORS workarounds, you can do the
following to manually disable defining withCredentials and manually reenable CORS on jQuery:
Note: In newer browsers xhook.addWithCredentials has no effect as they already support withCredentials.
Q: XDomain works for a few requests and then it stops.
A: Most likely, the slave iframe was removed - this is often due to libraries like Turbolinks
Q: In IE, I'm getting an Access Denied error
A: This is error occurs when IE attempts a CORS request. Read on.
Q: The browser is still sending CORS requests.
A: Double check your slaves configuration against the examples.
If your slaves configuration is correct, double-check that you're
including XDomain beforewindow.XMLHttpRequest is referenced anywhere.
The safest way to fix it is to include XDomain first, it has no dependencies,
it only modifies window.XMLHttpRequest.
Q: The script is loads but the 'Quick Start' steps don't work
A: XDomain only searches the script tags for master and slave attributes if they have xdomain in the src. So, if you've renamed or embedded XDomain, you'll need to use the API in order to insert your masters and slaves.
Q: It's still not working!
A: Enable xdomain.debug = true; (or add a debug="true" attribute to the script tag) on both the master and the slave
and copy the console.logs to a new issue. If possible, please provide a live example demonstrating your issue.
Change log
0.8.2
Removed CoffeeScript
Restructured with ES6 and Common.js
Use parcel as bundler
Todo
Saucelabs testing is broken, need to swap to BrowserStack.
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.
客服电话
APP下载
官方微信
请发表评论