superagent 3.7.0 → 3.8.2

package/History.md

@@ -1,3 +1,15 @@
+# 3.8.1 (2017-11-08)
+
+ * Clear authorization header on cross-domain redirect
+
+# 3.8.0
+
+ * Added support for "globally" defined headers and event handlers via `superagent.agent()`. It now remembers default settings for all its requests.
+ * Added optional callback to `.retry()` (Alexander Murphy)
+ * Unified auth args handling in node/browser (Edmundo Alvarez)
+ * Fixed error handling in zlib pipes (Kornel)
+ * Documented that 3xx status codes are errors (Mickey Reiss)
+
 # 3.7.0 (2017-10-17)
 
  * Limit maximum response size. Prevents zip bombs (Kornel)

package/docs/index.md

@@ -211,13 +211,17 @@ SuperAgent will automatically serialize JSON and forms. If you want to send the
 
 ## Retrying requests
 
-When given the `.retry()` method, SuperAgent will automatically retry requests, if they fail in a way that is transient or could be due to a flaky Internet connection. `.retry()` takes an optional argument which is the maximum number of times to retry failed requests; the default is 3 times.
+When given the `.retry()` method, SuperAgent will automatically retry requests, if they fail in a way that is transient or could be due to a flaky Internet connection.
+
+This method has two optional arguments: number of retries (default 3) and a callback. It calls `callback(err, res)` before each retry. The callback may return `true`/`false` to control whether the request sould be retried (but the maximum number of retries is always applied).
 
      request
        .get('http://example.com/search')
        .retry(2)
        .end(callback);
 
