superagent 4.0.0-alpha.1 → 4.0.0-beta.5

package/.travis.yml

@@ -1,7 +1,7 @@
 sudo: false
 language: node_js
 node_js:
-  - "9"
+  - "10"
   - "8"
   - "6"
 
@@ -14,3 +14,6 @@ matrix:
   include:
     - node_js: "9"
       env: BROWSER=1
+  include:
+    - node_js: "10"
+      env: HTTP2_TEST=1

package/.zuul.yml

@@ -8,8 +8,6 @@ browsers:
     version: latest
   - name: safari
     version: latest
-  - name: iphone
-    version: latest
   - name: ie
     version: 9..latest
 browserify:

package/History.md

@@ -2,10 +2,13 @@
 
 ## Breaking changes
 
- * Node.js v4 has reached it's end of life, so we no longer support it. It's v6+ or later.
+ * Node.js v4 has reached it's end of life, so we no longer support it. It's v6+ or later. We recommend Node.js 10.
  * We now use ES6 in the browser code, too.
     * If you're using Browserify or Webpack to package code for Internet Explorer, you will also have to use Babel.
     * The pre-built node_modules/superagent.js is still ES5-compatible.
+ * `.end(…)` returns `undefined` instead of the request. If you need the request object after calling `.end()` (and you probably don't), save it in a variable and call `request.end(…)`. Consider not using `.end()` at all, and migrating to promises by calling `.then()` instead.
+ * In Node, responses with unknown MIME type are buffered by default. To get old behavior, if you use custom *unbuffered* parsers, add `.buffer(false)` to requests or set `superagent.buffer[yourMimeType] = false`.
+ * Invalid uses of `.pipe()` throw.
 
 ## Minor changes
 
@@ -16,6 +19,7 @@
  * Leave backticks unencoded in query strings where possible (Ethan Resnick)
  * Update node-mime to 2.x (Alexey Kucherenko)
  * Allow default buffer settings based on response-type (shrey)
+ * `response.buffered` is more accurate.
 
 # 3.8.3 (2018-04-29)
 

package/Makefile

@@ -11,6 +11,15 @@ test:
 test-node:
 	@NODE_ENV=test NODE_TLS_REJECT_UNAUTHORIZED=0 ./node_modules/.bin/mocha \
 		--require should \
+		--trace-warnings \
+		--reporter $(REPORTER) \
+		--timeout 5000 \
+		$(NODETESTS)
+
+test-node-http2:
+	@NODE_ENV=test HTTP2_TEST=1 NODE_TLS_REJECT_UNAUTHORIZED=0 node ./node_modules/.bin/mocha \
+		--require should \
+		--trace-warnings \
 		--reporter $(REPORTER) \
 		--timeout 5000 \
 		$(NODETESTS)

package/Readme.md

@@ -2,7 +2,7 @@
 
 [![Sauce Test Status](https://saucelabs.com/browser-matrix/shtylman-superagent.svg)](https://saucelabs.com/u/shtylman-superagent)
 
-SuperAgent is a small progressive __client-side__ HTTP request library, and __Node.js__ module with the same API, sporting many high-level HTTP client features. View the [docs](http://visionmedia.github.io/superagent/).
+SuperAgent is a small progressive __client-side__ HTTP request library, and __Node.js__ module with the same API, sporting many high-level HTTP client features. View the [docs](https://visionmedia.github.io/superagent/).
 
 ![super agent](http://f.cl.ly/items/3d282n3A0h0Z0K2w0q2a/Screenshot.png)
 
@@ -63,10 +63,9 @@ Existing plugins:
  * [superagent-mock](https://github.com/M6Web/superagent-mock) - simulate HTTP calls by returning data fixtures based on the requested URL
  * [superagent-mocker](https://github.com/shuvalov-anton/superagent-mocker) — simulate REST API
  * [superagent-cache](https://github.com/jpodwys/superagent-cache) - A global SuperAgent patch with built-in, flexible caching
-  * [superagent-cache-plugin](https://github.com/jpodwys/superagent-cache-plugin) - A SuperAgent plugin with built-in, flexible caching
+ * [superagent-cache-plugin](https://github.com/jpodwys/superagent-cache-plugin) - A SuperAgent plugin with built-in, flexible caching
  * [superagent-jsonapify](https://github.com/alex94puchades/superagent-jsonapify) - A lightweight [json-api](http://jsonapi.org/format/) client addon for superagent
  * [superagent-serializer](https://github.com/zzarcon/superagent-serializer) - Converts server payload into different cases
- * [superagent-use](https://github.com/koenpunt/superagent-use) - A client addon to apply plugins to all requests.
  * [superagent-httpbackend](https://www.npmjs.com/package/superagent-httpbackend) - stub out requests using AngularJS' $httpBackend syntax
  * [superagent-throttle](https://github.com/leviwheatcroft/superagent-throttle) - queues and intelligently throttles requests
  * [superagent-charset](https://github.com/magicdawn/superagent-charset) - add charset support for node's SuperAgent
@@ -80,15 +79,19 @@ For SuperAgent extensions such as couchdb and oauth visit the [wiki](https://git
 
 Our breaking changes are mostly in rarely used functionality and from stricter error handling.
 
+* [3.x to 4.x](https://github.com/visionmedia/superagent/releases/tag/v4.0.0-alpha.1):
+  - Ensure you're running Node 6 or later. We've dropped support for Node 4.
+  - We've started using ES6 and for compatibility with Internet Explorer you may need to use Babel.
+  - We suggest migrating from `.end()` callbacks to `.then()` or `await`.
 * [2.x to 3.x](https://github.com/visionmedia/superagent/releases/tag/v3.0.0):
-  - Ensure you're running Node 4 or later. We dropped support for Node 0.x.
+  - Ensure you're running Node 4 or later. We've dropped support for Node 0.x.
   - Test code that calls `.send()` multiple times. Invalid calls to `.send()` will now throw instead of sending garbage.
 * [1.x to 2.x](https://github.com/visionmedia/superagent/releases/tag/v2.0.0):
   - If you use `.parse()` in the *browser* version, rename it to `.serialize()`.
   - If you rely on `undefined` in query-string values being sent literally as the text "undefined", switch to checking for missing value instead. `?key=undefined` is now `?key` (without a value).
   - If you use `.then()` in Internet Explorer, ensure that you have a polyfill that adds a global `Promise` object.
 * 0.x to 1.x:
-  - Use `.end(function(err, res){})`. 1-argument version is no longer supported.
+  - Instead of 1-argument callback `.end(function(res){})` use `.then(res => {})`.
 
 ## Running node tests
 

package/docs/index.md

@@ -8,13 +8,13 @@ SuperAgent is light-weight progressive ajax API crafted for flexibility, readabi
        .send({ name: 'Manny', species: 'cat' })
        .set('X-API-Key', 'foobar')
        .set('Accept', 'application/json')
-       .then(function(res) {
+       .then(res => {
           alert('yay got ' + JSON.stringify(res.body));
        });
 
 ## Test documentation
 
-The following [test documentation](docs/test.html) was generated with [Mocha's](http://mochajs.org/) "doc" reporter, and directly reflects the test suite. This provides an additional source of documentation.
+The following [test documentation](docs/test.html) was generated with [Mocha's](https://mochajs.org/) "doc" reporter, and directly reflects the test suite. This provides an additional source of documentation.
 
 ## Request basics
 
@@ -22,10 +22,10 @@ A request can be initiated by invoking the appropriate method on the `request` o
 
      request
        .get('/search')
-       .then(function(res) {
+       .then(res => {
           // res.body, res.headers, res.status
        })
-       .catch(function(err) {
+       .catch(err => {
           // err.message, err.response
        });
 
@@ -33,7 +33,7 @@ HTTP method may also be passed as a string:
 
     request('GET', '/search').then(success, failure);
 
-Old-style callbacks are also supported. *Instead of* `.then()` you can call `.end()`:
+Old-style callbacks are also supported, but not recommended. *Instead of* `.then()` you can call `.end()`:
 
     request('GET', '/search').end(function(err, res){
       if (res.ok) {}
@@ -42,12 +42,12 @@ Old-style callbacks are also supported. *Instead of* `.then()` you can call `.en
 Absolute URLs can be used. In web browsers absolute URLs work only if the server implements [CORS](#cors).
 
      request
-       .get('http://example.com/search')
-       .then(function(res) {
+       .get('https://example.com/search')
+       .then(res => {
 
        });
 
-The __Node__ client supports making requests to [Unix Domain Sockets](http://en.wikipedia.org/wiki/Unix_domain_socket):
+The __Node__ client supports making requests to [Unix Domain Sockets](https://en.wikipedia.org/wiki/Unix_domain_socket):
 
      // pattern: https?+unix://SOCKET_PATH/REQUEST_PATH
      //          Use `%2F` as `/` in SOCKET_PATH
@@ -61,7 +61,7 @@ __DELETE__, __HEAD__, __PATCH__, __POST__, and __PUT__ requests can also be used
 
     request
       .head('/favicon.ico')
-      .then(function(res) {
+      .then(res => {
 
       });
 
@@ -69,7 +69,7 @@ __DELETE__ can be also called as `.del()` for compatibility with old IE where `d
 
 The HTTP method defaults to __GET__, so if you wish, the following is valid:
 
-     request('/search', function(err, res){
+     request('/search', (err, res) => {
 
      });
 
@@ -99,7 +99,7 @@ The `.query()` method accepts objects, which when used with the __GET__ method w
        .query({ query: 'Manny' })
        .query({ range: '1..5' })
        .query({ order: 'desc' })
-       .then(function(res) {
+       .then(res => {
 
        });
 
@@ -108,7 +108,7 @@ Or as a single object:
     request
       .get('/search')
       .query({ query: 'Manny', range: '1..5', order: 'desc' })
-      .then(function(res) {
+      .then(res => {
 
       });
 
@@ -117,7 +117,7 @@ The `.query()` method accepts strings as well:
       request
         .get('/querystring')
         .query('search=Manny&range=1..5')
-        .then(function(res) {
+        .then(res => {
 
         });
 
@@ -127,7 +127,7 @@ Or joined:
         .get('/querystring')
         .query('search=Manny')
         .query('range=1..5')
-        .then(function(res) {
+        .then(res => {
 
         });
 
@@ -138,7 +138,7 @@ You can also use the `.query()` method for HEAD requests. The following will pro
       request
         .head('/users')
         .query({ email: 'joe@smith.com' })
-        .then(function(res) {
+        .then(res => {
 
         });
 
@@ -216,8 +216,8 @@ request.serialize['application/xml'] = function (obj) {
     return 'string generated from obj';
 };
 
-//going forward, all requests with a Content-type of
-//'application/xml' will be automatically serialized
+// going forward, all requests with a Content-type of
+// 'application/xml' will be automatically serialized
 ```
 If you want to send the payload in a custom format, you can replace
 the built-in serialization with the `.serialize()` method on a per-request basis:
@@ -226,7 +226,7 @@ the built-in serialization with the `.serialize()` method on a per-request basis
 request
     .post('/user')
     .send({foo: 'bar'})
-    .serialize(function serializer(obj) {
+    .serialize(obj => {
         return 'string generated from obj';
     });
 ```
@@ -237,7 +237,7 @@ When given the `.retry()` method, SuperAgent will automatically retry requests,
 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')
+       .get('https://example.com/search')
        .retry(2) // or:
        .retry(2, callback)
        .then(finished);
@@ -286,9 +286,7 @@ By default the query string is not assembled in any particular order. An asciibe
  request.get('/user')
    .query('name=Nick')
    .query('search=Manny')
-   .sortQuery(function(a, b){
-     return a.length - b.length;
-   })
+   .sortQuery((a, b) => a.length - b.length)
    .then(callback)
 ```
 
@@ -383,7 +381,7 @@ In browsers, you may use `.responseType('blob')` to request handling of binary r
 ```js
 req.get('/binary.data')
   .responseType('blob')
-  .end(function (error, res) {
+  .then(res => {
     // res.body will be a browser native Blob type here
   });
 ```
@@ -444,11 +442,11 @@ To abort requests simply invoke the `req.abort()` method.
 
 Sometimes networks and servers get "stuck" and never respond after accepting a request. Set timeouts to avoid requests waiting forever.
 
-  * `req.timeout({deadline:ms})` or `req.timeout(ms)` (where `ms` is a number of milliseconds > 0) sets a deadline for the entire request (including all redirects) to complete. If the response isn't fully downloaded within that time, the request will be aborted.
+  * `req.timeout({deadline:ms})` or `req.timeout(ms)` (where `ms` is a number of milliseconds > 0) sets a deadline for the entire request (including all uploads, redirects, server processing time) to complete. If the response isn't fully downloaded within that time, the request will be aborted.
 
-  * `req.timeout({response:ms})` sets maximum time to wait for the first byte to arrive from the server, but it does not limit how long the entire download can take. Response timeout should be a few seconds longer than just the time it takes server to respond, because it also includes time to make DNS lookup, TCP/IP and TLS connections.
+  * `req.timeout({response:ms})` sets maximum time to wait for the first byte to arrive from the server, but it does not limit how long the entire download can take. Response timeout should be at least few seconds longer than just the time it takes the server to respond, because it also includes time to make DNS lookup, TCP/IP and TLS connections, and time to upload request data.
 
-You should use both `deadline` and `response` timeouts. This way you can use a short response timeout to detect unresponsive networks quickly, and a long deadline to give time for downloads on slow, but reliable, networks.
+You should use both `deadline` and `response` timeouts. This way you can use a short response timeout to detect unresponsive networks quickly, and a long deadline to give time for downloads on slow, but reliable, networks. Note that both of these timers limit how long *uploads* of attached files are allowed to take. Use long timeouts if you're uploading files.
 
     request
       .get('/big-file?network=slow')
@@ -609,9 +607,9 @@ For security reasons, browsers will block cross-origin requests unless the serve
 The `.withCredentials()` method enables the ability to send cookies from the origin, however only when `Access-Control-Allow-Origin` is _not_ a wildcard ("*"), and `Access-Control-Allow-Credentials` is "true".
 
     request
-      .get('http://api.example.com:4001/')
+      .get('https://api.example.com:4001/')
       .withCredentials()
-      .then(function(res) {
+      .then(res => {
         assert.equal(200, res.status);
         assert.equal('tobi', res.text);
       })
@@ -623,7 +621,7 @@ Your callback function will always be passed two arguments: error and response.
     request
      .post('/upload')
      .attach('image', 'path/to/tobi.png')
-     .then(function(res) {
+     .then(res => {
 
      });
 
@@ -633,7 +631,7 @@ An "error" event is also emitted, with you can listen for:
       .post('/upload')
       .attach('image', 'path/to/tobi.png')
       .on('error', handle)
-      .then(function(res) {
+      .then(res => {
 
       });
 
@@ -673,7 +671,7 @@ SuperAgent fires `progress` events on upload and download of large files.
           loaded: // bytes downloaded or uploaded so far
         } */
       })
-      .end()
+      .then()
 
 ## Promise and Generator support
 
@@ -698,4 +696,4 @@ If want to use WebPack to compile code for Node.JS, you *must* specify [node tar
 
 ### Using browser version in electron
 
-[Electron](http://electron.atom.io/) developers report if you would prefer to use the browser version of SuperAgent instead of the Node version, you can `require('superagent/superagent')`. Your requests will now show up in the Chrome developer tools Network tab. Note this environment is not covered by automated test suite and not officially supported.
+[Electron](https://electron.atom.io/) developers report if you would prefer to use the browser version of SuperAgent instead of the Node version, you can `require('superagent/superagent')`. Your requests will now show up in the Chrome developer tools Network tab. Note this environment is not covered by automated test suite and not officially supported.

package/docs/test.html

@@ -265,7 +265,7 @@
 .post(uri + '/echo')
 .send({ name: 'tobi' })
 .end(function(err, res){
-  assert.equal(null, err);
+  assert.ifError(err)
   res.text.should.equal('{"name":"tobi"}');
   done();
 });</code></pre></dd>
@@ -662,7 +662,7 @@ request
 .get('http://localhost:5000/custom')
 .buffer()
 .end(function(err, res){
-  assert.equal(null, err);
+  assert.ifError(err)
   assert.equal('custom stuff', res.text);
   assert(res.buffered);
   done();
@@ -679,7 +679,7 @@ request
 .send('hello this is dog')
 .buffer(false)
 .end(function(err, res){
-  assert.equal(null, err);
+  assert.ifError(err)
   assert.equal(null, res.text);
   res.body.should.eql({});
   var buf = '';
@@ -734,7 +734,7 @@ done();</code></pre></dd>
 .type('application/x-dog')
 .send('hello this is dog')
 .end(function(err, res){
-  assert.equal(null, err);
+  assert.ifError(err)
   assert.equal(null, res.text);
   res.body.should.eql({});
   var buf = '';
@@ -761,7 +761,7 @@ request
 .send(img)
 .buffer(false)
 .end(function(err, res){
-  assert.equal(null, err);
+  assert.ifError(err)
   assert(!res.buffered);
   assert.equal(res.header['content-length'], Buffer.byteLength(img));
   done();
@@ -774,7 +774,7 @@ request
 .send(img)
 .buffer(true)
 .end(function(err, res){
-  assert.equal(null, err);
+  assert.ifError(err)
   assert(res.buffered);
   assert.equal(res.header['content-length'], img.length);
   done();

package/dump.js

@@ -0,0 +1 @@
+

package/lib/client.js

@@ -673,7 +673,7 @@ Request.prototype.end = function(fn){
   // querystring
   this._finalizeQueryString();
 
-  return this._end();
+  this._end();
 };
 
 Request.prototype._end = function() {
@@ -772,7 +772,6 @@ Request.prototype._end = function() {
   // IE11 xhr.send(undefined) sends 'undefined' string as POST payload (instead of nothing)
   // We need null here if data is undefined
   xhr.send(typeof data !== 'undefined' ? data : null);
-  return this;
 };
 
 request.agent = () => new Agent();

package/lib/node/http2wrapper.js

@@ -0,0 +1,188 @@
+'use strict';
+
+const http2 = require('http2');
+const Stream = require('stream');
+const util = require('util');
+const net = require('net');
+const tls = require('tls');
+const parse = require('url').parse;
+
+const {
+  HTTP2_HEADER_PATH,
+  HTTP2_HEADER_STATUS,
+  HTTP2_HEADER_METHOD,
+  HTTP2_HEADER_AUTHORITY,
+  HTTP2_HEADER_HOST,
+  HTTP2_HEADER_SET_COOKIE,
+  NGHTTP2_CANCEL,
+} = http2.constants;
+
+
+function setProtocol(protocol) {
+  return {
+    request: function (options) {
+      return new Request(protocol, options);
+    }
+  }
+}
+
+function Request(protocol, options) {
+  Stream.call(this);
+  const defaultPort = protocol === 'https:' ? 443 : 80;
+  const defaultHost = 'localhost'
+  const port = options.port || defaultPort;
+  const host = options.host || defaultHost;
+
+  delete options.port
+  delete options.host
+
+  this.method = options.method;
+  this.path = options.path;
+  this.protocol = protocol;
+  this.host = host;
+
+  delete options.method
+  delete options.path
+
+  const sessionOptions = Object.assign({}, options);
+  if (options.socketPath) {
+    sessionOptions.socketPath = options.socketPath;
+    sessionOptions.createConnection = this.createUnixConnection.bind(this);
+  }
+
+  this._headers = {};
+
+  const session = http2.connect(`${protocol}//${host}:${port}`, sessionOptions);
+  this.setHeader('host', `${host}:${port}`)
+
+  session.on('error', (err) => this.emit('error', err));
+
+  this.session = session;
+}
+
+/**
+ * Inherit from `Stream` (which inherits from `EventEmitter`).
+ */
+util.inherits(Request, Stream);
+
+Request.prototype.createUnixConnection = function (authority, options) {
+  switch (this.protocol) {
+    case 'http:':
+      return net.connect(options.socketPath);
+    case 'https:':
+      options.ALPNProtocols = ['h2'];
+      options.servername = this.host;
+      options.allowHalfOpen = true;
+      return tls.connect(options.socketPath, options);
+    default:
+      throw new Error('Unsupported protocol', this.protocol);
+  }
+}
+
+Request.prototype.setNoDelay = function (bool) {
+  // We can not use setNoDelay with HTTP/2.
+  // Node 10 limits http2session.socket methods to ones safe to use with HTTP/2.
+  // See also https://nodejs.org/api/http2.html#http2_http2session_socket
+}
+
+Request.prototype.getFrame = function () {
+  if (this.frame) {
+    return this.frame;
+  }
+
+  const method = {
+    [HTTP2_HEADER_PATH]: this.path,
+    [HTTP2_HEADER_METHOD]: this.method,
+  }
+
+  let headers = this.mapToHttp2Header(this._headers);
+
+  headers = Object.assign(headers, method);
+
+  const frame = this.session.request(headers);
+  frame.once('response', (headers, flags) => {
+    headers = this.mapToHttpHeader(headers);
+    frame.headers = headers;
+    frame.status = frame.statusCode = headers[HTTP2_HEADER_STATUS];
+    this.emit('response', frame);
+  });
+
+  this._headerSent = true;
+
+  frame.once('drain', () => this.emit('drain'));
+  frame.on('error', (err) => this.emit('error', err));
+  frame.on('close', () => this.session.close());
+
+  this.frame = frame;
+  return frame;
+}
+
+Request.prototype.mapToHttpHeader = function (headers) {
+  const keys = Object.keys(headers);
+  const http2Headers = {};
+  for (var i = 0; i < keys.length; i++) {
+    let key = keys[i];
+    let value = headers[key];
+    key = key.toLowerCase();
+    switch (key) {
+      case HTTP2_HEADER_SET_COOKIE:
+        value = Array.isArray(value) ? value : [value];
+        break;
+      default:
+        break;
+    }
+    http2Headers[key] = value;
+  }
+  return http2Headers;
+}
+
+Request.prototype.mapToHttp2Header = function (headers) {
+  const keys = Object.keys(headers);
+  const http2Headers = {};
+  for (var i = 0; i < keys.length; i++) {
+    let key = keys[i];
+    let value = headers[key];
+    key = key.toLowerCase();
+    switch (key) {
+      case HTTP2_HEADER_HOST:
+        key = HTTP2_HEADER_AUTHORITY;
+        value = /^http\:\/\/|^https\:\/\//.test(value) ? parse(value).host : value;
+        break;
+      default:
+        break;
+    }
+    http2Headers[key] = value;
+  }
+  return http2Headers;
+}
+
+Request.prototype.setHeader = function (name, value) {
+  this._headers[name.toLowerCase()] = value;
+}
+
+Request.prototype.getHeader = function (name) {
+  return this._headers[name.toLowerCase()];
+}
+
+Request.prototype.write = function (data, encoding) {
+  const frame = this.getFrame();
+  return frame.write(data, encoding);
+};
+
+Request.prototype.pipe = function (stream, options) {
+  const frame = this.getFrame();
+  return frame.pipe(stream, options);
+}
+
+Request.prototype.end = function (data) {
+  const frame = this.getFrame();
+  frame.end(data);
+}
+
+Request.prototype.abort = function (data) {
+  const frame = this.getFrame();
+  frame.close(NGHTTP2_CANCEL);
+  this.session.destroy();
+}
+
+exports.setProtocol = setProtocol;