Skip to content

Commit

Permalink
feat: add experimental customize fetch option
Browse files Browse the repository at this point in the history
closes #94
  • Loading branch information
panva committed Jan 10, 2024
1 parent a5fe73c commit e98c1aa
Show file tree
Hide file tree
Showing 14 changed files with 393 additions and 60 deletions.
1 change: 1 addition & 0 deletions docs/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -174,6 +174,7 @@
- [clockTolerance](variables/clockTolerance.md)
- [expectNoNonce](variables/expectNoNonce.md)
- [expectNoState](variables/expectNoState.md)
- [experimentalCustomFetch](variables/experimentalCustomFetch.md)
- [skipAuthTimeCheck](variables/skipAuthTimeCheck.md)
- [skipStateCheck](variables/skipStateCheck.md)
- [skipSubjectCheck](variables/skipSubjectCheck.md)
Expand Down
12 changes: 12 additions & 0 deletions docs/interfaces/ClientCredentialsGrantRequestOptions.md
Original file line number Diff line number Diff line change
Expand Up @@ -7,6 +7,7 @@
### Properties

- [DPoP](ClientCredentialsGrantRequestOptions.md#dpop)
- [[experimentalCustomFetch]](ClientCredentialsGrantRequestOptions.md#[experimentalcustomfetch])
- [clientPrivateKey](ClientCredentialsGrantRequestOptions.md#clientprivatekey)
- [headers](ClientCredentialsGrantRequestOptions.md#headers)
- [signal](ClientCredentialsGrantRequestOptions.md#signal)
Expand All @@ -21,6 +22,17 @@ DPoP-related options.

___

### [experimentalCustomFetch]

`Optional` **[experimentalCustomFetch]**: (`input`: `RequestInfo` \| [`URL`]( https://developer.mozilla.org/docs/Web/API/URL ), `init?`: `RequestInit`) => [`Promise`]( https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Promise )\<[`Response`]( https://developer.mozilla.org/docs/Web/API/Response )\>

This is an experimental feature, it is not subject to semantic versioning rules. Non-backward
compatible changes or removal may occur in any future release.

See [experimentalCustomFetch](../variables/experimentalCustomFetch.md) for its documentation.

___

### clientPrivateKey

`Optional` **clientPrivateKey**: [`CryptoKey`]( https://developer.mozilla.org/docs/Web/API/CryptoKey ) \| [`PrivateKey`](PrivateKey.md)
Expand Down
12 changes: 12 additions & 0 deletions docs/interfaces/DeviceAuthorizationRequestOptions.md
Original file line number Diff line number Diff line change
Expand Up @@ -6,12 +6,24 @@

### Properties

- [[experimentalCustomFetch]](DeviceAuthorizationRequestOptions.md#[experimentalcustomfetch])
- [clientPrivateKey](DeviceAuthorizationRequestOptions.md#clientprivatekey)
- [headers](DeviceAuthorizationRequestOptions.md#headers)
- [signal](DeviceAuthorizationRequestOptions.md#signal)

## Properties

### [experimentalCustomFetch]

`Optional` **[experimentalCustomFetch]**: (`input`: `RequestInfo` \| [`URL`]( https://developer.mozilla.org/docs/Web/API/URL ), `init?`: `RequestInit`) => [`Promise`]( https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Promise )\<[`Response`]( https://developer.mozilla.org/docs/Web/API/Response )\>

This is an experimental feature, it is not subject to semantic versioning rules. Non-backward
compatible changes or removal may occur in any future release.

See [experimentalCustomFetch](../variables/experimentalCustomFetch.md) for its documentation.

___

### clientPrivateKey

`Optional` **clientPrivateKey**: [`CryptoKey`]( https://developer.mozilla.org/docs/Web/API/CryptoKey ) \| [`PrivateKey`](PrivateKey.md)
Expand Down
12 changes: 12 additions & 0 deletions docs/interfaces/DiscoveryRequestOptions.md
Original file line number Diff line number Diff line change
Expand Up @@ -6,12 +6,24 @@

### Properties

- [[experimentalCustomFetch]](DiscoveryRequestOptions.md#[experimentalcustomfetch])
- [algorithm](DiscoveryRequestOptions.md#algorithm)
- [headers](DiscoveryRequestOptions.md#headers)
- [signal](DiscoveryRequestOptions.md#signal)

## Properties

### [experimentalCustomFetch]

`Optional` **[experimentalCustomFetch]**: (`input`: `RequestInfo` \| [`URL`]( https://developer.mozilla.org/docs/Web/API/URL ), `init?`: `RequestInit`) => [`Promise`]( https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Promise )\<[`Response`]( https://developer.mozilla.org/docs/Web/API/Response )\>

This is an experimental feature, it is not subject to semantic versioning rules. Non-backward
compatible changes or removal may occur in any future release.

See [experimentalCustomFetch](../variables/experimentalCustomFetch.md) for its documentation.

___

### algorithm

`Optional` **algorithm**: ``"oidc"`` \| ``"oauth2"``
Expand Down
12 changes: 12 additions & 0 deletions docs/interfaces/HttpRequestOptions.md
Original file line number Diff line number Diff line change
Expand Up @@ -6,11 +6,23 @@

### Properties

- [[experimentalCustomFetch]](HttpRequestOptions.md#[experimentalcustomfetch])
- [headers](HttpRequestOptions.md#headers)
- [signal](HttpRequestOptions.md#signal)

## Properties

### [experimentalCustomFetch]

`Optional` **[experimentalCustomFetch]**: (`input`: `RequestInfo` \| [`URL`]( https://developer.mozilla.org/docs/Web/API/URL ), `init?`: `RequestInit`) => [`Promise`]( https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Promise )\<[`Response`]( https://developer.mozilla.org/docs/Web/API/Response )\>

This is an experimental feature, it is not subject to semantic versioning rules. Non-backward
compatible changes or removal may occur in any future release.

See [experimentalCustomFetch](../variables/experimentalCustomFetch.md) for its documentation.

___

### headers

`Optional` **headers**: [`Record`]( https://www.typescriptlang.org/docs/handbook/utility-types.html#recordkeys-type )\<`string`, `string`\> \| [`string`, `string`][] \| [`Headers`]( https://developer.mozilla.org/docs/Web/API/Headers )
Expand Down
12 changes: 12 additions & 0 deletions docs/interfaces/IntrospectionRequestOptions.md
Original file line number Diff line number Diff line change
Expand Up @@ -6,6 +6,7 @@

### Properties

- [[experimentalCustomFetch]](IntrospectionRequestOptions.md#[experimentalcustomfetch])
- [additionalParameters](IntrospectionRequestOptions.md#additionalparameters)
- [clientPrivateKey](IntrospectionRequestOptions.md#clientprivatekey)
- [headers](IntrospectionRequestOptions.md#headers)
Expand All @@ -14,6 +15,17 @@

## Properties

### [experimentalCustomFetch]

`Optional` **[experimentalCustomFetch]**: (`input`: `RequestInfo` \| [`URL`]( https://developer.mozilla.org/docs/Web/API/URL ), `init?`: `RequestInit`) => [`Promise`]( https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Promise )\<[`Response`]( https://developer.mozilla.org/docs/Web/API/Response )\>

This is an experimental feature, it is not subject to semantic versioning rules. Non-backward
compatible changes or removal may occur in any future release.

See [experimentalCustomFetch](../variables/experimentalCustomFetch.md) for its documentation.

___

### additionalParameters

`Optional` **additionalParameters**: [`Record`]( https://www.typescriptlang.org/docs/handbook/utility-types.html#recordkeys-type )\<`string`, `string`\> \| [`URLSearchParams`]( https://developer.mozilla.org/docs/Web/API/URLSearchParams ) \| `string`[][]
Expand Down
12 changes: 12 additions & 0 deletions docs/interfaces/ProtectedResourceRequestOptions.md
Original file line number Diff line number Diff line change
Expand Up @@ -8,6 +8,7 @@

- [DPoP](ProtectedResourceRequestOptions.md#dpop)
- [[clockSkew]](ProtectedResourceRequestOptions.md#[clockskew])
- [[experimentalCustomFetch]](ProtectedResourceRequestOptions.md#[experimentalcustomfetch])
- [signal](ProtectedResourceRequestOptions.md#signal)

## Properties
Expand All @@ -32,6 +33,17 @@ option is also used.

___

### [experimentalCustomFetch]

`Optional` **[experimentalCustomFetch]**: (`input`: `RequestInfo` \| [`URL`]( https://developer.mozilla.org/docs/Web/API/URL ), `init?`: `RequestInit`) => [`Promise`]( https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Promise )\<[`Response`]( https://developer.mozilla.org/docs/Web/API/Response )\>

This is an experimental feature, it is not subject to semantic versioning rules. Non-backward
compatible changes or removal may occur in any future release.

See [experimentalCustomFetch](../variables/experimentalCustomFetch.md) for its documentation.

___

### signal

`Optional` **signal**: [`AbortSignal`]( https://developer.mozilla.org/docs/Web/API/AbortSignal ) \| () => [`AbortSignal`]( https://developer.mozilla.org/docs/Web/API/AbortSignal )
Expand Down
12 changes: 12 additions & 0 deletions docs/interfaces/PushedAuthorizationRequestOptions.md
Original file line number Diff line number Diff line change
Expand Up @@ -7,6 +7,7 @@
### Properties

- [DPoP](PushedAuthorizationRequestOptions.md#dpop)
- [[experimentalCustomFetch]](PushedAuthorizationRequestOptions.md#[experimentalcustomfetch])
- [clientPrivateKey](PushedAuthorizationRequestOptions.md#clientprivatekey)
- [headers](PushedAuthorizationRequestOptions.md#headers)
- [signal](PushedAuthorizationRequestOptions.md#signal)
Expand All @@ -21,6 +22,17 @@ DPoP-related options.

___

### [experimentalCustomFetch]

`Optional` **[experimentalCustomFetch]**: (`input`: `RequestInfo` \| [`URL`]( https://developer.mozilla.org/docs/Web/API/URL ), `init?`: `RequestInit`) => [`Promise`]( https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Promise )\<[`Response`]( https://developer.mozilla.org/docs/Web/API/Response )\>

This is an experimental feature, it is not subject to semantic versioning rules. Non-backward
compatible changes or removal may occur in any future release.

See [experimentalCustomFetch](../variables/experimentalCustomFetch.md) for its documentation.

___

### clientPrivateKey

`Optional` **clientPrivateKey**: [`CryptoKey`]( https://developer.mozilla.org/docs/Web/API/CryptoKey ) \| [`PrivateKey`](PrivateKey.md)
Expand Down
12 changes: 12 additions & 0 deletions docs/interfaces/RevocationRequestOptions.md
Original file line number Diff line number Diff line change
Expand Up @@ -6,13 +6,25 @@

### Properties

- [[experimentalCustomFetch]](RevocationRequestOptions.md#[experimentalcustomfetch])
- [additionalParameters](RevocationRequestOptions.md#additionalparameters)
- [clientPrivateKey](RevocationRequestOptions.md#clientprivatekey)
- [headers](RevocationRequestOptions.md#headers)
- [signal](RevocationRequestOptions.md#signal)

## Properties

### [experimentalCustomFetch]

`Optional` **[experimentalCustomFetch]**: (`input`: `RequestInfo` \| [`URL`]( https://developer.mozilla.org/docs/Web/API/URL ), `init?`: `RequestInit`) => [`Promise`]( https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Promise )\<[`Response`]( https://developer.mozilla.org/docs/Web/API/Response )\>

This is an experimental feature, it is not subject to semantic versioning rules. Non-backward
compatible changes or removal may occur in any future release.

See [experimentalCustomFetch](../variables/experimentalCustomFetch.md) for its documentation.

___

### additionalParameters

`Optional` **additionalParameters**: [`Record`]( https://www.typescriptlang.org/docs/handbook/utility-types.html#recordkeys-type )\<`string`, `string`\> \| [`URLSearchParams`]( https://developer.mozilla.org/docs/Web/API/URLSearchParams ) \| `string`[][]
Expand Down
12 changes: 12 additions & 0 deletions docs/interfaces/TokenEndpointRequestOptions.md
Original file line number Diff line number Diff line change
Expand Up @@ -7,6 +7,7 @@
### Properties

- [DPoP](TokenEndpointRequestOptions.md#dpop)
- [[experimentalCustomFetch]](TokenEndpointRequestOptions.md#[experimentalcustomfetch])
- [additionalParameters](TokenEndpointRequestOptions.md#additionalparameters)
- [clientPrivateKey](TokenEndpointRequestOptions.md#clientprivatekey)
- [headers](TokenEndpointRequestOptions.md#headers)
Expand All @@ -22,6 +23,17 @@ DPoP-related options.

___

### [experimentalCustomFetch]

`Optional` **[experimentalCustomFetch]**: (`input`: `RequestInfo` \| [`URL`]( https://developer.mozilla.org/docs/Web/API/URL ), `init?`: `RequestInit`) => [`Promise`]( https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Promise )\<[`Response`]( https://developer.mozilla.org/docs/Web/API/Response )\>

This is an experimental feature, it is not subject to semantic versioning rules. Non-backward
compatible changes or removal may occur in any future release.

See [experimentalCustomFetch](../variables/experimentalCustomFetch.md) for its documentation.

___

### additionalParameters

`Optional` **additionalParameters**: [`Record`]( https://www.typescriptlang.org/docs/handbook/utility-types.html#recordkeys-type )\<`string`, `string`\> \| [`URLSearchParams`]( https://developer.mozilla.org/docs/Web/API/URLSearchParams ) \| `string`[][]
Expand Down
12 changes: 12 additions & 0 deletions docs/interfaces/UserInfoRequestOptions.md
Original file line number Diff line number Diff line change
Expand Up @@ -7,6 +7,7 @@
### Properties

- [DPoP](UserInfoRequestOptions.md#dpop)
- [[experimentalCustomFetch]](UserInfoRequestOptions.md#[experimentalcustomfetch])
- [headers](UserInfoRequestOptions.md#headers)
- [signal](UserInfoRequestOptions.md#signal)

Expand All @@ -20,6 +21,17 @@ DPoP-related options.

___

### [experimentalCustomFetch]

`Optional` **[experimentalCustomFetch]**: (`input`: `RequestInfo` \| [`URL`]( https://developer.mozilla.org/docs/Web/API/URL ), `init?`: `RequestInit`) => [`Promise`]( https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Promise )\<[`Response`]( https://developer.mozilla.org/docs/Web/API/Response )\>

This is an experimental feature, it is not subject to semantic versioning rules. Non-backward
compatible changes or removal may occur in any future release.

See [experimentalCustomFetch](../variables/experimentalCustomFetch.md) for its documentation.

___

### headers

`Optional` **headers**: [`Record`]( https://www.typescriptlang.org/docs/handbook/utility-types.html#recordkeys-type )\<`string`, `string`\> \| [`string`, `string`][] \| [`Headers`]( https://developer.mozilla.org/docs/Web/API/Headers )
Expand Down
90 changes: 90 additions & 0 deletions docs/variables/experimentalCustomFetch.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,90 @@
# Variable: experimentalCustomFetch

[💗 Help the project](https://github.com/sponsors/panva)

`Const` **experimentalCustomFetch**: typeof [`experimentalCustomFetch`](experimentalCustomFetch.md)

This is an experimental feature, it is not subject to semantic versioning rules. Non-backward
compatible changes or removal may occur in any future release.

When configured on an interface that extends [HttpRequestOptions](../interfaces/HttpRequestOptions.md), that's every `options`
parameter for functions that trigger HTTP Requests, this replaces the use of global fetch. As a
fetch replacement the arguments and expected return are the same as fetch.

In theory any module that claims to be compatible with the Fetch API can be used but your mileage
may vary. No workarounds to allow use of non-conform Responses will be considered.

If you only need to update the Request properties you do not need to use a Fetch API
module, just change what you need and pass it to globalThis.fetch just like this module would
normally do.

Its intended use cases are:

- Request/Response tracing and logging
- Custom caching strategies for responses of Authorization Server Metadata and JSON Web Key Set
(JWKS) endpoints
- Changing the Request properties like headers, body, credentials, mode before it is passed
to fetch

Known caveats:

- Expect Type-related issues when passing the inputs through to fetch-like modules, they hardly
ever get their typings inline with actual fetch, you should `@ts-expect-error` them.
- Returning self-constructed Response instances prohibits AS-signalled DPoP Nonce caching.

**`Example`**

Using [sindresorhus/ky](https://github.com/sindresorhus/ky) hooks feature for logging outgoing
requests and their responses.

```js
import ky from 'ky'
import { experimentalCustomFetch } from 'oauth4webapi'

// example use
await discoveryRequest(new URL('https://as.example.com'), {
[experimentalCustomFetch]: (...args) =>
ky(args[0], {
...args[1],
hooks: {
beforeRequest: [
(request) => {
logRequest(request)
},
],
beforeRetry: [
({ request, error, retryCount }) => {
logRetry(request, error, retryCount)
},
],
afterResponse: [
(request, _, response) => {
logResponse(request, response)
},
],
},
}),
})
```

**`Example`**

Using [nodejs/undici](https://github.com/nodejs/undici) for mocking.

```js
import * as undici from 'undici'
import { discoveryRequest, experimentalCustomFetch } from 'oauth4webapi'

const mockAgent = new undici.MockAgent()
mockAgent.disableNetConnect()
undici.setGlobalDispatcher(mockAgent)

// continue as per undici documentation
// https://github.com/nodejs/undici/blob/v6.2.1/docs/api/MockAgent.md#example---basic-mocked-request

// example use
await discoveryRequest(new URL('https://as.example.com'), {
// @ts-expect-error
[experimentalCustomFetch]: undici.fetch,
})
```

0 comments on commit e98c1aa

Please sign in to comment.