+Use `.retry()` only with requests that are *idempotent* (i.e. multiple requests reaching the server won't cause undesirable side effects like duplicate purchases).
+
 ## Setting Accept
 
 In a similar fashion to the `.type()` method it is also possible to set the `Accept` header via the short hand method `.accept()`. Which references `request.types` as well allowing you to specify either the full canonicalized MIME type name as `type/subtype`, or the extension suffix form as "xml", "json", "png", etc. for convenience:
@@ -443,7 +447,9 @@ By default up to 5 redirects will be followed, however you may specify this with
       .redirects(2)
       .end(callback);
 
-## Preserving cookies
+## Agents for global state
+
+### Saving cookies
 
 In Node SuperAgent does not save cookies by default, but you can use the `.agent()` method to create a copy of SuperAgent that saves cookies. Each copy has a separate cookie jar.
 
@@ -454,7 +460,18 @@ In Node SuperAgent does not save cookies by default, but you can use the `.agent
         return agent.get('/cookied-page');
       });
 
-In browsers cookies are managed automatically by the browser, and there is no `.agent()` method.
+In browsers cookies are managed automatically by the browser, so the `.agent()` does not isolate cookies.
+
+### Default options for multiple requests
+
+Regular request methods (`.use()`, `.set()`, `.auth()`) called on the agent will be used as defaults for all requests made by that agent.
+
+    const agent = request.agent()
+      .use(plugin)
+      .auth(shared);
+
+    await agent.get('/with-plugin-and-auth');
+    await agent.get('/also-with-plugin-and-auth');
 
 ## Piping data
 
@@ -467,7 +484,7 @@ The Node client allows you to pipe data to and from the request. For example pip
     const req = request.post('/somewhere');
     req.type('json');
     stream.pipe(req);
-    
+
 Note that when you pipe to a request, superagent sends the piped data with [chunked transfer encoding](https://en.wikipedia.org/wiki/Chunked_transfer_encoding), which isn't supported by all servers (for instance, Python WSGI servers).
 
 Or piping the response to a file:
@@ -476,6 +493,22 @@ Or piping the response to a file:
     const req = request.get('/some.json');
     req.pipe(stream);
 
+Note that you should **NOT** attempt to pipe the result of `.end()` or the `Response` object:
+
+    // Don't do either of these:
+    const stream = getAWritableStream();
+    const req = request
+      .get('/some.json')
+      // this pipes garbage to the stream and fails in unexpected ways
+      .end((err, response) => response.pipe(stream))
+    const req = request
+      .get('/some.json')
+      .end()
+      // this is also unsupported, .pipe calls .end for you.
+      .pipe(stream);
+
+In a [future version](https://github.com/visionmedia/superagent/issues/1188) of superagent, improper calls to `pipe()` will fail.
+
 ## Multipart requests
 
 SuperAgent is also great for _building_ multipart requests for which it provides methods `.attach()` and `.field()`.
@@ -556,7 +589,7 @@ An "error" event is also emitted, with you can listen for:
 
       });
 
-Note that a 4xx or 5xx response with super agent **are** considered an error by default. For example if you get a 500 or 403 response, this status information will be available via `err.status`. Errors from such responses also contain an `err.response` field with all of the properties mentioned in "[Response properties](#response-properties)". The library behaves in this way to handle the common case of wanting success responses and treating HTTP error status codes as errors while still allowing for custom logic around specific error conditions.
+Note that **superagent considers 4xx and 5xx responses (as well as unhandled 3xx responses) errors by default**. For example, if you get a `304 Not modified`, `403 Forbidden` or `500 Internal server error` response, this status information will be available via `err.status`. Errors from such responses also contain an `err.response` field with all of the properties mentioned in "[Response properties](#response-properties)". The library behaves in this way to handle the common case of wanting success responses and treating HTTP error status codes as errors while still allowing for custom logic around specific error conditions.
 
 Network failures, timeouts, and other errors that produce no response will contain no `err.status` or `err.response` fields.
 

package/lib/agent-base.js

@@ -0,0 +1,20 @@
+function Agent() {
+  this._defaults = [];
+}
+
+["use", "on", "once", "set", "query", "type", "accept", "auth", "withCredentials", "sortQuery", "retry", "ok", "redirects",
+ "timeout", "buffer", "serialize", "parse", "ca", "key", "pfx", "cert"].forEach(function(fn) {
+  /** Default setting for all requests from this agent */
+  Agent.prototype[fn] = function(/*varargs*/) {
+    this._defaults.push({fn:fn, arguments:arguments});
+    return this;
+  }
+});
+
+Agent.prototype._setDefaults = function(req) {
+    this._defaults.forEach(function(def) {
+      req[def.fn].apply(req, def.arguments);
+    });
+};
+
+module.exports = Agent;

package/lib/client.js

@@ -16,7 +16,7 @@ var Emitter = require('component-emitter');
 var RequestBase = require('./request-base');
 var isObject = require('./is-object');
 var ResponseBase = require('./response-base');
-var shouldRetry = require('./should-retry');
+var Agent = require('./agent-base');
 
 /**
  * Noop.
@@ -123,9 +123,9 @@ function pushEncodedKeyValuePair(pairs, key, val) {
  * Expose serialization method.
  */
 
- request.serializeObject = serialize;
+request.serializeObject = serialize;
 
- /**
+/**
   * Parse the given x-www-form-urlencoded `str`.
   *
   * @param {String} str
@@ -184,12 +184,12 @@ request.types = {
  *
  */
 
- request.serialize = {
-   'application/x-www-form-urlencoded': serialize,
-   'application/json': JSON.stringify
- };
+request.serialize = {
+  'application/x-www-form-urlencoded': serialize,
+  'application/json': JSON.stringify,
+};
 
- /**
+/**
   * Default parsers.
   *
   *     superagent.parse['application/xml'] = function(str){
@@ -200,7 +200,7 @@ request.types = {
 
 request.parse = {
   'application/x-www-form-urlencoded': parseString,
-  'application/json': JSON.parse
+  'application/json': JSON.parse,
 };
 
 /**
@@ -243,7 +243,9 @@ function parseHeader(str) {
  */
 
 function isJSON(mime) {
-  return /[\/+]json\b/.test(mime);
+  // should match /json or +json
+  // but not /json-seq
+  return /[\/+]json($|[^-\w])/.test(mime);
 }
 
 /**
@@ -303,7 +305,7 @@ function Response(req) {
   var status = this.xhr.status;
   // handle IE9 bug: http://stackoverflow.com/questions/10046972/msie-returns-status-code-of-1223-for-ajax-request
   if (status === 1223) {
-      status = 204;
+    status = 204;
   }
   this._setStatusProperties(status);
   this.header = this.headers = parseHeader(this.xhr.getAllResponseHeaders());
@@ -335,9 +337,9 @@ ResponseBase(Response.prototype);
  * @api private
  */
 
-Response.prototype._parseBody = function(str){
+Response.prototype._parseBody = function(str) {
   var parse = request.parse[this.type];
-  if(this.req._parser) {
+  if (this.req._parser) {
     return this.req._parser(this, str);
   }
   if (!parse && isJSON(this.type)) {
@@ -508,30 +510,25 @@ Request.prototype.accept = function(type){
  */
 
 Request.prototype.auth = function(user, pass, options){
-  if (typeof pass === 'object' && pass !== null) { // pass is optional and can substitute for options
+  if (1 === arguments.length) pass = '';
+  if (typeof pass === 'object' && pass !== null) { // pass is optional and can be replaced with options
     options = pass;
+    pass = '';
   }
   if (!options) {
     options = {
       type: 'function' === typeof btoa ? 'basic' : 'auto',
-    }
+    };
   }
 
-  switch (options.type) {
-    case 'basic':
-      this.set('Authorization', 'Basic ' + btoa(user + ':' + pass));
-    break;
-
-    case 'auto':
-      this.username = user;
-      this.password = pass;
-    break;
+  var encoder = function(string) {
+    if ('function' === typeof btoa) {
+      return btoa(string);
+    }
+    throw new Error('Cannot use basic auth, btoa is not a function');
+  };
 
-    case 'bearer': // usage would be .auth(accessToken, { type: 'bearer' })
-      this.set('Authorization', 'Bearer ' + user);
-    break;
-  }
-  return this;
+  return this._auth(user, pass, options, encoder);
 };
 
 /**
@@ -599,8 +596,7 @@ Request.prototype._getFormData = function(){
  */
 
 Request.prototype.callback = function(err, res){
-  // console.log(this._retries, this._maxRetries)
-  if (this._maxRetries && this._retries++ < this._maxRetries && shouldRetry(err, res)) {
+  if (this._shouldRetry(err, res)) {
     return this._retry();
   }
 
@@ -682,7 +678,7 @@ Request.prototype.end = function(fn){
 
 Request.prototype._end = function() {
   var self = this;
-  var xhr = this.xhr = request.getXHR();
+  var xhr = (this.xhr = request.getXHR());
   var data = this._formData || this._data;
 
   this._setTimeouts();
@@ -716,7 +712,7 @@ Request.prototype._end = function() {
     }
     e.direction = direction;
     self.emit('progress', e);
-  }
+  };
   if (this.hasListeners('progress')) {
     try {
       xhr.onprogress = handleProgress.bind(null, 'download');
@@ -777,6 +773,23 @@ Request.prototype._end = function() {
   return this;
 };
 
+request.agent = function() {
+  return new Agent();
+};
+
+["GET", "POST", "OPTIONS", "PATCH", "PUT", "DELETE"].forEach(function(method) {
+  Agent.prototype[method.toLowerCase()] = function(url, fn) {
+    var req = new request.Request(method, url);
+    this._setDefaults(req);
+    if (fn) {
+      req.end(fn);
+    }
+    return req;
+  };
+});
+
+Agent.prototype.del = Agent.prototype['delete'];
+
 /**
  * GET `url` with optional callback `fn(res)`.
  *
@@ -787,9 +800,9 @@ Request.prototype._end = function() {
  * @api public
  */
 
-request.get = function(url, data, fn){
+request.get = function(url, data, fn) {
   var req = request('GET', url);
-  if ('function' == typeof data) fn = data, data = null;
+  if ('function' == typeof data) (fn = data), (data = null);
   if (data) req.query(data);
   if (fn) req.end(fn);
   return req;
@@ -805,9 +818,9 @@ request.get = function(url, data, fn){
  * @api public
  */
 
-request.head = function(url, data, fn){
+request.head = function(url, data, fn) {
   var req = request('HEAD', url);
-  if ('function' == typeof data) fn = data, data = null;
+  if ('function' == typeof data) (fn = data), (data = null);
   if (data) req.query(data);
   if (fn) req.end(fn);
   return req;
@@ -823,9 +836,9 @@ request.head = function(url, data, fn){
  * @api public
  */
 
-request.options = function(url, data, fn){
+request.options = function(url, data, fn) {
   var req = request('OPTIONS', url);
-  if ('function' == typeof data) fn = data, data = null;
+  if ('function' == typeof data) (fn = data), (data = null);
   if (data) req.send(data);
   if (fn) req.end(fn);
   return req;
@@ -841,13 +854,13 @@ request.options = function(url, data, fn){
  * @api public
  */
 
-function del(url, data, fn){
+function del(url, data, fn) {
   var req = request('DELETE', url);
-  if ('function' == typeof data) fn = data, data = null;
+  if ('function' == typeof data) (fn = data), (data = null);
   if (data) req.send(data);
   if (fn) req.end(fn);
   return req;
-};
+}
 
 request['del'] = del;
 request['delete'] = del;
@@ -862,9 +875,9 @@ request['delete'] = del;
  * @api public
  */
 
-request.patch = function(url, data, fn){
+request.patch = function(url, data, fn) {
   var req = request('PATCH', url);
-  if ('function' == typeof data) fn = data, data = null;
+  if ('function' == typeof data) (fn = data), (data = null);
   if (data) req.send(data);
   if (fn) req.end(fn);
   return req;
@@ -880,9 +893,9 @@ request.patch = function(url, data, fn){
  * @api public
  */
 
-request.post = function(url, data, fn){
+request.post = function(url, data, fn) {
   var req = request('POST', url);
-  if ('function' == typeof data) fn = data, data = null;
+  if ('function' == typeof data) (fn = data), (data = null);
   if (data) req.send(data);
   if (fn) req.end(fn);
   return req;
@@ -898,9 +911,9 @@ request.post = function(url, data, fn){
  * @api public
  */
 
-request.put = function(url, data, fn){
+request.put = function(url, data, fn) {
   var req = request('PUT', url);
-  if ('function' == typeof data) fn = data, data = null;
+  if ('function' == typeof data) (fn = data), (data = null);
   if (data) req.send(data);
   if (fn) req.end(fn);
   return req;

package/lib/node/agent.js

@@ -4,11 +4,12 @@
  * Module dependencies.
  */
 
-var CookieJar = require('cookiejar').CookieJar;
-var CookieAccess = require('cookiejar').CookieAccessInfo;
-var parse = require('url').parse;
-var request = require('../..');
-var methods = require('methods');
+const CookieJar = require('cookiejar').CookieJar;
+const CookieAccess = require('cookiejar').CookieAccessInfo;
+const parse = require('url').parse;
+const request = require('../..');
+const AgentBase = require('../agent-base');
+let methods = require('methods');
 
 /**
  * Expose `Agent`.
@@ -23,16 +24,22 @@ module.exports = Agent;
  */
 
 function Agent(options) {
-  if (!(this instanceof Agent)) return new Agent(options);
+  if (!(this instanceof Agent)) {
+    return new Agent(options);
+  }
+  AgentBase.call(this);
+  this.jar = new CookieJar();
+
   if (options) {
-    this._ca = options.ca;
-    this._key = options.key;
-    this._pfx = options.pfx;
-    this._cert = options.cert;
+    if (options.ca) {this.ca(options.ca);}
+    if (options.key) {this.key(options.key);}
+    if (options.pfx) {this.pfx(options.pfx);}
+    if (options.cert) {this.cert(options.cert);}
   }
-  this.jar = new CookieJar;
 }
 
+Agent.prototype = Object.create(AgentBase.prototype);
+
 /**
  * Save the cookies in the given `res` to
  * the agent's cookie jar for persistence.
@@ -41,8 +48,8 @@ function Agent(options) {
  * @api private
  */
 
-Agent.prototype._saveCookies = function(res){
-  var cookies = res.headers['set-cookie'];
+Agent.prototype._saveCookies = function(res) {
+  const cookies = res.headers['set-cookie'];
   if (cookies) this.jar.setCookies(cookies);
 };
 
@@ -53,39 +60,33 @@ Agent.prototype._saveCookies = function(res){
  * @api private
  */
 
-Agent.prototype._attachCookies = function(req){
-  var url = parse(req.url);
-  var access = CookieAccess(url.hostname, url.pathname, 'https:' == url.protocol);
-  var cookies = this.jar.getCookies(access).toValueString();
+Agent.prototype._attachCookies = function(req) {
+  const url = parse(req.url);
+  const access = CookieAccess(
+    url.hostname,
+    url.pathname,
+    'https:' == url.protocol
+  );
+  const cookies = this.jar.getCookies(access).toValueString();
   req.cookies = cookies;
 };
 
-// generate HTTP verb methods
-if (methods.indexOf('del') == -1) {
-  // create a copy so we don't cause conflicts with
-  // other packages using the methods package and
-  // npm 3.x
-  methods = methods.slice(0);
-  methods.push('del');
-}
-methods.forEach(function(method){
-  var name = method;
-  method = 'del' == method ? 'delete' : method;
-
-  method = method.toUpperCase();
-  Agent.prototype[name] = function(url, fn){
-    var req = new request.Request(method, url);
-    req.ca(this._ca);
-    req.key(this._key);
-    req.pfx(this._pfx);
-    req.cert(this._cert);
+methods.forEach(name => {
+  const method = name.toUpperCase();
+  Agent.prototype[name] = function(url, fn) {
+    const req = new request.Request(method, url);
 
     req.on('response', this._saveCookies.bind(this));
     req.on('redirect', this._saveCookies.bind(this));
     req.on('redirect', this._attachCookies.bind(this, req));
     this._attachCookies(req);
+    this._setDefaults(req);
 
-    fn && req.end(fn);
+    if (fn) {
+      req.end(fn);
+    }
     return req;
   };
 });
+
+Agent.prototype.del = Agent.prototype['delete'];