/**
|
* XmlHttpRequest implementation that uses TLS and flash SocketPool.
|
*
|
* @author Dave Longley
|
*
|
* Copyright (c) 2010-2013 Digital Bazaar, Inc.
|
*/
|
var forge = require('./forge');
|
require('./socket');
|
require('./http');
|
|
/* XHR API */
|
var xhrApi = module.exports = forge.xhr = forge.xhr || {};
|
|
(function($) {
|
|
// logging category
|
var cat = 'forge.xhr';
|
|
/*
|
XMLHttpRequest interface definition from:
|
http://www.w3.org/TR/XMLHttpRequest
|
|
interface XMLHttpRequest {
|
// event handler
|
attribute EventListener onreadystatechange;
|
|
// state
|
const unsigned short UNSENT = 0;
|
const unsigned short OPENED = 1;
|
const unsigned short HEADERS_RECEIVED = 2;
|
const unsigned short LOADING = 3;
|
const unsigned short DONE = 4;
|
readonly attribute unsigned short readyState;
|
|
// request
|
void open(in DOMString method, in DOMString url);
|
void open(in DOMString method, in DOMString url, in boolean async);
|
void open(in DOMString method, in DOMString url,
|
in boolean async, in DOMString user);
|
void open(in DOMString method, in DOMString url,
|
in boolean async, in DOMString user, in DOMString password);
|
void setRequestHeader(in DOMString header, in DOMString value);
|
void send();
|
void send(in DOMString data);
|
void send(in Document data);
|
void abort();
|
|
// response
|
DOMString getAllResponseHeaders();
|
DOMString getResponseHeader(in DOMString header);
|
readonly attribute DOMString responseText;
|
readonly attribute Document responseXML;
|
readonly attribute unsigned short status;
|
readonly attribute DOMString statusText;
|
};
|
*/
|
|
// readyStates
|
var UNSENT = 0;
|
var OPENED = 1;
|
var HEADERS_RECEIVED = 2;
|
var LOADING = 3;
|
var DONE = 4;
|
|
// exceptions
|
var INVALID_STATE_ERR = 11;
|
var SYNTAX_ERR = 12;
|
var SECURITY_ERR = 18;
|
var NETWORK_ERR = 19;
|
var ABORT_ERR = 20;
|
|
// private flash socket pool vars
|
var _sp = null;
|
var _policyPort = 0;
|
var _policyUrl = null;
|
|
// default client (used if no special URL provided when creating an XHR)
|
var _client = null;
|
|
// all clients including the default, key'd by full base url
|
// (multiple cross-domain http clients are permitted so there may be more
|
// than one client in this map)
|
// TODO: provide optional clean up API for non-default clients
|
var _clients = {};
|
|
// the default maximum number of concurrents connections per client
|
var _maxConnections = 10;
|
|
var net = forge.net;
|
var http = forge.http;
|
|
/**
|
* Initializes flash XHR support.
|
*
|
* @param options:
|
* url: the default base URL to connect to if xhr URLs are relative,
|
* ie: https://myserver.com.
|
* flashId: the dom ID of the flash SocketPool.
|
* policyPort: the port that provides the server's flash policy, 0 to use
|
* the flash default.
|
* policyUrl: the policy file URL to use instead of a policy port.
|
* msie: true if browser is internet explorer, false if not.
|
* connections: the maximum number of concurrent connections.
|
* caCerts: a list of PEM-formatted certificates to trust.
|
* cipherSuites: an optional array of cipher suites to use,
|
* see forge.tls.CipherSuites.
|
* verify: optional TLS certificate verify callback to use (see forge.tls
|
* for details).
|
* getCertificate: an optional callback used to get a client-side
|
* certificate (see forge.tls for details).
|
* getPrivateKey: an optional callback used to get a client-side private
|
* key (see forge.tls for details).
|
* getSignature: an optional callback used to get a client-side signature
|
* (see forge.tls for details).
|
* persistCookies: true to use persistent cookies via flash local storage,
|
* false to only keep cookies in javascript.
|
* primeTlsSockets: true to immediately connect TLS sockets on their
|
* creation so that they will cache TLS sessions for reuse.
|
*/
|
xhrApi.init = function(options) {
|
forge.log.debug(cat, 'initializing', options);
|
|
// update default policy port and max connections
|
_policyPort = options.policyPort || _policyPort;
|
_policyUrl = options.policyUrl || _policyUrl;
|
_maxConnections = options.connections || _maxConnections;
|
|
// create the flash socket pool
|
_sp = net.createSocketPool({
|
flashId: options.flashId,
|
policyPort: _policyPort,
|
policyUrl: _policyUrl,
|
msie: options.msie || false
|
});
|
|
// create default http client
|
_client = http.createClient({
|
url: options.url || (
|
window.location.protocol + '//' + window.location.host),
|
socketPool: _sp,
|
policyPort: _policyPort,
|
policyUrl: _policyUrl,
|
connections: options.connections || _maxConnections,
|
caCerts: options.caCerts,
|
cipherSuites: options.cipherSuites,
|
persistCookies: options.persistCookies || true,
|
primeTlsSockets: options.primeTlsSockets || false,
|
verify: options.verify,
|
getCertificate: options.getCertificate,
|
getPrivateKey: options.getPrivateKey,
|
getSignature: options.getSignature
|
});
|
_clients[_client.url.full] = _client;
|
|
forge.log.debug(cat, 'ready');
|
};
|
|
/**
|
* Called to clean up the clients and socket pool.
|
*/
|
xhrApi.cleanup = function() {
|
// destroy all clients
|
for(var key in _clients) {
|
_clients[key].destroy();
|
}
|
_clients = {};
|
_client = null;
|
|
// destroy socket pool
|
_sp.destroy();
|
_sp = null;
|
};
|
|
/**
|
* Sets a cookie.
|
*
|
* @param cookie the cookie with parameters:
|
* name: the name of the cookie.
|
* value: the value of the cookie.
|
* comment: an optional comment string.
|
* maxAge: the age of the cookie in seconds relative to created time.
|
* secure: true if the cookie must be sent over a secure protocol.
|
* httpOnly: true to restrict access to the cookie from javascript
|
* (inaffective since the cookies are stored in javascript).
|
* path: the path for the cookie.
|
* domain: optional domain the cookie belongs to (must start with dot).
|
* version: optional version of the cookie.
|
* created: creation time, in UTC seconds, of the cookie.
|
*/
|
xhrApi.setCookie = function(cookie) {
|
// default cookie expiration to never
|
cookie.maxAge = cookie.maxAge || -1;
|
|
// if the cookie's domain is set, use the appropriate client
|
if(cookie.domain) {
|
// add the cookies to the applicable domains
|
for(var key in _clients) {
|
var client = _clients[key];
|
if(http.withinCookieDomain(client.url, cookie) &&
|
client.secure === cookie.secure) {
|
client.setCookie(cookie);
|
}
|
}
|
} else {
|
// use the default domain
|
// FIXME: should a null domain cookie be added to all clients? should
|
// this be an option?
|
_client.setCookie(cookie);
|
}
|
};
|
|
/**
|
* Gets a cookie.
|
*
|
* @param name the name of the cookie.
|
* @param path an optional path for the cookie (if there are multiple cookies
|
* with the same name but different paths).
|
* @param domain an optional domain for the cookie (if not using the default
|
* domain).
|
*
|
* @return the cookie, cookies (if multiple matches), or null if not found.
|
*/
|
xhrApi.getCookie = function(name, path, domain) {
|
var rval = null;
|
|
if(domain) {
|
// get the cookies from the applicable domains
|
for(var key in _clients) {
|
var client = _clients[key];
|
if(http.withinCookieDomain(client.url, domain)) {
|
var cookie = client.getCookie(name, path);
|
if(cookie !== null) {
|
if(rval === null) {
|
rval = cookie;
|
} else if(!forge.util.isArray(rval)) {
|
rval = [rval, cookie];
|
} else {
|
rval.push(cookie);
|
}
|
}
|
}
|
}
|
} else {
|
// get cookie from default domain
|
rval = _client.getCookie(name, path);
|
}
|
|
return rval;
|
};
|
|
/**
|
* Removes a cookie.
|
*
|
* @param name the name of the cookie.
|
* @param path an optional path for the cookie (if there are multiple cookies
|
* with the same name but different paths).
|
* @param domain an optional domain for the cookie (if not using the default
|
* domain).
|
*
|
* @return true if a cookie was removed, false if not.
|
*/
|
xhrApi.removeCookie = function(name, path, domain) {
|
var rval = false;
|
|
if(domain) {
|
// remove the cookies from the applicable domains
|
for(var key in _clients) {
|
var client = _clients[key];
|
if(http.withinCookieDomain(client.url, domain)) {
|
if(client.removeCookie(name, path)) {
|
rval = true;
|
}
|
}
|
}
|
} else {
|
// remove cookie from default domain
|
rval = _client.removeCookie(name, path);
|
}
|
|
return rval;
|
};
|
|
/**
|
* Creates a new XmlHttpRequest. By default the base URL, flash policy port,
|
* etc, will be used. However, an XHR can be created to point at another
|
* cross-domain URL.
|
*
|
* @param options:
|
* logWarningOnError: If true and an HTTP error status code is received then
|
* log a warning, otherwise log a verbose message.
|
* verbose: If true be very verbose in the output including the response
|
* event and response body, otherwise only include status, timing, and
|
* data size.
|
* logError: a multi-var log function for warnings that takes the log
|
* category as the first var.
|
* logWarning: a multi-var log function for warnings that takes the log
|
* category as the first var.
|
* logDebug: a multi-var log function for warnings that takes the log
|
* category as the first var.
|
* logVerbose: a multi-var log function for warnings that takes the log
|
* category as the first var.
|
* url: the default base URL to connect to if xhr URLs are relative,
|
* eg: https://myserver.com, and note that the following options will be
|
* ignored if the URL is absent or the same as the default base URL.
|
* policyPort: the port that provides the server's flash policy, 0 to use
|
* the flash default.
|
* policyUrl: the policy file URL to use instead of a policy port.
|
* connections: the maximum number of concurrent connections.
|
* caCerts: a list of PEM-formatted certificates to trust.
|
* cipherSuites: an optional array of cipher suites to use, see
|
* forge.tls.CipherSuites.
|
* verify: optional TLS certificate verify callback to use (see forge.tls
|
* for details).
|
* getCertificate: an optional callback used to get a client-side
|
* certificate.
|
* getPrivateKey: an optional callback used to get a client-side private key.
|
* getSignature: an optional callback used to get a client-side signature.
|
* persistCookies: true to use persistent cookies via flash local storage,
|
* false to only keep cookies in javascript.
|
* primeTlsSockets: true to immediately connect TLS sockets on their
|
* creation so that they will cache TLS sessions for reuse.
|
*
|
* @return the XmlHttpRequest.
|
*/
|
xhrApi.create = function(options) {
|
// set option defaults
|
options = $.extend({
|
logWarningOnError: true,
|
verbose: false,
|
logError: function() {},
|
logWarning: function() {},
|
logDebug: function() {},
|
logVerbose: function() {},
|
url: null
|
}, options || {});
|
|
// private xhr state
|
var _state = {
|
// the http client to use
|
client: null,
|
// request storage
|
request: null,
|
// response storage
|
response: null,
|
// asynchronous, true if doing asynchronous communication
|
asynchronous: true,
|
// sendFlag, true if send has been called
|
sendFlag: false,
|
// errorFlag, true if a network error occurred
|
errorFlag: false
|
};
|
|
// private log functions
|
var _log = {
|
error: options.logError || forge.log.error,
|
warning: options.logWarning || forge.log.warning,
|
debug: options.logDebug || forge.log.debug,
|
verbose: options.logVerbose || forge.log.verbose
|
};
|
|
// create public xhr interface
|
var xhr = {
|
// an EventListener
|
onreadystatechange: null,
|
// readonly, the current readyState
|
readyState: UNSENT,
|
// a string with the response entity-body
|
responseText: '',
|
// a Document for response entity-bodies that are XML
|
responseXML: null,
|
// readonly, returns the HTTP status code (i.e. 404)
|
status: 0,
|
// readonly, returns the HTTP status message (i.e. 'Not Found')
|
statusText: ''
|
};
|
|
// determine which http client to use
|
if(options.url === null) {
|
// use default
|
_state.client = _client;
|
} else {
|
var url = http.parseUrl(options.url);
|
if(!url) {
|
var error = new Error('Invalid url.');
|
error.details = {
|
url: options.url
|
};
|
}
|
|
// find client
|
if(url.full in _clients) {
|
// client found
|
_state.client = _clients[url.full];
|
} else {
|
// create client
|
_state.client = http.createClient({
|
url: options.url,
|
socketPool: _sp,
|
policyPort: options.policyPort || _policyPort,
|
policyUrl: options.policyUrl || _policyUrl,
|
connections: options.connections || _maxConnections,
|
caCerts: options.caCerts,
|
cipherSuites: options.cipherSuites,
|
persistCookies: options.persistCookies || true,
|
primeTlsSockets: options.primeTlsSockets || false,
|
verify: options.verify,
|
getCertificate: options.getCertificate,
|
getPrivateKey: options.getPrivateKey,
|
getSignature: options.getSignature
|
});
|
_clients[url.full] = _state.client;
|
}
|
}
|
|
/**
|
* Opens the request. This method will create the HTTP request to send.
|
*
|
* @param method the HTTP method (i.e. 'GET').
|
* @param url the relative url (the HTTP request path).
|
* @param async always true, ignored.
|
* @param user always null, ignored.
|
* @param password always null, ignored.
|
*/
|
xhr.open = function(method, url, async, user, password) {
|
// 1. validate Document if one is associated
|
// TODO: not implemented (not used yet)
|
|
// 2. validate method token
|
// 3. change method to uppercase if it matches a known
|
// method (here we just require it to be uppercase, and
|
// we do not allow the standard methods)
|
// 4. disallow CONNECT, TRACE, or TRACK with a security error
|
switch(method) {
|
case 'DELETE':
|
case 'GET':
|
case 'HEAD':
|
case 'OPTIONS':
|
case 'PATCH':
|
case 'POST':
|
case 'PUT':
|
// valid method
|
break;
|
case 'CONNECT':
|
case 'TRACE':
|
case 'TRACK':
|
throw new Error('CONNECT, TRACE and TRACK methods are disallowed');
|
default:
|
throw new Error('Invalid method: ' + method);
|
}
|
|
// TODO: other validation steps in algorithm are not implemented
|
|
// 19. set send flag to false
|
// set response body to null
|
// empty list of request headers
|
// set request method to given method
|
// set request URL
|
// set username, password
|
// set asychronous flag
|
_state.sendFlag = false;
|
xhr.responseText = '';
|
xhr.responseXML = null;
|
|
// custom: reset status and statusText
|
xhr.status = 0;
|
xhr.statusText = '';
|
|
// create the HTTP request
|
_state.request = http.createRequest({
|
method: method,
|
path: url
|
});
|
|
// 20. set state to OPENED
|
xhr.readyState = OPENED;
|
|
// 21. dispatch onreadystatechange
|
if(xhr.onreadystatechange) {
|
xhr.onreadystatechange();
|
}
|
};
|
|
/**
|
* Adds an HTTP header field to the request.
|
*
|
* @param header the name of the header field.
|
* @param value the value of the header field.
|
*/
|
xhr.setRequestHeader = function(header, value) {
|
// 1. if state is not OPENED or send flag is true, raise exception
|
if(xhr.readyState != OPENED || _state.sendFlag) {
|
throw new Error('XHR not open or sending');
|
}
|
|
// TODO: other validation steps in spec aren't implemented
|
|
// set header
|
_state.request.setField(header, value);
|
};
|
|
/**
|
* Sends the request and any associated data.
|
*
|
* @param data a string or Document object to send, null to send no data.
|
*/
|
xhr.send = function(data) {
|
// 1. if state is not OPENED or 2. send flag is true, raise
|
// an invalid state exception
|
if(xhr.readyState != OPENED || _state.sendFlag) {
|
throw new Error('XHR not open or sending');
|
}
|
|
// 3. ignore data if method is GET or HEAD
|
if(data &&
|
_state.request.method !== 'GET' &&
|
_state.request.method !== 'HEAD') {
|
// handle non-IE case
|
if(typeof(XMLSerializer) !== 'undefined') {
|
if(data instanceof Document) {
|
var xs = new XMLSerializer();
|
_state.request.body = xs.serializeToString(data);
|
} else {
|
_state.request.body = data;
|
}
|
} else {
|
// poorly implemented IE case
|
if(typeof(data.xml) !== 'undefined') {
|
_state.request.body = data.xml;
|
} else {
|
_state.request.body = data;
|
}
|
}
|
}
|
|
// 4. release storage mutex (not used)
|
|
// 5. set error flag to false
|
_state.errorFlag = false;
|
|
// 6. if asynchronous is true (must be in this implementation)
|
|
// 6.1 set send flag to true
|
_state.sendFlag = true;
|
|
// 6.2 dispatch onreadystatechange
|
if(xhr.onreadystatechange) {
|
xhr.onreadystatechange();
|
}
|
|
// create send options
|
var options = {};
|
options.request = _state.request;
|
options.headerReady = function(e) {
|
// make cookies available for ease of use/iteration
|
xhr.cookies = _state.client.cookies;
|
|
// TODO: update document.cookie with any cookies where the
|
// script's domain matches
|
|
// headers received
|
xhr.readyState = HEADERS_RECEIVED;
|
xhr.status = e.response.code;
|
xhr.statusText = e.response.message;
|
_state.response = e.response;
|
if(xhr.onreadystatechange) {
|
xhr.onreadystatechange();
|
}
|
if(!_state.response.aborted) {
|
// now loading body
|
xhr.readyState = LOADING;
|
if(xhr.onreadystatechange) {
|
xhr.onreadystatechange();
|
}
|
}
|
};
|
options.bodyReady = function(e) {
|
xhr.readyState = DONE;
|
var ct = e.response.getField('Content-Type');
|
// Note: this null/undefined check is done outside because IE
|
// dies otherwise on a "'null' is null" error
|
if(ct) {
|
if(ct.indexOf('text/xml') === 0 ||
|
ct.indexOf('application/xml') === 0 ||
|
ct.indexOf('+xml') !== -1) {
|
try {
|
var doc = new ActiveXObject('MicrosoftXMLDOM');
|
doc.async = false;
|
doc.loadXML(e.response.body);
|
xhr.responseXML = doc;
|
} catch(ex) {
|
var parser = new DOMParser();
|
xhr.responseXML = parser.parseFromString(ex.body, 'text/xml');
|
}
|
}
|
}
|
|
var length = 0;
|
if(e.response.body !== null) {
|
xhr.responseText = e.response.body;
|
length = e.response.body.length;
|
}
|
// build logging output
|
var req = _state.request;
|
var output =
|
req.method + ' ' + req.path + ' ' +
|
xhr.status + ' ' + xhr.statusText + ' ' +
|
length + 'B ' +
|
(e.request.connectTime + e.request.time + e.response.time) +
|
'ms';
|
var lFunc;
|
if(options.verbose) {
|
lFunc = (xhr.status >= 400 && options.logWarningOnError) ?
|
_log.warning : _log.verbose;
|
lFunc(cat, output,
|
e, e.response.body ? '\n' + e.response.body : '\nNo content');
|
} else {
|
lFunc = (xhr.status >= 400 && options.logWarningOnError) ?
|
_log.warning : _log.debug;
|
lFunc(cat, output);
|
}
|
if(xhr.onreadystatechange) {
|
xhr.onreadystatechange();
|
}
|
};
|
options.error = function(e) {
|
var req = _state.request;
|
_log.error(cat, req.method + ' ' + req.path, e);
|
|
// 1. set response body to null
|
xhr.responseText = '';
|
xhr.responseXML = null;
|
|
// 2. set error flag to true (and reset status)
|
_state.errorFlag = true;
|
xhr.status = 0;
|
xhr.statusText = '';
|
|
// 3. set state to done
|
xhr.readyState = DONE;
|
|
// 4. asyc flag is always true, so dispatch onreadystatechange
|
if(xhr.onreadystatechange) {
|
xhr.onreadystatechange();
|
}
|
};
|
|
// 7. send request
|
_state.client.send(options);
|
};
|
|
/**
|
* Aborts the request.
|
*/
|
xhr.abort = function() {
|
// 1. abort send
|
// 2. stop network activity
|
_state.request.abort();
|
|
// 3. set response to null
|
xhr.responseText = '';
|
xhr.responseXML = null;
|
|
// 4. set error flag to true (and reset status)
|
_state.errorFlag = true;
|
xhr.status = 0;
|
xhr.statusText = '';
|
|
// 5. clear user headers
|
_state.request = null;
|
_state.response = null;
|
|
// 6. if state is DONE or UNSENT, or if OPENED and send flag is false
|
if(xhr.readyState === DONE || xhr.readyState === UNSENT ||
|
(xhr.readyState === OPENED && !_state.sendFlag)) {
|
// 7. set ready state to unsent
|
xhr.readyState = UNSENT;
|
} else {
|
// 6.1 set state to DONE
|
xhr.readyState = DONE;
|
|
// 6.2 set send flag to false
|
_state.sendFlag = false;
|
|
// 6.3 dispatch onreadystatechange
|
if(xhr.onreadystatechange) {
|
xhr.onreadystatechange();
|
}
|
|
// 7. set state to UNSENT
|
xhr.readyState = UNSENT;
|
}
|
};
|
|
/**
|
* Gets all response headers as a string.
|
*
|
* @return the HTTP-encoded response header fields.
|
*/
|
xhr.getAllResponseHeaders = function() {
|
var rval = '';
|
if(_state.response !== null) {
|
var fields = _state.response.fields;
|
$.each(fields, function(name, array) {
|
$.each(array, function(i, value) {
|
rval += name + ': ' + value + '\r\n';
|
});
|
});
|
}
|
return rval;
|
};
|
|
/**
|
* Gets a single header field value or, if there are multiple
|
* fields with the same name, a comma-separated list of header
|
* values.
|
*
|
* @return the header field value(s) or null.
|
*/
|
xhr.getResponseHeader = function(header) {
|
var rval = null;
|
if(_state.response !== null) {
|
if(header in _state.response.fields) {
|
rval = _state.response.fields[header];
|
if(forge.util.isArray(rval)) {
|
rval = rval.join();
|
}
|
}
|
}
|
return rval;
|
};
|
|
return xhr;
|
};
|
|
})(jQuery);
|
