PageRenderTime 77ms CodeModel.GetById 2ms app.highlight 65ms RepoModel.GetById 1ms app.codeStats 1ms

/node_modules/telehash/node_modules/telehash-cs2a/node_modules/node-forge/js/http.js

https://github.com/ImyarekRu/Paradox
JavaScript | 1413 lines | 799 code | 97 blank | 517 comment | 176 complexity | 0983f19e74e1bf57d71aafa3dd3e9ae1 MD5 | raw file
   1/**
   2 * HTTP client-side implementation that uses forge.net sockets.
   3 *
   4 * @author Dave Longley
   5 *
   6 * Copyright (c) 2010-2012 Digital Bazaar, Inc. All rights reserved.
   7 */
   8(function() {
   9
  10// define http namespace
  11var http = {};
  12
  13// logging category
  14var cat = 'forge.http';
  15
  16// add array of clients to debug storage
  17if(forge.debug) {
  18  forge.debug.set('forge.http', 'clients', []);
  19}
  20
  21// normalizes an http header field name
  22var _normalize = function(name) {
  23  return name.toLowerCase().replace(/(^.)|(-.)/g,
  24    function(a){return a.toUpperCase();});
  25};
  26
  27/**
  28 * Gets the local storage ID for the given client.
  29 *
  30 * @param client the client to get the local storage ID for.
  31 *
  32 * @return the local storage ID to use.
  33 */
  34var _getStorageId = function(client) {
  35  // TODO: include browser in ID to avoid sharing cookies between
  36  // browsers (if this is undesirable)
  37  // navigator.userAgent
  38  return 'forge.http.' +
  39    client.url.scheme + '.' +
  40    client.url.host + '.' +
  41    client.url.port;
  42};
  43
  44/**
  45 * Loads persistent cookies from disk for the given client.
  46 *
  47 * @param client the client.
  48 */
  49var _loadCookies = function(client) {
  50  if(client.persistCookies) {
  51    try {
  52      var cookies = forge.util.getItem(
  53        client.socketPool.flashApi,
  54        _getStorageId(client), 'cookies');
  55      client.cookies = cookies || {};
  56    }
  57    catch(ex) {
  58      // no flash storage available, just silently fail
  59      // TODO: i assume we want this logged somewhere or
  60      // should it actually generate an error
  61      //forge.log.error(cat, ex);
  62    }
  63  }
  64};
  65
  66/**
  67 * Saves persistent cookies on disk for the given client.
  68 *
  69 * @param client the client.
  70 */
  71var _saveCookies = function(client) {
  72  if(client.persistCookies) {
  73    try {
  74      forge.util.setItem(
  75        client.socketPool.flashApi,
  76        _getStorageId(client), 'cookies', client.cookies);
  77    }
  78    catch(ex) {
  79      // no flash storage available, just silently fail
  80      // TODO: i assume we want this logged somewhere or
  81      // should it actually generate an error
  82      //forge.log.error(cat, ex);
  83    }
  84  }
  85
  86  // FIXME: remove me
  87  _loadCookies(client);
  88};
  89
  90/**
  91 * Clears persistent cookies on disk for the given client.
  92 *
  93 * @param client the client.
  94 */
  95var _clearCookies = function(client) {
  96  if(client.persistCookies) {
  97    try {
  98      // only thing stored is 'cookies', so clear whole storage
  99      forge.util.clearItems(
 100        client.socketPool.flashApi,
 101        _getStorageId(client));
 102    }
 103    catch(ex) {
 104      // no flash storage available, just silently fail
 105      // TODO: i assume we want this logged somewhere or
 106      // should it actually generate an error
 107      //forge.log.error(cat, ex);
 108    }
 109  }
 110};
 111
 112/**
 113 * Connects and sends a request.
 114 *
 115 * @param client the http client.
 116 * @param socket the socket to use.
 117 */
 118var _doRequest = function(client, socket) {
 119  if(socket.isConnected()) {
 120    // already connected
 121    socket.options.request.connectTime = +new Date();
 122    socket.connected({
 123      type: 'connect',
 124      id: socket.id
 125    });
 126  }
 127  else {
 128    // connect
 129    socket.options.request.connectTime = +new Date();
 130    socket.connect({
 131      host: client.url.host,
 132      port: client.url.port,
 133      policyPort: client.policyPort,
 134      policyUrl: client.policyUrl
 135    });
 136  }
 137};
 138
 139/**
 140 * Handles the next request or marks a socket as idle.
 141 *
 142 * @param client the http client.
 143 * @param socket the socket.
 144 */
 145var _handleNextRequest = function(client, socket) {
 146  // clear buffer
 147  socket.buffer.clear();
 148
 149  // get pending request
 150  var pending = null;
 151  while(pending === null && client.requests.length > 0) {
 152    pending = client.requests.shift();
 153    if(pending.request.aborted) {
 154      pending = null;
 155    }
 156  }
 157
 158  // mark socket idle if no pending requests
 159  if(pending === null) {
 160    if(socket.options !== null) {
 161      socket.options = null;
 162    }
 163    client.idle.push(socket);
 164  }
 165  // handle pending request
 166  else {
 167    // allow 1 retry
 168    socket.retries = 1;
 169    socket.options = pending;
 170    _doRequest(client, socket);
 171  }
 172};
 173
 174/**
 175 * Sets up a socket for use with an http client.
 176 *
 177 * @param client the parent http client.
 178 * @param socket the socket to set up.
 179 * @param tlsOptions if the socket must use TLS, the TLS options.
 180 */
 181var _initSocket = function(client, socket, tlsOptions) {
 182  // no socket options yet
 183  socket.options = null;
 184
 185  // set up handlers
 186  socket.connected = function(e) {
 187    // socket primed by caching TLS session, handle next request
 188    if(socket.options === null) {
 189      _handleNextRequest(client, socket);
 190    }
 191    // socket in use
 192    else {
 193      var request = socket.options.request;
 194      request.connectTime = +new Date() - request.connectTime;
 195      e.socket = socket;
 196      socket.options.connected(e);
 197      if(request.aborted) {
 198        socket.close();
 199      }
 200      else {
 201        var out = request.toString();
 202        if(request.body) {
 203          out += request.body;
 204        }
 205        request.time = +new Date();
 206        socket.send(out);
 207        request.time = +new Date() - request.time;
 208        socket.options.response.time = +new Date();
 209        socket.sending = true;
 210      }
 211    }
 212  };
 213  socket.closed = function(e) {
 214    if(socket.sending) {
 215      socket.sending = false;
 216      if(socket.retries > 0) {
 217        --socket.retries;
 218        _doRequest(client, socket);
 219      }
 220      else {
 221        // error, closed during send
 222        socket.error({
 223          id: socket.id,
 224          type: 'ioError',
 225          message: 'Connection closed during send. Broken pipe.',
 226          bytesAvailable: 0
 227        });
 228      }
 229    }
 230    else {
 231      // handle unspecified content-length transfer
 232      var response = socket.options.response;
 233      if(response.readBodyUntilClose) {
 234        response.time = +new Date() - response.time;
 235        response.bodyReceived = true;
 236        socket.options.bodyReady({
 237          request: socket.options.request,
 238          response: response,
 239          socket: socket
 240        });
 241      }
 242      socket.options.closed(e);
 243      _handleNextRequest(client, socket);
 244    }
 245  };
 246  socket.data = function(e) {
 247    socket.sending = false;
 248    var request = socket.options.request;
 249    if(request.aborted) {
 250      socket.close();
 251    }
 252    else {
 253      // receive all bytes available
 254      var response = socket.options.response;
 255      var bytes = socket.receive(e.bytesAvailable);
 256      if(bytes !== null) {
 257        // receive header and then body
 258        socket.buffer.putBytes(bytes);
 259        if(!response.headerReceived) {
 260          response.readHeader(socket.buffer);
 261          if(response.headerReceived) {
 262            socket.options.headerReady({
 263              request: socket.options.request,
 264              response: response,
 265              socket: socket
 266            });
 267          }
 268        }
 269        if(response.headerReceived && !response.bodyReceived) {
 270          response.readBody(socket.buffer);
 271        }
 272        if(response.bodyReceived) {
 273          socket.options.bodyReady({
 274            request: socket.options.request,
 275            response: response,
 276            socket: socket
 277          });
 278          // close connection if requested or by default on http/1.0
 279          var value = response.getField('Connection') || '';
 280          if(value.indexOf('close') != -1 ||
 281            (response.version === 'HTTP/1.0' &&
 282            response.getField('Keep-Alive') === null)) {
 283            socket.close();
 284          }
 285          else {
 286            _handleNextRequest(client, socket);
 287          }
 288        }
 289      }
 290    }
 291  };
 292  socket.error = function(e) {
 293    // do error callback, include request
 294    socket.options.error({
 295      type: e.type,
 296      message: e.message,
 297      request: socket.options.request,
 298      response: socket.options.response,
 299      socket: socket
 300    });
 301    socket.close();
 302  };
 303
 304  // wrap socket for TLS
 305  if(tlsOptions) {
 306    socket = forge.tls.wrapSocket({
 307      sessionId: null,
 308      sessionCache: {},
 309      caStore: tlsOptions.caStore,
 310      cipherSuites: tlsOptions.cipherSuites,
 311      socket: socket,
 312      virtualHost: tlsOptions.virtualHost,
 313      verify: tlsOptions.verify,
 314      getCertificate: tlsOptions.getCertificate,
 315      getPrivateKey: tlsOptions.getPrivateKey,
 316      getSignature: tlsOptions.getSignature,
 317      deflate: tlsOptions.deflate || null,
 318      inflate: tlsOptions.inflate || null
 319    });
 320
 321    socket.options = null;
 322    socket.buffer = forge.util.createBuffer();
 323    client.sockets.push(socket);
 324    if(tlsOptions.prime) {
 325      // prime socket by connecting and caching TLS session, will do
 326      // next request from there
 327      socket.connect({
 328        host: client.url.host,
 329        port: client.url.port,
 330        policyPort: client.policyPort,
 331        policyUrl: client.policyUrl
 332      });
 333    }
 334    else {
 335      // do not prime socket, just add as idle
 336      client.idle.push(socket);
 337    }
 338  }
 339  else {
 340    // no need to prime non-TLS sockets
 341    socket.buffer = forge.util.createBuffer();
 342    client.sockets.push(socket);
 343    client.idle.push(socket);
 344  }
 345};
 346
 347/**
 348 * Checks to see if the given cookie has expired. If the cookie's max-age
 349 * plus its created time is less than the time now, it has expired, unless
 350 * its max-age is set to -1 which indicates it will never expire.
 351 *
 352 * @param cookie the cookie to check.
 353 *
 354 * @return true if it has expired, false if not.
 355 */
 356var _hasCookieExpired = function(cookie) {
 357  var rval = false;
 358
 359  if(cookie.maxAge !== -1) {
 360    var now = _getUtcTime(new Date());
 361    var expires = cookie.created + cookie.maxAge;
 362    if(expires <= now) {
 363      rval = true;
 364    }
 365  }
 366
 367  return rval;
 368};
 369
 370/**
 371 * Adds cookies in the given client to the given request.
 372 *
 373 * @param client the client.
 374 * @param request the request.
 375 */
 376var _writeCookies = function(client, request) {
 377  var expired = [];
 378  var url = client.url;
 379  var cookies = client.cookies;
 380  for(var name in cookies) {
 381    // get cookie paths
 382    var paths = cookies[name];
 383    for(var p in paths) {
 384      var cookie = paths[p];
 385      if(_hasCookieExpired(cookie)) {
 386        // store for clean up
 387        expired.push(cookie);
 388      }
 389      // path or path's ancestor must match cookie.path
 390      else if(request.path.indexOf(cookie.path) === 0) {
 391        request.addCookie(cookie);
 392      }
 393    }
 394  }
 395
 396  // clean up expired cookies
 397  for(var i = 0; i < expired.length; ++i) {
 398    var cookie = expired[i];
 399    client.removeCookie(cookie.name, cookie.path);
 400  }
 401};
 402
 403/**
 404 * Gets cookies from the given response and adds the to the given client.
 405 *
 406 * @param client the client.
 407 * @param response the response.
 408 */
 409var _readCookies = function(client, response) {
 410  var cookies = response.getCookies();
 411  for(var i = 0; i < cookies.length; ++i) {
 412    try {
 413      client.setCookie(cookies[i]);
 414    }
 415    catch(ex) {
 416      // ignore failure to add other-domain, etc. cookies
 417    }
 418  }
 419};
 420
 421/**
 422 * Creates an http client that uses forge.net sockets as a backend and
 423 * forge.tls for security.
 424 *
 425 * @param options:
 426 *   url: the url to connect to (scheme://host:port).
 427 *     socketPool: the flash socket pool to use.
 428 *   policyPort: the flash policy port to use (if other than the
 429 *     socket pool default), use 0 for flash default.
 430 *   policyUrl: the flash policy file URL to use (if provided will
 431 *     be used instead of a policy port).
 432 *   connections: number of connections to use to handle requests.
 433 *   caCerts: an array of certificates to trust for TLS, certs may
 434 *     be PEM-formatted or cert objects produced via forge.pki.
 435 *   cipherSuites: an optional array of cipher suites to use,
 436 *     see forge.tls.CipherSuites.
 437 *   virtualHost: the virtual server name to use in a TLS SNI
 438 *     extension, if not provided the url host will be used.
 439 *   verify: a custom TLS certificate verify callback to use.
 440 *   getCertificate: an optional callback used to get a client-side
 441 *     certificate (see forge.tls for details).
 442 *   getPrivateKey: an optional callback used to get a client-side
 443 *     private key (see forge.tls for details).
 444 *   getSignature: an optional callback used to get a client-side
 445 *     signature (see forge.tls for details).
 446 *   persistCookies: true to use persistent cookies via flash local
 447 *     storage, false to only keep cookies in javascript.
 448 *   primeTlsSockets: true to immediately connect TLS sockets on
 449 *     their creation so that they will cache TLS sessions for reuse.
 450 *
 451 * @return the client.
 452 */
 453http.createClient = function(options) {
 454  // create CA store to share with all TLS connections
 455  var caStore = null;
 456  if(options.caCerts) {
 457    caStore = forge.pki.createCaStore(options.caCerts);
 458  }
 459
 460  // get scheme, host, and port from url
 461  options.url = (options.url ||
 462    window.location.protocol + '//' + window.location.host);
 463  var url = http.parseUrl(options.url);
 464  if(!url) {
 465    throw {
 466      message: 'Invalid url.',
 467      details: {url: options.url}
 468    };
 469  }
 470
 471  // default to 1 connection
 472  options.connections = options.connections || 1;
 473
 474  // create client
 475  var sp = options.socketPool;
 476  var client = {
 477    // url
 478    url: url,
 479    // socket pool
 480    socketPool: sp,
 481    // the policy port to use
 482    policyPort: options.policyPort,
 483    // policy url to use
 484    policyUrl: options.policyUrl,
 485    // queue of requests to service
 486    requests: [],
 487    // all sockets
 488    sockets: [],
 489    // idle sockets
 490    idle: [],
 491    // whether or not the connections are secure
 492    secure: (url.scheme === 'https'),
 493    // cookie jar (key'd off of name and then path, there is only 1 domain
 494    // and one setting for secure per client so name+path is unique)
 495    cookies: {},
 496    // default to flash storage of cookies
 497    persistCookies: (typeof(options.persistCookies) === 'undefined') ?
 498      true : options.persistCookies
 499  };
 500
 501  // add client to debug storage
 502  if(forge.debug) {
 503    forge.debug.get('forge.http', 'clients').push(client);
 504  }
 505
 506  // load cookies from disk
 507  _loadCookies(client);
 508
 509  /**
 510   * A default certificate verify function that checks a certificate common
 511   * name against the client's URL host.
 512   *
 513   * @param c the TLS connection.
 514   * @param verified true if cert is verified, otherwise alert number.
 515   * @param depth the chain depth.
 516   * @param certs the cert chain.
 517   *
 518   * @return true if verified and the common name matches the host, error
 519   *         otherwise.
 520   */
 521  var _defaultCertificateVerify = function(c, verified, depth, certs) {
 522    if(depth === 0 && verified === true) {
 523      // compare common name to url host
 524      var cn = certs[depth].subject.getField('CN');
 525      if(cn === null || client.url.host !== cn.value) {
 526        verified = {
 527          message: 'Certificate common name does not match url host.'
 528        };
 529      }
 530    }
 531    return verified;
 532  };
 533
 534  // determine if TLS is used
 535  var tlsOptions = null;
 536  if(client.secure) {
 537    tlsOptions = {
 538      caStore: caStore,
 539      cipherSuites: options.cipherSuites || null,
 540      virtualHost: options.virtualHost || url.host,
 541      verify: options.verify || _defaultCertificateVerify,
 542      getCertificate: options.getCertificate || null,
 543      getPrivateKey: options.getPrivateKey || null,
 544      getSignature: options.getSignature || null,
 545      prime: options.primeTlsSockets || false
 546    };
 547
 548    // if socket pool uses a flash api, then add deflate support to TLS
 549    if(sp.flashApi !== null) {
 550      tlsOptions.deflate = function(bytes) {
 551        // strip 2 byte zlib header and 4 byte trailer
 552        return forge.util.deflate(sp.flashApi, bytes, true);
 553      };
 554      tlsOptions.inflate = function(bytes) {
 555        return forge.util.inflate(sp.flashApi, bytes, true);
 556      };
 557    }
 558  }
 559
 560  // create and initialize sockets
 561  for(var i = 0; i < options.connections; ++i) {
 562    _initSocket(client, sp.createSocket(), tlsOptions);
 563  }
 564
 565  /**
 566   * Sends a request. A method 'abort' will be set on the request that
 567   * can be called to attempt to abort the request.
 568   *
 569   * @param options:
 570   *          request: the request to send.
 571   *          connected: a callback for when the connection is open.
 572   *          closed: a callback for when the connection is closed.
 573   *          headerReady: a callback for when the response header arrives.
 574   *          bodyReady: a callback for when the response body arrives.
 575   *          error: a callback for if an error occurs.
 576   */
 577  client.send = function(options) {
 578    // add host header if not set
 579    if(options.request.getField('Host') === null) {
 580      options.request.setField('Host', client.url.fullHost);
 581    }
 582
 583    // set default dummy handlers
 584    var opts = {};
 585    opts.request = options.request;
 586    opts.connected = options.connected || function(){};
 587    opts.closed = options.close || function(){};
 588    opts.headerReady = function(e) {
 589      // read cookies
 590      _readCookies(client, e.response);
 591      if(options.headerReady) {
 592        options.headerReady(e);
 593      }
 594    };
 595    opts.bodyReady = options.bodyReady || function(){};
 596    opts.error = options.error || function(){};
 597
 598    // create response
 599    opts.response = http.createResponse();
 600    opts.response.time = 0;
 601    opts.response.flashApi = client.socketPool.flashApi;
 602    opts.request.flashApi = client.socketPool.flashApi;
 603
 604    // create abort function
 605    opts.request.abort = function() {
 606      // set aborted, clear handlers
 607      opts.request.aborted = true;
 608      opts.connected = function(){};
 609      opts.closed = function(){};
 610      opts.headerReady = function(){};
 611      opts.bodyReady = function(){};
 612      opts.error = function(){};
 613    };
 614
 615    // add cookies to request
 616    _writeCookies(client, opts.request);
 617
 618    // queue request options if there are no idle sockets
 619    if(client.idle.length === 0) {
 620      client.requests.push(opts);
 621    }
 622    // use an idle socket
 623    else {
 624      // prefer an idle *connected* socket first
 625      var socket = null;
 626      var len = client.idle.length;
 627      for(var i = 0; socket === null && i < len; ++i) {
 628        socket = client.idle[i];
 629        if(socket.isConnected()) {
 630          client.idle.splice(i, 1);
 631        }
 632        else {
 633          socket = null;
 634        }
 635      }
 636      // no connected socket available, get unconnected socket
 637      if(socket === null) {
 638        socket = client.idle.pop();
 639      }
 640      socket.options = opts;
 641      _doRequest(client, socket);
 642    }
 643  };
 644
 645  /**
 646   * Destroys this client.
 647   */
 648  client.destroy = function() {
 649    // clear pending requests, close and destroy sockets
 650    client.requests = [];
 651    for(var i = 0; i < client.sockets.length; ++i) {
 652      client.sockets[i].close();
 653      client.sockets[i].destroy();
 654    }
 655    client.socketPool = null;
 656    client.sockets = [];
 657    client.idle = [];
 658  };
 659
 660  /**
 661   * Sets a cookie for use with all connections made by this client. Any
 662   * cookie with the same name will be replaced. If the cookie's value
 663   * is undefined, null, or the blank string, the cookie will be removed.
 664   *
 665   * If the cookie's domain doesn't match this client's url host or the
 666   * cookie's secure flag doesn't match this client's url scheme, then
 667   * setting the cookie will fail with an exception.
 668   *
 669   * @param cookie the cookie with parameters:
 670   *   name: the name of the cookie.
 671   *   value: the value of the cookie.
 672   *   comment: an optional comment string.
 673   *   maxAge: the age of the cookie in seconds relative to created time.
 674   *   secure: true if the cookie must be sent over a secure protocol.
 675   *   httpOnly: true to restrict access to the cookie from javascript
 676   *     (inaffective since the cookies are stored in javascript).
 677   *   path: the path for the cookie.
 678   *   domain: optional domain the cookie belongs to (must start with dot).
 679   *   version: optional version of the cookie.
 680   *   created: creation time, in UTC seconds, of the cookie.
 681   */
 682  client.setCookie = function(cookie) {
 683    if(typeof(cookie.name) !== 'undefined') {
 684      if(cookie.value === null || typeof(cookie.value) === 'undefined' ||
 685        cookie.value === '') {
 686        // remove cookie
 687        rval = client.removeCookie(cookie.name, cookie.path);
 688      }
 689      else {
 690        // set cookie defaults
 691        cookie.comment = cookie.comment || '';
 692        cookie.maxAge = cookie.maxAge || 0;
 693        cookie.secure = (typeof(cookie.secure) === 'undefined') ?
 694          true : cookie.secure;
 695        cookie.httpOnly = cookie.httpOnly || true;
 696        cookie.path = cookie.path || '/';
 697        cookie.domain = cookie.domain || null;
 698        cookie.version = cookie.version || null;
 699        cookie.created = _getUtcTime(new Date());
 700
 701        // do secure check
 702        if(cookie.secure !== client.secure) {
 703          throw {
 704            message: 'Http client url scheme is incompatible ' +
 705              'with cookie secure flag.',
 706            url: client.url,
 707            cookie: cookie
 708          };
 709        }
 710        // make sure url host is within cookie.domain
 711        if(!http.withinCookieDomain(client.url, cookie)) {
 712          throw {
 713            message: 'Http client url host is incompatible with ' +
 714              'cookie domain.',
 715            url: client.url,
 716            cookie: cookie
 717          };
 718        }
 719
 720        // add new cookie
 721        if(!(cookie.name in client.cookies)) {
 722          client.cookies[cookie.name] = {};
 723        }
 724        client.cookies[cookie.name][cookie.path] = cookie;
 725        rval = true;
 726
 727        // save cookies
 728        _saveCookies(client);
 729      }
 730    }
 731
 732    return rval;
 733  };
 734
 735  /**
 736   * Gets a cookie by its name.
 737   *
 738   * @param name the name of the cookie to retrieve.
 739   * @param path an optional path for the cookie (if there are multiple
 740   *          cookies with the same name but different paths).
 741   *
 742   * @return the cookie or null if not found.
 743   */
 744  client.getCookie = function(name, path) {
 745    var rval = null;
 746    if(name in client.cookies) {
 747      var paths = client.cookies[name];
 748
 749      // get path-specific cookie
 750      if(path) {
 751        if(path in paths) {
 752          rval = paths[path];
 753        }
 754      }
 755      // get first cookie
 756      else {
 757        for(var p in paths) {
 758          rval = paths[p];
 759          break;
 760        }
 761      }
 762    }
 763    return rval;
 764  };
 765
 766  /**
 767   * Removes a cookie.
 768   *
 769   * @param name the name of the cookie to remove.
 770   * @param path an optional path for the cookie (if there are multiple
 771   *          cookies with the same name but different paths).
 772   *
 773   * @return true if a cookie was removed, false if not.
 774   */
 775  client.removeCookie = function(name, path) {
 776    var rval = false;
 777    if(name in client.cookies) {
 778      // delete the specific path
 779      if(path) {
 780        var paths = client.cookies[name];
 781        if(path in paths) {
 782          rval = true;
 783          delete client.cookies[name][path];
 784          // clean up entry if empty
 785          var empty = true;
 786          for(var i in client.cookies[name]) {
 787            empty = false;
 788            break;
 789          }
 790          if(empty) {
 791            delete client.cookies[name];
 792          }
 793        }
 794      }
 795      // delete all cookies with the given name
 796      else {
 797        rval = true;
 798        delete client.cookies[name];
 799      }
 800    }
 801    if(rval) {
 802      // save cookies
 803      _saveCookies(client);
 804    }
 805    return rval;
 806  };
 807
 808  /**
 809   * Clears all cookies stored in this client.
 810   */
 811  client.clearCookies = function() {
 812    client.cookies = {};
 813    _clearCookies(client);
 814  };
 815
 816  if(forge.log) {
 817    forge.log.debug('forge.http', 'created client', options);
 818  }
 819
 820  return client;
 821};
 822
 823/**
 824 * Trims the whitespace off of the beginning and end of a string.
 825 *
 826 * @param str the string to trim.
 827 *
 828 * @return the trimmed string.
 829 */
 830var _trimString = function(str) {
 831  return str.replace(/^\s*/, '').replace(/\s*$/, '');
 832};
 833
 834/**
 835 * Creates an http header object.
 836 *
 837 * @return the http header object.
 838 */
 839var _createHeader = function() {
 840  var header = {
 841    fields: {},
 842    setField: function(name, value) {
 843      // normalize field name, trim value
 844      header.fields[_normalize(name)] = [_trimString('' + value)];
 845    },
 846    appendField: function(name, value) {
 847      name = _normalize(name);
 848      if(!(name in header.fields)) {
 849        header.fields[name] = [];
 850      }
 851      header.fields[name].push(_trimString('' + value));
 852    },
 853    getField: function(name, index) {
 854      var rval = null;
 855      name = _normalize(name);
 856      if(name in header.fields) {
 857        index = index || 0;
 858        rval = header.fields[name][index];
 859      }
 860      return rval;
 861    }
 862  };
 863  return header;
 864};
 865
 866/**
 867 * Gets the time in utc seconds given a date.
 868 *
 869 * @param d the date to use.
 870 *
 871 * @return the time in utc seconds.
 872 */
 873var _getUtcTime = function(d) {
 874  var utc = +d + d.getTimezoneOffset() * 60000;
 875  return Math.floor(+new Date() / 1000);
 876};
 877
 878/**
 879 * Creates an http request.
 880 *
 881 * @param options:
 882 *          version: the version.
 883 *          method: the method.
 884 *          path: the path.
 885 *          body: the body.
 886 *          headers: custom header fields to add,
 887 *            eg: [{'Content-Length': 0}].
 888 *
 889 * @return the http request.
 890 */
 891http.createRequest = function(options) {
 892  options = options || {};
 893  var request = _createHeader();
 894  request.version = options.version || 'HTTP/1.1';
 895  request.method = options.method || null;
 896  request.path = options.path || null;
 897  request.body = options.body || null;
 898  request.bodyDeflated = false;
 899  request.flashApi = null;
 900
 901  // add custom headers
 902  var headers = options.headers || [];
 903  if(!forge.util.isArray(headers)) {
 904    headers = [headers];
 905  }
 906  for(var i = 0; i < headers.length; ++i) {
 907    for(var name in headers[i]) {
 908      request.appendField(name, headers[i][name]);
 909    }
 910  }
 911
 912  /**
 913   * Adds a cookie to the request 'Cookie' header.
 914   *
 915   * @param cookie a cookie to add.
 916   */
 917  request.addCookie = function(cookie) {
 918    var value = '';
 919    var field = request.getField('Cookie');
 920    if(field !== null) {
 921      // separate cookies by semi-colons
 922      value = field + '; ';
 923    }
 924
 925    // get current time in utc seconds
 926    var now = _getUtcTime(new Date());
 927
 928    // output cookie name and value
 929    value += cookie.name + '=' + cookie.value;
 930    request.setField('Cookie', value);
 931  };
 932
 933  /**
 934   * Converts an http request into a string that can be sent as an
 935   * HTTP request. Does not include any data.
 936   *
 937   * @return the string representation of the request.
 938   */
 939  request.toString = function() {
 940    /* Sample request header:
 941      GET /some/path/?query HTTP/1.1
 942      Host: www.someurl.com
 943      Connection: close
 944      Accept-Encoding: deflate
 945      Accept: image/gif, text/html
 946      User-Agent: Mozilla 4.0
 947     */
 948
 949    // set default headers
 950    if(request.getField('User-Agent') === null) {
 951      request.setField('User-Agent', 'forge.http 1.0');
 952    }
 953    if(request.getField('Accept') === null) {
 954      request.setField('Accept', '*/*');
 955    }
 956    if(request.getField('Connection') === null) {
 957      request.setField('Connection', 'keep-alive');
 958      request.setField('Keep-Alive', '115');
 959    }
 960
 961    // add Accept-Encoding if not specified
 962    if(request.flashApi !== null &&
 963      request.getField('Accept-Encoding') === null) {
 964      request.setField('Accept-Encoding', 'deflate');
 965    }
 966
 967    // if the body isn't null, deflate it if its larger than 100 bytes
 968    if(request.flashApi !== null && request.body !== null &&
 969      request.getField('Content-Encoding') === null &&
 970      !request.bodyDeflated && request.body.length > 100) {
 971      // use flash to compress data
 972      request.body = forge.util.deflate(request.flashApi, request.body);
 973      request.bodyDeflated = true;
 974      request.setField('Content-Encoding', 'deflate');
 975      request.setField('Content-Length', request.body.length);
 976    }
 977    else if(request.body !== null) {
 978      // set content length for body
 979      request.setField('Content-Length', request.body.length);
 980    }
 981
 982    // build start line
 983    var rval =
 984      request.method.toUpperCase() + ' ' + request.path + ' ' +
 985      request.version + '\r\n';
 986
 987    // add each header
 988    for(var name in request.fields) {
 989      var fields = request.fields[name];
 990      for(var i = 0; i < fields.length; ++i) {
 991        rval += name + ': ' + fields[i] + '\r\n';
 992      }
 993    }
 994    // final terminating CRLF
 995    rval += '\r\n';
 996
 997    return rval;
 998  };
 999
1000  return request;
1001};
1002
1003/**
1004 * Creates an empty http response header.
1005 *
1006 * @return the empty http response header.
1007 */
1008http.createResponse = function() {
1009  // private vars
1010  var _first = true;
1011  var _chunkSize = 0;
1012  var _chunksFinished = false;
1013
1014  // create response
1015  var response = _createHeader();
1016  response.version = null;
1017  response.code = 0;
1018  response.message = null;
1019  response.body = null;
1020  response.headerReceived = false;
1021  response.bodyReceived = false;
1022  response.flashApi = null;
1023
1024  /**
1025   * Reads a line that ends in CRLF from a byte buffer.
1026   *
1027   * @param b the byte buffer.
1028   *
1029   * @return the line or null if none was found.
1030   */
1031  var _readCrlf = function(b) {
1032    var line = null;
1033    var i = b.data.indexOf('\r\n', b.read);
1034    if(i != -1) {
1035      // read line, skip CRLF
1036      line = b.getBytes(i - b.read);
1037      b.getBytes(2);
1038    }
1039    return line;
1040  };
1041
1042  /**
1043   * Parses a header field and appends it to the response.
1044   *
1045   * @param line the header field line.
1046   */
1047  var _parseHeader = function(line) {
1048    var tmp = line.indexOf(':');
1049    var name = line.substring(0, tmp++);
1050    response.appendField(
1051      name, (tmp < line.length) ? line.substring(tmp) : '');
1052  };
1053
1054  /**
1055   * Reads an http response header from a buffer of bytes.
1056   *
1057   * @param b the byte buffer to parse the header from.
1058   *
1059   * @return true if the whole header was read, false if not.
1060   */
1061  response.readHeader = function(b) {
1062    // read header lines (each ends in CRLF)
1063    var line = '';
1064    while(!response.headerReceived && line !== null) {
1065      line = _readCrlf(b);
1066      if(line !== null) {
1067        // parse first line
1068        if(_first) {
1069          _first = false;
1070          var tmp = line.split(' ');
1071          if(tmp.length >= 3) {
1072            response.version = tmp[0];
1073            response.code = parseInt(tmp[1], 10);
1074            response.message = tmp.slice(2).join(' ');
1075          }
1076          else {
1077            // invalid header
1078            throw {
1079              message: 'Invalid http response header.',
1080              details: {'line': line}
1081            };
1082          }
1083        }
1084        // handle final line
1085        else if(line.length === 0) {
1086          // end of header
1087          response.headerReceived = true;
1088        }
1089        // parse header
1090        else {
1091          _parseHeader(line);
1092        }
1093      }
1094    }
1095
1096    return response.headerReceived;
1097  };
1098
1099  /**
1100   * Reads some chunked http response entity-body from the given buffer of
1101   * bytes.
1102   *
1103   * @param b the byte buffer to read from.
1104   *
1105   * @return true if the whole body was read, false if not.
1106   */
1107  var _readChunkedBody = function(b) {
1108    /* Chunked transfer-encoding sends data in a series of chunks,
1109      followed by a set of 0-N http trailers.
1110      The format is as follows:
1111
1112      chunk-size (in hex) CRLF
1113      chunk data (with "chunk-size" many bytes) CRLF
1114      ... (N many chunks)
1115      chunk-size (of 0 indicating the last chunk) CRLF
1116      N many http trailers followed by CRLF
1117      blank line + CRLF (terminates the trailers)
1118
1119      If there are no http trailers, then after the chunk-size of 0,
1120      there is still a single CRLF (indicating the blank line + CRLF
1121      that terminates the trailers). In other words, you always terminate
1122      the trailers with blank line + CRLF, regardless of 0-N trailers. */
1123
1124      /* From RFC-2616, section 3.6.1, here is the pseudo-code for
1125      implementing chunked transfer-encoding:
1126
1127      length := 0
1128      read chunk-size, chunk-extension (if any) and CRLF
1129      while (chunk-size > 0) {
1130        read chunk-data and CRLF
1131        append chunk-data to entity-body
1132        length := length + chunk-size
1133        read chunk-size and CRLF
1134      }
1135      read entity-header
1136      while (entity-header not empty) {
1137        append entity-header to existing header fields
1138        read entity-header
1139      }
1140      Content-Length := length
1141      Remove "chunked" from Transfer-Encoding
1142    */
1143
1144    var line = '';
1145    while(line !== null && b.length() > 0) {
1146      // if in the process of reading a chunk
1147      if(_chunkSize > 0) {
1148        // if there are not enough bytes to read chunk and its
1149        // trailing CRLF,  we must wait for more data to be received
1150        if(_chunkSize + 2 > b.length()) {
1151          break;
1152        }
1153
1154        // read chunk data, skip CRLF
1155        response.body += b.getBytes(_chunkSize);
1156        b.getBytes(2);
1157        _chunkSize = 0;
1158      }
1159      // if chunks not finished, read the next chunk size
1160      else if(!_chunksFinished) {
1161        // read chunk-size line
1162        line = _readCrlf(b);
1163        if(line !== null) {
1164          // parse chunk-size (ignore any chunk extension)
1165          _chunkSize = parseInt(line.split(';', 1)[0], 16);
1166          _chunksFinished = (_chunkSize === 0);
1167        }
1168      }
1169      // chunks finished, read trailers
1170      else {
1171        // read next trailer
1172        line = _readCrlf(b);
1173        while(line !== null) {
1174          if(line.length > 0) {
1175            // parse trailer
1176            _parseHeader(line);
1177            // read next trailer
1178            line = _readCrlf(b);
1179          }
1180          else {
1181            // body received
1182            response.bodyReceived = true;
1183            line = null;
1184          }
1185        }
1186      }
1187    }
1188
1189    return response.bodyReceived;
1190  };
1191
1192  /**
1193   * Reads an http response body from a buffer of bytes.
1194   *
1195   * @param b the byte buffer to read from.
1196   *
1197   * @return true if the whole body was read, false if not.
1198   */
1199  response.readBody = function(b) {
1200    var contentLength = response.getField('Content-Length');
1201    var transferEncoding = response.getField('Transfer-Encoding');
1202    if(contentLength !== null) {
1203      contentLength = parseInt(contentLength);
1204    }
1205
1206    // read specified length
1207    if(contentLength !== null && contentLength >= 0) {
1208      response.body = response.body || '';
1209      response.body += b.getBytes(contentLength);
1210      response.bodyReceived = (response.body.length === contentLength);
1211    }
1212    // read chunked encoding
1213    else if(transferEncoding !== null) {
1214      if(transferEncoding.indexOf('chunked') != -1) {
1215        response.body = response.body || '';
1216        _readChunkedBody(b);
1217      }
1218      else {
1219        throw {
1220          message: 'Unknown Transfer-Encoding.',
1221          details: {'transferEncoding' : transferEncoding}
1222        };
1223      }
1224    }
1225    // read all data in the buffer
1226    else if((contentLength !== null && contentLength < 0) ||
1227      (contentLength === null &&
1228      response.getField('Content-Type') !== null)) {
1229      response.body = response.body || '';
1230      response.body += b.getBytes();
1231      response.readBodyUntilClose = true;
1232    }
1233    else {
1234      // no body
1235      response.body = null;
1236      response.bodyReceived = true;
1237    }
1238
1239    if(response.bodyReceived) {
1240      response.time = +new Date() - response.time;
1241    }
1242
1243    if(response.flashApi !== null &&
1244      response.bodyReceived && response.body !== null &&
1245      response.getField('Content-Encoding') === 'deflate') {
1246      // inflate using flash api
1247      response.body = forge.util.inflate(
1248        response.flashApi, response.body);
1249    }
1250
1251    return response.bodyReceived;
1252  };
1253
1254   /**
1255    * Parses an array of cookies from the 'Set-Cookie' field, if present.
1256    *
1257    * @return the array of cookies.
1258    */
1259   response.getCookies = function() {
1260     var rval = [];
1261
1262     // get Set-Cookie field
1263     if('Set-Cookie' in response.fields) {
1264       var field = response.fields['Set-Cookie'];
1265
1266       // get current local time in seconds
1267       var now = +new Date() / 1000;
1268
1269       // regex for parsing 'name1=value1; name2=value2; name3'
1270       var regex = /\s*([^=]*)=?([^;]*)(;|$)/g;
1271
1272       // examples:
1273       // Set-Cookie: cookie1_name=cookie1_value; max-age=0; path=/
1274       // Set-Cookie: c2=v2; expires=Thu, 21-Aug-2008 23:47:25 GMT; path=/
1275       for(var i = 0; i < field.length; ++i) {
1276         var fv = field[i];
1277         var m;
1278         regex.lastIndex = 0;
1279         var first = true;
1280         var cookie = {};
1281         do {
1282           m = regex.exec(fv);
1283           if(m !== null) {
1284             var name = _trimString(m[1]);
1285             var value = _trimString(m[2]);
1286
1287             // cookie_name=value
1288             if(first) {
1289               cookie.name = name;
1290               cookie.value = value;
1291               first = false;
1292             }
1293             // property_name=value
1294             else {
1295               name = name.toLowerCase();
1296               switch(name) {
1297               case 'expires':
1298                 // replace hyphens w/spaces so date will parse
1299                 value = value.replace(/-/g, ' ');
1300                 var secs = Date.parse(value) / 1000;
1301                 cookie.maxAge = Math.max(0, secs - now);
1302                 break;
1303               case 'max-age':
1304                 cookie.maxAge = parseInt(value, 10);
1305                 break;
1306               case 'secure':
1307                 cookie.secure = true;
1308                 break;
1309               case 'httponly':
1310                 cookie.httpOnly = true;
1311                 break;
1312               default:
1313                 if(name !== '') {
1314                   cookie[name] = value;
1315                 }
1316               }
1317             }
1318           }
1319         }
1320         while(m !== null && m[0] !== '');
1321         rval.push(cookie);
1322       }
1323     }
1324
1325     return rval;
1326  };
1327
1328  /**
1329   * Converts an http response into a string that can be sent as an
1330   * HTTP response. Does not include any data.
1331   *
1332   * @return the string representation of the response.
1333   */
1334  response.toString = function() {
1335    /* Sample response header:
1336      HTTP/1.0 200 OK
1337      Host: www.someurl.com
1338      Connection: close
1339     */
1340
1341    // build start line
1342    var rval =
1343      response.version + ' ' + response.code + ' ' + response.message + '\r\n';
1344
1345    // add each header
1346    for(var name in response.fields) {
1347      var fields = response.fields[name];
1348      for(var i = 0; i < fields.length; ++i) {
1349        rval += name + ': ' + fields[i] + '\r\n';
1350      }
1351    }
1352    // final terminating CRLF
1353    rval += '\r\n';
1354
1355    return rval;
1356  };
1357
1358  return response;
1359};
1360
1361/**
1362 * Parses the scheme, host, and port from an http(s) url.
1363 *
1364 * @param str the url string.
1365 *
1366 * @return the parsed url object or null if the url is invalid.
1367 */
1368http.parseUrl = forge.util.parseUrl;
1369
1370/**
1371 * Returns true if the given url is within the given cookie's domain.
1372 *
1373 * @param url the url to check.
1374 * @param cookie the cookie or cookie domain to check.
1375 */
1376http.withinCookieDomain = function(url, cookie) {
1377  var rval = false;
1378
1379  // cookie may be null, a cookie object, or a domain string
1380  var domain = (cookie === null || typeof cookie === 'string') ?
1381    cookie : cookie.domain;
1382
1383  // any domain will do
1384  if(domain === null) {
1385    rval = true;
1386  }
1387  // ensure domain starts with a '.'
1388  else if(domain.charAt(0) === '.') {
1389    // parse URL as necessary
1390    if(typeof url === 'string') {
1391      url = http.parseUrl(url);
1392    }
1393
1394    // add '.' to front of URL host to match against domain
1395    var host = '.' + url.host;
1396
1397    // if the host ends with domain then it falls within it
1398    var idx = host.lastIndexOf(domain);
1399    if(idx !== -1 && (idx + domain.length === host.length)) {
1400      rval = true;
1401    }
1402  }
1403
1404  return rval;
1405};
1406
1407// public access to http namespace
1408if(typeof forge === 'undefined') {
1409  forge = {};
1410}
1411forge.http = http;
1412
1413})();