superagent - npm Package Compare versions

Comparing version 4.0.0 to 4.1.0-beta.1

docs/index.md

@@ -52,10 +52,12 @@
 
-     // pattern: https?+unix://SOCKET_PATH/REQUEST_PATH
-     //          Use `%2F` as `/` in SOCKET_PATH
-     request
-       .get('http+unix://%2Fabsolute%2Fpath%2Fto%2Funix.sock/search')
-       .then(res => {
+    // pattern: https?+unix://SOCKET_PATH/REQUEST_PATH
+    //          Use `%2F` as `/` in SOCKET_PATH
+    try {
+      const res = await request
+        .get('http+unix://%2Fabsolute%2Fpath%2Fto%2Funix.sock/search');
+      // res.body, res.headers, res.status
+    } catch(err) {
+      // err.message, err.response
+    }
 
-       });
-
 __DELETE__, __HEAD__, __PATCH__, __POST__, and __PUT__ requests can also be used, simply change the method name:
@@ -154,2 +156,3 @@
         .then(callback)
+        .catch(errorCallback)
 
@@ -160,3 +163,3 @@ Since JSON is undoubtedly the most common, it's the _default_! The following example is equivalent to the previous.
         .send({ name: 'tj', pet: 'tobi' })
-        .then(callback)
+        .then(callback, errorCallback)
 
@@ -168,3 +171,3 @@ Or using multiple `.send()` calls:
         .send({ pet: 'tobi' })
-        .then(callback)
+        .then(callback, errorCallback)
 
@@ -177,3 +180,3 @@ By default sending strings will set the `Content-Type` to `application/x-www-form-urlencoded`,
         .send('pet=tobi')
-        .then(callback);
+        .then(callback, errorCallback);
 
@@ -186,3 +189,3 @@ SuperAgent formats are extensible, however by default "json" and "form" are supported. To send the data as `application/x-www-form-urlencoded` simply invoke `.type()` with "form", where the default is "json". This request will __POST__ the body "name=tj&pet=tobi".
         .send({ pet: 'tobi' })
-        .then(callback)
+        .then(callback, errorCallback)
 
