feat: option to change http options globally

docs/README.md

@@ -445,12 +445,13 @@ Performs Dynamic Client Read Request to retrieve a Client instance.
 
 <!-- TOC Customizing START -->
 - [Customizing HTTP requests](#customizing-http-requests)
+- [Customizing individual HTTP requests](#customizing-individual-http-requests)
 - [Customizing clock skew tolerance](#customizing-clock-skew-tolerance)
 <!-- TOC Customizing END -->
 
 ---
 
-#### Customizing HTTP Requests
+#### Customizing HTTP requests
 
 The following are default [`got`][got-library] request
 [options](https://github.com/sindresorhus/got/tree/v9.6.0#options) that openid-client sets for all
@@ -466,7 +467,21 @@ const DEFAULT_HTTP_OPTIONS = {
 };
 ```
 
-You can change these options by assigning a function to
+You may change these global options like so:
+
+```js
+const { custom } = require('openid-client');
+
+custom.setHttpOptionsDefaults({
+  timeout: 5000,
+});
+```
+
+This is meant to change global request options such as `timeout` or the default `User-Agent` header.
+
+#### Customizing individual HTTP requests
+
+You change options on a per-request basis by assigning a function to
 
 - `Issuer` constructor to override the following request's options
   - discovery
@@ -481,7 +496,7 @@ You can change these options by assigning a function to
   - introspection endpoint requests
   - revocation endpoint requests
 
-This function will then be called before executing each and every request.
+This function will then be called before executing each and every request on the instance or constructor.
 
 ```js
 const { custom } = require('openid-client');
@@ -492,6 +507,9 @@ client[custom.http_options] = function (options) {
 }
 ```
 
+This is meant to change request options on per-request basis should there be a specific IdP quirk
+you need to work around, e.g. adding custom headers or body payload parameters.
+
 <details>
   <summary><em><strong>Example</strong></em> (Click to expand) providing mutual-TLS client certificate and key</summary>
 

lib/helpers/request.js

@@ -1,20 +1,26 @@
-const got = require('got');
+const Got = require('got');
 const { defaultsDeep } = require('lodash');
 
 const pkg = require('../../package.json');
 
 const isAbsoluteUrl = require('./is_absolute_url');
 const { HTTP_OPTIONS } = require('./consts');
 
-const USER_AGENT = `${pkg.name}/${pkg.version} (${pkg.homepage})`;
+let DEFAULT_HTTP_OPTIONS;
+let got;
 
-const DEFAULT_HTTP_OPTIONS = {
+const setDefaults = (options) => {
+  DEFAULT_HTTP_OPTIONS = defaultsDeep(options, DEFAULT_HTTP_OPTIONS);
+  got = Got.extend(DEFAULT_HTTP_OPTIONS);
+};
+
+setDefaults({
   followRedirect: false,
-  headers: { 'User-Agent': USER_AGENT },
+  headers: { 'User-Agent': `${pkg.name}/${pkg.version} (${pkg.homepage})` },
   retry: 0,
   timeout: 2500,
   throwHttpErrors: false,
-};
+});
 
 module.exports = function request(options, { mTLS = false } = {}) {
   const { url } = options;
@@ -24,11 +30,13 @@ module.exports = function request(options, { mTLS = false } = {}) {
   if (optsFn) {
     opts = optsFn.call(this, defaultsDeep(options, DEFAULT_HTTP_OPTIONS));
   } else {
-    opts = defaultsDeep(options, DEFAULT_HTTP_OPTIONS);
+    opts = options;
   }
 
   if (mTLS && (!opts.key || !opts.cert)) {
     throw new TypeError('mutual-TLS certificate and key not set');
   }
   return got(opts);
 };
+
+module.exports.setDefaults = setDefaults;

lib/index.js

@@ -5,6 +5,7 @@ const Strategy = require('./passport_strategy');
 const TokenSet = require('./token_set');
 const { CLOCK_TOLERANCE, HTTP_OPTIONS } = require('./helpers/consts');
 const generators = require('./helpers/generators');
+const { setDefaults } = require('./helpers/request');
 
 module.exports = {
   Issuer,
@@ -16,6 +17,7 @@ module.exports = {
     RPError,
   },
   custom: {
+    setHttpOptionsDefaults: setDefaults,
     http_options: HTTP_OPTIONS,
     clock_tolerance: CLOCK_TOLERANCE,
   },