got

Got version 9 is a massive release! Many new awesome features and we have pretty much fixed all the open issues regarding Got bugs on the issue tracker.

Got is a human-friendly and powerful HTTP request library for Node.js

Breaking changes

• Requires Node.js 8. You might ask, why not follow the Node.js LTS cycle and target Node.js 6. In short, async/await and WHATWG URL, which enabled us to simplify the codebase and reduce the dependency-tree considerably. Got v8 is a stable release, and you can continue using that if you need to support Node.js 6.
• The retry functionality was rewritten to improve its reliability and to support retrying on HTTP status codes. Previously, it only retried on some network failures. https://github.com/sindresorhus/got/commit/98b566444c9dd103af14281ace61fe2bd17d4f49 The option was renamed from retries to retry and it now accepts either a number of retries or an object with the ability to specify the number of retries, HTTP status codes and methods to retry on, and a function to decide how to retry. See the docs for more. Migration: - { retries: 4 } → { retry: 4 } - { retries: () => { … } } → { retry: { retries: () => { … } } }
• Renamed the .canceled property to .isCanceled. https://github.com/sindresorhus/got/commit/00fdeea9395225f1ca0f25230f5dfcc4010e3af0
• Dropped support for the body option being an Array when form: true. https://github.com/sindresorhus/got/commit/dfe5b1cfd762d4ccf4bf53ef2c1c0b31500baa30 The built-in new URLSearchParams() API doesn't support this either and it's a weird use-case. If you need support for this, just don't set form: true and handle stringifying yourself.
• Got throws an error if .pipe() was called after the response has been emitted. This makes us sure you receive whole response in case flowing mode is on (#223).

Improvements

• Fewer dependencies and smaller install size!
  • Got v9:
  • Got v8:
  • Request (latest):
• The timeout option was rewritten to be more reliable and flexible. You can now set a timeout for every phase of the request if you want, or just for the whole request. That's up to you. https://github.com/sindresorhus/got/commit/da4f23699dead63f17b5e27f9cadd9e4cb95e9a9
• Added got.extend() which lets you easily create instances of Got with some options overridden. https://github.com/sindresorhus/got/commit/bc41a49f14f16374766bfe8f7f8ee59365794d9c
• Added got.create() which is a more advanced and powerful version of got.extend(). With this API, you can create your own niche-specific instance of Got, for example, an HTTP-client for GitHub. https://github.com/sindresorhus/got/commit/bc41a49f14f16374766bfe8f7f8ee59365794d9c
• Added a beforeRequest hook. https://github.com/sindresorhus/got/commit/107756fc28dce579c521b15248f8bba730ae9e54
• Added request and response events to the Promise API. https://github.com/sindresorhus/got/commit/e86aad7cf17edb596d9ed362d610960529d505c6
• The content-length header is now also automatically set if the body option is set to a fs.createReadStream instance. https://github.com/sindresorhus/got/commit/6e7a4557d7568fed0677d146bdbd655d60d4fd92
• You can now remove the default user-agent header by passing in 'user-agent': null as a header. https://github.com/sindresorhus/got/commit/e473a26de25f8cc8fa34f5285f52aa01bb6065eb
• The body option can now be any kind of object, not just a plain object. https://github.com/sindresorhus/got/commit/7a49ce7b72e3c482fd66f1d3a30ec39098d8e618

Bug fixes

• Fixed a problem with the cache not working when using the query option. https://github.com/sindresorhus/got/commit/07a91cc94db41d4d797a46e45e1834ef65818a43
• Less unhandled errors (Hopefully none!). https://github.com/sindresorhus/got/commit/f621184d401329c1397ff5a033dfcea155218440
• Headers are now correctly proxied when you pipe got.stream(). https://github.com/sindresorhus/got/commit/83bc44c536f0c0ffb743e20e04bf569c51fa5d69
• Lots of more bug fixes.

Other

• 100% code coverage! Doing this caught a couple of bugs, so definitely worth doing even if 100% doesn't mean bug-free.
• The codebase was significantly refactored for better readability and maintainability. https://github.com/sindresorhus/got/commit/b54b68060c52a95621cae20132e90833dd999433

Team

Welcome @szmarczak and @brandon93s as maintainers 🎉

Special shoutout to @jstewmon for helping us with many of the above improvements and fixes 🙌

All changes

https://github.com/sindresorhus/got/compare/v8.3.2...v9.0.0

Fix Got throwing an error in some cases when trying to pipe one got.stream into another one. https://github.com/sindresorhus/got/commit/7ac705f831658c11b4a6fca6c6b21035ef8db3e8

• No longer overrides accept-encoding header if already provided. https://github.com/sindresorhus/got/commit/81f2537e6950643e986c09c182dbf29d5fcee8e2
• Sets content-length header when using form-data if not already set. https://github.com/sindresorhus/got/commit/de9514d897ca58ec70bbf82acc52e43b44cca870
• Now clears the progress interval if the socket has been destroyed. https://github.com/sindresorhus/got/commit/82763c8089596dcee5eaa7f57f5dbf8194842fe6

https://github.com/sindresorhus/got/compare/v8.3.0...v8.3.1

• Fixed socket connect memory leak. https://github.com/sindresorhus/got/commit/13d6b68ba02413374519f490d75741a427d705ad
• Prevented uncaught exception in some cases. https://github.com/sindresorhus/got/commit/43b51ba661140b102b7e243748d683dd39620631
• No longer continues the request after cancelation. https://github.com/sindresorhus/got/commit/9a646a39e6761d0914694f9d97bf332b06fdb8f5

https://github.com/sindresorhus/got/compare/v8.2.0...v8.3.0

No longer sets the default accept-encoding: gzip,deflate header if the decompress option is false.

https://github.com/sindresorhus/got/compare/v8.1.0...v8.2.0

• Add throwHttpErrors option. https://github.com/sindresorhus/got/commit/5a8894363172f1d39761447b93e0496b363782f0
• Allow calling of got.stream via options. https://github.com/sindresorhus/got/commit/b26c51e50f1657b702cb738561239654f5a4cbd9

https://github.com/sindresorhus/got/compare/v8.0.3...v8.1.0

• Fix browser usage. https://github.com/sindresorhus/got/commit/30c39bc1c3042a80ed3f6752677e0ab42cb1ca98
• Validate that url is UTF-8 encoded. https://github.com/sindresorhus/got/commit/4f5e6bfc8f4ed83b3e2c4c03fe20ea706543cfc9

https://github.com/sindresorhus/got/compare/v8.0.1...v8.0.2

• Correctly forwards stream errors. https://github.com/sindresorhus/got/commit/974473aadb2f43a7feacfd0e9246af8690ac016e
• Fix the request not aborting if the connection cannot be established and the timeout expires. https://github.com/sindresorhus/got/commit/98d226cff2935ab4d3c59cc1259acfa819765c76

https://github.com/sindresorhus/got/compare/v8.0.0...v8.0.1

• Added a powerful cache option. https://github.com/sindresorhus/got/commit/3c7920507fae88a5f53d0640b5116fa34a5ed829 (Thanks to @lukechilds ✨)
• Added download/upload progress events. https://github.com/sindresorhus/got/commit/be7b80252a7a678533b51d59bb7e11e9f317aced (Thanks to @vadimdemedes 🌟)
• Support for an object in the agent option. https://github.com/sindresorhus/got/commit/b9bf2e6bfcb0ccdb8761a4ce1b04e80a422234de
• [Breaking change] Uses HTTPS for protocol-less URLs (Previously it defaulted to http). https://github.com/sindresorhus/got/commit/ae1a0fedf202ac2adcac8f2d3e0d2ef40fe52d37
• Excludes passed headers with values null or undefined. https://github.com/sindresorhus/got/commit/c5e2f8d456c72dd5ce6acf73a12a80c700a26c83
• Fixed some memory leaks. https://github.com/sindresorhus/got/commit/0c5e44ce3cdb0e274fcb0e3d68cd9df297baf1ce https://github.com/sindresorhus/got/commit/98a714462c3e7b901454b3cb9975b1c4d974c4ca
• [Potentially breaking change] Uses statusMessage returned by endpoint. https://github.com/sindresorhus/got/commit/01c26364d9e34c60cf0cf81e331271ee4fc11d1a
• [Breaking change] Made the useElectron option false by default. https://github.com/sindresorhus/got/commit/33cbb6ffcf4cf9d8a735531fcc9ca81b4196efd4
• Exposed got.CancelError. https://github.com/sindresorhus/got/commit/b55f79e99d11d11d438f64dd8499dcee964d1c5d
• Fixed .cancel() when timeout exists. https://github.com/sindresorhus/got/commit/e31282dfd3402e7581bc7921746a62b35e9a8a31

https://github.com/sindresorhus/got/compare/v7.1.0...v8.0.0

• Added decompress option. https://github.com/sindresorhus/got/commit/f9d19e333413396a40328f28fd56b0e9fa26d5ed
• Support Array with the json option. https://github.com/sindresorhus/got/commit/1cf2bbf8cf1d26a4449171a4bbb689310dc9036b
• Fixed a bug with the Unix address parser. https://github.com/sindresorhus/got/commit/c0c6bcf1acb7132356d5fdddcf757466071799f4
• Worked around an issue with New Relic and Promise subclasses. https://github.com/sindresorhus/p-cancelable/commit/fe1fb8ede911846b428ecd7deb8e8c895c1ca165

https://github.com/sindresorhus/got/compare/v7.0.0...v7.1.0

Breaking changes

• Changes stringifying options behavior. https://github.com/sindresorhus/got/commit/51a3eafbdfa2e98e36a6231cd16c80ca16b6523b Setting the body option to be an object to stringify is no longer possible without setting either the form option for URL encoding or the json option for JSON encoding. Previously, Got would use URL encoding by default, now it will throw an error. Since the json option also means Got will decode a JSON response for you, setting both options to true will encode the request as URL and decode the response as JSON.
• Now also redirects on 307, 308, 303 responses. https://github.com/sindresorhus/got/commit/b45896aa4ec7a0ed0472a2a2436b6430099431b5
• The timeout option now applies to the whole request and we added ability to control the timeout of the individual phases. https://github.com/sindresorhus/got/commit/7964f2cdef36d98d498d7cc2dfe811c5291aaaf5

Highlights

• Added ability to cancel in-progress requests! https://github.com/sindresorhus/got/commit/9ef7a5aab9f989a8df2d867fa3fc6015eece8b86
• Added WHATWG URL support. https://github.com/sindresorhus/got/commit/f501fc2c7c6667dcd36d13384752b0d8b507bbdc
• Improve request retries by reducing the number of retries and making delays shorter. https://github.com/sindresorhus/got/commit/14d0859261aec38a73b0d30b5a350127b9e82ab6
• Only throws ParseError when parsing fails on 2xx responses. https://github.com/sindresorhus/got/commit/c86706bd23277ba033abefaf92a9c8fa69f78eee
• No longer throws HTTPError on 304 responses. https://github.com/sindresorhus/got/commit/7b12b7582d71abc652013d3b967473a776abf481
• Added protocol property to errors. https://github.com/sindresorhus/got/commit/919703cd8e9ba944753457d7f6b0ca4ecd94748d
• Added url property to errors. https://github.com/sindresorhus/got/commit/a287f8ec8a6498d9d5e1037255b36946f5c0c97b
• Includes response headers in errors, and redirect URLs in errors and the response. https://github.com/sindresorhus/got/commit/8b4d06ef31942721157d437f4135fc84535ba7ba
• Improve use in Electron. https://github.com/sindresorhus/got/commit/213057084cc4de325a829c82aae50d55b4f73c7d https://github.com/sindresorhus/got/commit/6fc1902805bae0791ee36895d351823248da9d07

All changes

https://github.com/sindresorhus/got/compare/v6.7.1...v7.0.0

This minor release fixes timeout behaviour to correspond with readme:

Milliseconds to wait for a server to send response headers before aborting request with ETIMEDOUT error.

Before this release ESOCKTIMEDOUT can be thrown (which can lead to false-positive errors for keep-alive sockets).

• Add requestUrl to response in streaming mode (#230)
• new Buffer() => Buffer.from() 5888ca7aa1ca982caac27e7796e225f70ded68a4
• Add url to response (#236)
• timed-out updated to ^3.0.0

• Add a redirect url property to the response object (#191)
• Add a requestUrl property to the response object (#205)
• ⬆️ get-stream bumped to ^2.3.0 – which fixes some nasty encoding bugs
• Fix location encoding (#214)
• Detect formdata body and set content-type header (#220)
• ⬆️ unzip-response bumped to ^2.0.1 – which fixes unexpected EOF error
• Allow non-plain object as request body (#217)

Changes

https://github.com/sindresorhus/got/compare/v6.3.0...v6.5.0

followRedirect option

This option disables following redirects and got will not treat them as errors:

const res = await got(`google.com`, {followRedirect: false});
res.statusCode === 302; // true

By default this option is true, so no major changes in code are needed.

Changes

https://github.com/sindresorhus/got/compare/v6.2.0...v6.3.0

• 26a499c0332ae673c89ca6bb680cf04e11965a66 statusCode and statusMessage added to ParseError object

• 45a636c6c22c2f7c9ffc14c78b8679d23485f9d2 fixes errors on parsing empty JSON body
• f9078b6440eefd3a8ebf15ff07b61d2bc1b27b8b fixes default user-agent to be RFS complaint

• f9ef29a3fc91708e5c4635f0c2afa1b781fd39b8 fixes redirects with uppercased method option

Non-retrieable errors

In got@5 we introduced retries option, which (as name says) retry request on every Error. For most errors this was right thing to do, but in case ENETUNREACH and ENOTFOUND retries are pointless.

This version removes retries from such errors, so you will get instant error, when typo gets into configs.

Changes

https://github.com/sindresorhus/got/compare/v6.0.0...v6.1.0

Aiming on Node.js 4

This release drops Node.js 0.10/0.12 support, so we replaced lots of modules and reduce dependency tree more than twice (see PR overview). Module folder size reduced from 1.1 MB to 216 KB.

For older Node.js versions we will still maintain v5.x for critical bug-fixes.

Promises by default

Callback interface was replaced by Promises, because it is a better way to work with asynchronous operations and they can be used with yield/await nicely.

If you use callback before:

got('todomvc.com', (err, body) => {
    if (err) {
        console.log(err);
        return;
    }

    console.log(body);
});

You can rewrite it this way:

got('todomvc.com')
    .then(res => {
        console.log(res.body);
    })
    .catch(err => {
        console.log(err);
    });

You can read more about Promises in "ECMAScript 6 promises (2/2): the API" post and some caveats in "We have a problem with promises".

Update

$ npm install --save got@6

Changes

https://github.com/sindresorhus/got/compare/v5.3.0...v6.0.0

This is last release of 5.x branch (which compatible with old versions of Node.JS). In this release we pulled all fixes (only UTF in headers is not cherry-picked):

• Add url to response (#236)
• Add requestUrl to response in streaming mode (#230)
• Allow non-plain object as request body (#217)
• Fixed unexpected EOF when decompressing content
• Detect formdata body and set content-type header (#220)
• Add a requestUrl property to the response object (#205)
• Add redirect url to response object (#191)

🎃 Happy Halloween!

• 43a6ea5cdf8f22225df951e331f12934cc466b3c Missing exception in helper methods for stream mode.
• 436600f9db8cd3719a14a5d62d26f9d085182a80 Fixed piping response in response event for stream mode.

https://github.com/sindresorhus/got/compare/v5.3.0...v5.3.1

• 59aa1d3a1da88fe46a2e3fa85f4c194d3fa6b743 Error is passed to retries function as well
• da9fc07a590ecb3a92f3322f370269c1d5223d6e Unzipping HEAD requests is disabled

https://github.com/sindresorhus/got/compare/v5.2.0...v5.3.0

• 54bd6f5bbad9590be6ffc7baf004c381bf1ea7a9 default intervals between delays decreased - now they are around 1s, 2s, 4s, 8s, etc...
• a10a99e8ae6cfb84522795605ce0014877fb9f52 retries option accepts backoff function, for example you can:

// Constant delay of 10ms for 5 iterations
got('google.com', {
    retries: iter => iter < 5 && 10
});

// Infinity retries with constant delay
got('google.com', {
    retries: () => 10
});

https://github.com/sindresorhus/got/compare/v5.1.0...v5.2.0

• 5205e7260f6082fe567f505be4aa15249c2c74a5 body option now accepts Stream1 streams
• e45087ab049d5a0228c106fc0f84a5737ab762cd content-length and accept headers now can be falsy values ('' or 0 for example)
• dcc7de68152a5ca5c0d0e263b28258bf719feb43 response property is now non-enumerable in error object
• cf544592571f3fc944a8a1e74e468e2fe378e176 undefined value of code property in error removed

https://github.com/sindresorhus/got/compare/v5.0.0...v5.1.0

Retries

We added retries on network failures with noisy exponential backoff. By default got will try five times, before returning error.

Retries only applies to network errors (because network is not reliable). Requests with server errors, like 50x status codes, will not be retried.

You can disable them by passing 0 to retries option.

Update

$ npm install --save got@5

Highlights

• 0109725b7406e8b7005a4a435a0617179b1dc2da Reject promise on internal exception
• df26918b3d39ac803ecc5020c92e5a7d8c3d88b3 Catch callbacks in stream mode
• f9f2807e63635432ab175824859caa70e3c583aa Reduce size for browserify
• 066e6125e0c5da942650e67bd9b920c949718704 Remove response event on error (in stream mode) (#110)
• 62ff082deb41e711ae29c9e09ce173eef04390d6 Catch auth option passed in url string (#106)
• 6c59ce8b346e3171e9388c18d78ccc5f38a96c8e Add retries on network errors (#98)
• 9ffbbdf5aba98892519282ad7799a991c0b04483 Deferred response event
• 013a2b57f8d9d0417c89923ee93b0a8a4283cbdd

Changes

https://github.com/sindresorhus/got/compare/v4.2.0...v5.0.0

• e944467ed5e54ac37e19d924f17e7a1f93ebf01f improves error message on invalid JSON
• e0863dcce94783283350be863f5fff226ec90de8 enable errors in stream mode (#97)
• 3182234d0e91dca37f3b71d20696408c174c9137 allow requests via domain sockets

https://github.com/sindresorhus/got/compare/v4.1.1...v4.2.0

• bdc1bfb2b849bbb914c20520e12357df92be1e58 fixes crashes on RequestError in Promise mode

https://github.com/sindresorhus/got/compare/v4.1.0...v4.1.1

• 7bea9c4d33ca4bbc01b44e28d4aefca2d170c680 If body is a plain Object, it will be stringified and sent as application/x-www-form-urlencoded.

https://github.com/sindresorhus/got/compare/v4.0.0...v4.1.0

Major release with lots of new stuff! Enjoy!

Promise API

got without callback now returns a promise instead of a stream. The stream API now lives under stream property (look at the end of section).

got('todomvc.com')
    .then(function (res) {
        console.log(res.body);
    })
    .catch(function (err) {
        console.error(err.response.body);
    });

In resolve handler you receive a http.response object with body as additional property.

In reject handler we provide an Error object. Unless Error type is RequestError, it will have response property with body property.

This API will be a huge advantage with co and Generators:

var co = require('co');

co(function * () {
    try {
        var response = yield got('todomvc.com');
        console.log(response.body);
    } catch (err) {
        console.error(err);
    }
});

You can go even further with destructuring and await from ES7:

async function () {
    try {
        var {body} = await got('todomvc.com');
        console.log(body);
    } catch (err) {
        console.error(err);
    }
}

Stream support is preserved, but now under the streams property:

got.stream('todomvc.com').pipe(process.stdout);

New Errors

Before 4.0.0 got had one Error class (GotError) with nested stack traces and custom error messages. This was a nice concept, but in production use some edge cases popped out:

• Error stacks are too long.
• Relevant information often were in one or two levels deep (eg. error.nested.nested).
• Errors message are hard to parse for url.

So we decided to review Errors in new version. In 4.0.0 got now have multiple Error classes for different situations: RequestError, ReadError, ParseError, HTTPError and MaxRedirectsError.

In addition to message and code properties from the original error, the new errors types also provide additional properties (host, hostname, path and method) for logging and debugging.

Infinity-agent removed

Custom agent was removed. This returns the ability to configure or replace global Agent, but also returns low maxSockets value in NodeJS 0.10.x. To fix this you can add this lines at the top of your app (not in reusable modules!):

require('http').globalAgent.maxSockets = Infinity;
require('https').globalAgent.maxSockets = Infinity;

Changes

https://github.com/sindresorhus/got/compare/v3.3.1...v4.0.0

• 312c80d82cd0472d009914fe8ffeebf06637e9c3 Don't parse JSON on 204 responses. #78
• 79f1390727dc2845969d1361fbf71c8975e5e3f0 Emit response event only on final request. #75
• b9c33aa64e6c8bf38201714d114579b3040645f6 Reselect agent on redirect from HTTP to HTTPS. #80

https://github.com/sindresorhus/got/compare/v3.3.0...v3.3.1

• 87d98e1f46103044b2152886435a1b97203add32 Added content-length header in requests with body.
• d7a66baac7bb3c0915b921997e401adf4718baaf Fallback on pathname option, if no path is present.

https://github.com/sindresorhus/got/compare/v3.2.0...v3.3.0

json option now sets Accept header to application/json (if it was not specified in headers)

https://github.com/sindresorhus/got/compare/v3.1.0...v3.2.0

error event now have additional body and response arguments in callback:

got('http://giggle.com')
    .on('error', function (error, body, response) {
        console.log(error, body, response);
    });

https://github.com/sindresorhus/got/compare/v3.0.0...v3.1.0

Changes

52490b2e88f263ab8abfb9498cb65575f3a15b01 New redirect event

This event fired before any redirect with response and nextOptions objects. You can access cookies and store them to be passed with next request in nextOptions.

got('cookie.com')
    .on('redirect', function (res, nextOptions) {
        nextOptions.headers.cookie = cookie(res);
    });

Breaking changes

2302a1e6e584f0b4a64bc6c0b16c72c645cd3cb7 Redirects enabled only for GET and HEAD methods

As rfc2616 HTTP 1.1 says:

If the 302 status code is received in response to a request other than GET or HEAD, the user agent MUST NOT automatically redirect the request unless it can be confirmed by the user, since this might change the conditions under which the request was issued.

Now got will not auto-redirect you with unsafe methods (like POST or DELETE), which can cause lots of troubles.

https://github.com/sindresorhus/got/compare/v2.9.0...v3.0.0

Validation

• url now throws error if not string or object 6b015692aa9dd42f69085c24be5e4bdf450f22de
• Nice error on wrong body option type a0913bc13c337c03ae9312fe4d851e9a367885aa

Options

• url now accepts http.request options as first argument 47da1181a52501fd30a14ddb43f576043d2bc711
• query option added 53df1ca251fbc0299916d3309ff53df065e97fbe

https://github.com/sindresorhus/got/compare/v2.8.0...v2.9.0

• Don't mutate the user-supplied options object ae73837301b2b50664e732d2b5bf93847b2b4cb3
• infinity-agent updated to 2.0.0 - which uses backported Agent from Node core c06d741131cd71a0cc9ca38a960ef5469cc3c1ce
  • Every request (in Node 0.10) will now have Connection: close header instead of Connection: keep-alive. maxSockets is now Infinity always - if you want different value, pass null or new Agent instance.

https://github.com/sindresorhus/got/compare/v2.7.2...v2.8.0

Fixed absent nested error on parse error of response.

https://github.com/sindresorhus/got/compare/v2.7.1...v2.7.2