@@ -193,3 +196,3 @@ Sending a [`FormData`](https://developer.mozilla.org/en-US/docs/Web/API/FormData/FormData) object is also supported. The following example will __POST__ the content of the HTML form identified by id="myForm":
         .send(new FormData(document.getElementById('myForm')))
-        .then(callback)
+        .then(callback, errorCallback)
 
@@ -251,2 +254,3 @@ ## Setting the `Content-Type`
        .then(finished);
+       .catch(failed);
 
@@ -495,7 +499,6 @@ Use `.retry()` only with requests that are *idempotent* (i.e. multiple requests reaching the server won't cause undesirable side effects like duplicate purchases).
 
-    request
-      .get('/some.png')
-      .redirects(2)
-      .then(callback);
+    const response = await request.get('/some.png').redirects(2);
 
+Redirects exceeding the limit are treated as errors. Use `.ok(res => res.status < 400)` to read them as successful responses.
+
 ## Agents for global state
@@ -685,6 +688,38 @@
 
+
+## Testing on localhost
+
+### Forcing specific connection IP address
+
+In Node.js it's possible to ignore DNS resolution and direct all requests to a specific IP address using `.connect()` method. For example, this request will go to localhost instead of `example.com`:
+
+    const res = await request.get("http://example.com").connect("127.0.0.1");
+
+Because the request may be redirected, it's possible to specify multiple hostnames and multiple IPs, as well as a special `*` as the fallback (note: other wildcards are not supported). The requests will keep their `Host` header with the original value. `.connect(undefined)` turns off the feature.
+
+    const res = await request.get("http://redir.example.com:555")
+      .connect({
+        "redir.example.com": "127.0.0.1", // redir.example.com:555 will use 127.0.0.1:555
+        "www.example.com": false, // don't override this one; use DNS as normal
+        "*": "proxy.example.com", // all other requests will go to this host
+      });
+
+### Ignoring broken/insecure HTTPS on localhost
+
+In Node.js, when HTTPS is misconfigured and insecure (e.g. using self-signed certificate *without* specifying own `.ca()`), it's still possible to permit requests to `localhost` by calling `.trustLocalhost()`:
+
+    const res = await request.get("https://localhost").trustLocalhost()
+
+Together with `.connect("127.0.0.1")` this may be used to force HTTPS requests to any domain to be re-routed to `localhost` instead.
+
+It's generally safe to ignore broken HTTPS on `localhost`, because the loopback interface is not exposed to untrusted networks. Trusting `localhost` may become the default in the future. Use `.trustLocalhost(false)` to force check of `127.0.0.1`'s authenticity.
+
+We intentionally don't support disabling of HTTPS security when making requests to any other IP, because such options end up abused as a quick "fix" for HTTPS problems. You can get free HTTPS certificates from [Let's Encrypt](https://certbot.eff.org) or set your own CA (`.ca(ca_public_pem)`) to make your self-signed certificates trusted.
+
 ## Promise and Generator support
 
-SuperAgent's request is a "thenable" object that's compatible with JavaScript promises and `async`/`await` syntax.
+SuperAgent's request is a "thenable" object that's compatible with JavaScript promises and the `async`/`await` syntax.
 
+    const res = await request.get(url);
+
 If you're using promises, **do not** call `.end()` or `.pipe()`. Any use of `.then()` or `await` disables all other ways of using the request.
@@ -691,0 +726,0 @@

History.md

@@ -1,3 +0,8 @@
-# 4.0.0
+# 4.1.0-beta (2018-12-02)
 
+ * `.connect()` IP/DNS override option (Kornel)
+ * `.trustLocalhost()` option for allowing broken HTTPS on `localhost`
+
+# 4.0.0  (2018-11-17)
+
 ## Breaking changes
@@ -4,0 +9,0 @@

lib/node/index.js

@@ -677,2 +677,20 @@ 'use strict';
 
+  // Override IP address of a hostname
+  if (this._connectOverride) {
+    const hostname = url.hostname;
+    const match = hostname in this._connectOverride ? this._connectOverride[hostname] : this._connectOverride['*'];
+    if (match) {
+      // backup the real host
+      if (!this._header['host']) {
+        this.set('host', url.host);
+      }
+      // wrap [ipv6]
+      url.host = /:/.test(match) ? `[${match}]` : match;
+      if (url.port) {
+        url.host += `:${url.port}`;
+      }
+      url.hostname = match;
+    }
+  }
+
   // options
@@ -695,2 +713,6 @@ options.method = this.method;
 
+  if (this._trustLocalhost && /^(?:localhost|127\.0\.0\.\d+|(0*:)+:0*1)$/.test(url.hostname)) {
+    options.rejectUnauthorized = false;
+  }
+
   // initiate request
@@ -1144,2 +1166,31 @@ const mod = this._enableHttp2 ? exports.protocols['http2:'].setProtocol(url.protocol) : exports.protocols[url.protocol];
 
+/**
+ * Overrides DNS for selected hostnames. Takes object mapping hostnames to IP addresses.
+ *
+ * When making a request to a URL with a hostname exactly matching a key in the object,
+ * use the given IP address to connect, instead of using DNS to resolve the hostname.
+ *
+ * A special host `*` matches every hostname (keep redirects in mind!)
+ *
+ *      request.connect({
+ *        'test.example.com': '127.0.0.1',
+ *        'ipv6.example.com': '::1',
+ *      })
+ */
+Request.prototype.connect = function(connectOverride) {
+  if ('string' === typeof connectOverride) {
+    this._connectOverride = {'*': connectOverride};
+  } else if ('object' === typeof connectOverride) {
+    this._connectOverride = connectOverride;
+  } else {
+    this._connectOverride = undefined;
+  }
+  return this;
+};
+
+Request.prototype.trustLocalhost = function(toggle) {
+    this._trustLocalhost = toggle === undefined ? true : toggle;
+    return this;
+};
+
 // generate HTTP verb methods
@@ -1146,0 +1197,0 @@ if (methods.indexOf('del') == -1) {

package.json

 {
   "name": "superagent",
-  "version": "4.0.0",
+  "version": "4.1.0-beta.1",
   "description": "elegant & feature rich browser / node HTTP with a fluent API",
@@ -30,9 +30,9 @@ "scripts": {
     "cookiejar": "^2.1.2",
-    "debug": "^4.0.0",
-    "form-data": "^2.3.2",
+    "debug": "^4.1.0",
+    "form-data": "^2.3.3",
     "formidable": "^1.2.0",
     "methods": "^1.1.1",
-    "mime": "^2.0.3",
-    "qs": "^6.5.1",
-    "readable-stream": "^3.0.3"
+    "mime": "^2.4.0",
+    "qs": "^6.6.0",
+    "readable-stream": "^3.0.6"
   },
@@ -46,9 +46,9 @@ "devDependencies": {
     "body-parser": "^1.18.2",
-    "browserify": "^16.2.0",
+    "browserify": "^16.2.3",
     "cookie-parser": "^1.4.3",
     "express": "^4.16.3",
     "express-session": "^1.15.6",
-    "marked": "^0.5.0",
+    "marked": "^0.5.2",
     "mocha": "^3.5.3",
-    "multer": "^1.3.0",
+    "multer": "^1.4.1",
     "should": "^13.2.0",
@@ -55,0 +55,0 @@ "should-http": "^0.1.1",

Readme.md

@@ -5,3 +5,3 @@ # SuperAgent [![Build Status](https://travis-ci.org/visionmedia/superagent.svg?branch=master)](https://travis-ci.org/visionmedia/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/).
+SuperAgent is a small progressive __client-side__ and __Node.js__ HTTP request library, sporting many high-level HTTP client features. View the [docs](https://visionmedia.github.io/superagent/).
 
@@ -21,10 +21,7 @@ ![super agent](http://f.cl.ly/items/3d282n3A0h0Z0K2w0q2a/Screenshot.png)
 ```js
-request
+const res = await request
   .post('/api/pet')
   .send({ name: 'Manny', species: 'cat' }) // sends a JSON post body
   .set('X-API-Key', 'foobar')
-  .set('accept', 'json')
-  .end((err, res) => {
-    // Calling the end function will send the request
-  });
+  .set('accept', 'json');
 ```
@@ -40,3 +37,3 @@
 
-Node 6 or later is required.
+Node 6 or later is required. For older browsers ES6-to-ES5 translation (like Babel) is required.
 
@@ -76,2 +73,3 @@ ## Plugins
  * [superagent-verbose-errors](https://github.com/jcoreio/superagent-verbose-errors) - include response body in error messages for failed requests
+ * [superagent-cheerio](https://github.com/mmmmmrob/superagent-cheerio) - include cheerio as `res.$` on html responses
 
@@ -78,0 +76,0 @@ Please prefix your plugin with `superagent-*` so that it can easily be found by others.

New alerts

No v1

Quality

Package is not semver >=1. This means it is not stable and does not support ^ ranges.

Found 1 instance in 1 package

Improved metrics

Total package byte prevSize

483682

increased by11.55%

Lines of code

5033

increased by0.94%

Worsened metrics

Number of low quality alerts

2

increased by100%

Number of lines in readme file

139

decreased by-1.42%

Dependency changes

• Updateddebug@^4.1.0

• Updatedform-data@^2.3.3

• Updatedmime@^2.4.0

• Updatedqs@^6.6.0

• Updatedreadable-stream@^3.0.6