CORS support in 3.3

Updates since the original post/feature implementation

After receiving a number of requests during a relatively short amount of time, I decided to add support for Cross Origin Resource Sharing (CORS). This allows you to send requests to domain A and return the response from some other domain. You will need to enable this new feature if the domain of the server returning responses to Fine Uploader does not match the domain of the origin server. If you don’t know what this means, please do not enable CORS support. Support exists for both upload requests and delete file requests.

Support exceptions

  • CORS requests in IE7 are not supported. In IE8 and IE9, the response from the request iframe is passed to the uploader window via window.postMessage, which is not supported in IE7.
  • Delete file CORS requests in IE9 and earlier are not supported. This is due to the fact that DELETE requests must be preflighted. IE9 and earlier require XDomainRequest to be used when sending CORS requests, and XDomainRequest does not support preflighting. The delete files feature will be automatically disabled in IE9 and earlier if Fine Uploader CORS support is enabled.
var uploader = new qq.FineUploader({
    element: document.getElementById('myUploader'),
    request: {
        endpoint: 'server/upload'
    }
    cors: {
        //all requests are expected to be cross-domain requests
        expected: true,

        //if you want cookies to be sent along with the request
        sendCredentials: true
    }
});

Enabling CORS support

If you set the expected property to true, it is assumed that all requests will be cross-domain requests. If you set expected to true and do not respond using the cross-domain response convention outlined below for non-XHR requests, even if the request is NOT cross-domain, it will be considered a failure.

Handling XHR CORS requests server-side

An incoming upload request was sent via XMLHttpRequest if the request has an X-Requested-With header with a value of “XMLHttpRequest”. If CORS support is enabled in Fine Uploader, you must properly handle the associated requests and format your responses accordingly. Note that, since non-standards headers are sent with all Fine Uploader requests, ALL XHR requests are preflighted. This applies to both delete file requests (which are all XHR requests) and upload requests on browsers that support the File API. This means that you will need to handle an OPTIONS request as well. Your responses must include the appropriate Access-Control headers. If you set the sendCredentials property to true, you should be aware that your responses must NOT include wildcard Access-Control-Allow-Origin headers, and you must also include the Access-Control-Allow-Credentials header. The actual response text for CORS XHR requests will not differ at all from response text for non-CORS requests.

Handling iframe CORS upload requests server-side

An incoming upload request was sent via a form submission inside of a hidden iframe if the request does not have an X-Requested-With header, or if the X-Requested-With header has a value other than “XMLHttpRequest”. Handling cross-domain iframe/form-submit-initiated uploads (in browsers that do not support the File API) is a bit tricky for Fine Uploader. I’ve done my best to make it as simple as possible for developers/integrators, though. Your response for iframe based request (such as required when using IE8 or IE9), will look very similar to your normal response, except it must have a Content-Type header value of “text/html”, and your response must import a helper javascript file via a &ltscript&gt tag immediately preceding your valid JSON response. For example:

"{\"success\": true, \"uuid\": \"9da17ad5-ad6a-40cd-81b5-226e837db45b\"}<script src=\"http://<YOUR_SERVER_DOMAIN>/iframe.xss.response-<VERSION>.js/"></script>"

All cross-domain iframe-initiated responses must end with the script tag above, and the valid JSON portion MUST include the UUID of the associated file. Note that you must host the iframe.xss.response.js file on an accessible server and reference it in the &ltscript&gt tag accordingly. When the contents of your response is returned to the iframe tracked by Fine Uploader, the associated javascript file imported by the script tag above will be executed, and will pass the JSON portion of your response to the uploader via window.postMessage.

Additional reading on CORS

If you are unfamiliar with handling XHR CORS requests, Mozilla Developer Network has an excellent wiki article on CORS. Please pay attention, in particular, to the sections that describe how to handle preflighted requests, and credentialed requests (if you require credentials to be passed with the cross-domain request and you have set the sendCredentials cors property).

This is my first stab at CORS support in Fine Uploader. So, please let me know if anything can be improved.

-Ray Nicholus

Leave a Comment

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s