@passcod/faith 0.0.2 → 0.0.4

package/README.md

@@ -11,8 +11,8 @@ easily work around its limitations. The native fetch implementation, `undici`, e
 HTTP/1.1, and doesn't support HTTP/2+, among many other complaints.
 
 Fáith tries to bring a Node.js fetch that is closer to the browser's fetch, notably by having
-transparent support for HTTP/2 and HTTP/3, IPv6 and IPv4 using the "Happy Eyeballs" algorithm, an
-HTTP cache and a cookie jar, a DNS cache, and actual support for `half` and `full` duplex modes.
+transparent support for HTTP/2 and HTTP/3, IPv6 and IPv4 using the "Happy Eyeballs" algorithm, a
+DNS cache, an optional cookie jar, and your choice of two HTTP caches.
 
 ## Installation
 
@@ -31,7 +31,7 @@ async function example() {
   const response = await fetch('https://httpbin.org/get');
   console.log(response.status); // 200
   console.log(response.ok); // true
-  
+
   const data = response.json();
   console.log(data.url); // https://httpbin.org/get
 }
@@ -90,6 +90,7 @@ practice the `RequestInit` class does not exist in browsers or Node.js, and so t
 
 *A `Promise` that resolves to a `Response` object.*
 
+<!-- //full duplex mode is not yet implemented//
 In `half` duplex mode (the default), the promise resolves when the request body has been fully sent
 and the response headers have been received. In `full` duplex mode (supported by Fáith but not yet
 browsers), the promise resolves as soon as response headers have been received, even if the request
@@ -97,6 +98,7 @@ body has not yet finished sending. Most HTTP servers will not send response head
 finished receiving the body so this distinction doesn't matter, but some do, and it is possible to
 take advantage of this behaviour with `full` duplex mode for decreased latency in specific cases.
 You may even be able to vary the request body stream based on the response body stream.
+-->
 
 ## `Request`
 
@@ -118,7 +120,7 @@ then the value passed directly into `fetch()` is used.*
 
 Note that you can include options that Fáith does not support; they will simply be ignored.
 
-### `agent`
+### `FetchOptions.agent: Agent`
 
 This is custom to Fáith.
 
@@ -128,11 +130,11 @@ Notably an agent has a DNS cache, and may be configured to handle cookies and/or
 
 When not provided, a global default `Agent` is created on first use.
 
-### `attributionReporting`
+### `FetchOptions.attributionReporting`
 
 Fáith deliberately does not implement this.
 
-### `body`
+### `FetchOptions.body`
 
 *The request body contains content to send to the server, for example in a `POST` or `PUT` request.
 It is specified as an instance of any of the following types:*
@@ -144,23 +146,57 @@ It is specified as an instance of any of the following types:*
 - *`File`*
 - *`FormData`*
 - *`TypedArray`*
-- *`URLSearchParams`* Not yet implemented.
+- ~~*`URLSearchParams`*~~ Not yet implemented.
 - *`ReadableStream`* Note that Fáith currently reads this into memory before sending the request.
 
 *If `body` is a `ReadableStream`, the `duplex` option must also be set.*
 
-### `browsingTopics`
+### `FetchOptions.browsingTopics`
 
 Fáith deliberately does not implement this.
 
-### `cache`
+### `FetchOptions.cache`
 
-Fáith does not respect this option on the `RequestInit` dictionary. Instead, the option is present
-on `Agent` and applies to all requests made with that `Agent`.
+*The cache mode you want to use for the request. This may be any one of the following values:*
+
+- *`default`: The client looks in its HTTP cache for a response matching the request.*
+  - *If there is a match and it is fresh, it will be returned from the cache.*
+  - *If there is a match but it is stale, the client will make a conditional request to the remote
+    server. If the server indicates that the resource has not changed, it will be returned from the
+    cache. Otherwise the resource will be downloaded from the server and the cache will be updated.*
+  - *If there is no match, the client will make a normal request, and will update the cache with
+    the downloaded resource.*
+
+- *`no-store`: The client fetches the resource from the remote server without first looking in the
+  cache, and will not update the cache with the downloaded resource.*
+
+- *`reload`: The client fetches the resource from the remote server without first looking in the
+  cache, but then will update the cache with the downloaded resource.*
+
+- *`no-cache`: The client looks in its HTTP cache for a response matching the request.*
+  - *If there is a match, fresh or stale, the client will make a conditional request to the remote
+    server. If the server indicates that the resource has not changed, it will be returned from the
+    cache. Otherwise the resource will be downloaded from the server and the cache will be updated.*
+  - *If there is no match, the client will make a normal request, and will update the cache with
+    the downloaded resource.*
 
-### `credentials`
+- *`force-cache`: The client looks in its HTTP cache for a response matching the request.*
+  - *If there is a match, fresh or stale, it will be returned from the cache.*
+  - *If there is no match, the client will make a normal request, and will update the cache with
+    the downloaded resource.*
 
-*Controls whether or not the browser sends credentials with the request, as well as whether any
+- *`only-if-cached`: The client looks in its HTTP cache for a response matching the request.*
+  - *If there is a match, fresh or stale, it will be returned from the cache.*
+  - *If there is no match, a network error is returned.*
+
+- `ignore-rules`: Custom to Fáith. Overrides the check that determines if a response can be cached
+  to always return true on 200. Uses any response in the HTTP cache matching the request, not
+  paying attention to staleness. If there was no response, it creates a normal request and updates
+  the HTTP cache with the response.
+
+### `FetchOptions.credentials: string`
+
+*Controls whether or not the client sends credentials with the request, as well as whether any
 `Set-Cookie` response headers are respected. Credentials are cookies, ~~TLS client certificates,~~
 or authentication headers containing a username and password. This option may be any one of the
 following values:*
@@ -180,14 +216,14 @@ This is an upstream limitation.
 
 Defaults to `include` (browsers default to `same-origin`).
 
-### `duplex`
+### `FetchOptions.duplex: string`
 
 *Controls duplex behavior of the request. If this is present it must have the value `half`, meaning
 that Fáith will send the entire request before processing the response.*
 
 *This option must be present when `body` is a `ReadableStream`.*
 
-### `headers`
+### `FetchOptions.headers: Headers | object`
 
 *Any headers you want to add to your request, contained within a `Headers` object or an object
 literal whose keys are the names of headers and whose values are the header values.*
@@ -196,7 +232,7 @@ Fáith allows all request headers to be set (unlike browsers, which [forbid][1]
 
 [1]: https://developer.mozilla.org/en-US/docs/Glossary/Forbidden_request_header
 
-### `integrity`
+### `FetchOptions.integrity: string`
 
 Not implemented yet.
 
@@ -214,7 +250,7 @@ Fáith only checks the integrity when using `bytes()`, `json()`, `text()`, `arra
 Note that browsers will throw at the `fetch()` call when integrity fails, but Fáith will only throw
 when the above methods are called, as until then the body contents are not available.
 
-### `keepalive`
+### `FetchOptions.keepalive`
 
 Not supported.
 
@@ -223,41 +259,41 @@ single `Agent`, so subsequent requests to the same endpoint are faster until the
 times out. The `keepalive` option in browsers is instead a way to send a `fetch()` right before the
 page is unloaded, for tracking or analytics purposes. This concept does not exist in Node.js.
 
-### `method`
+### `FetchOptions.method: string`
 
 *The request method. Defaults to `GET`.*
 
-### `mode`
+### `FetchOptions.mode`
 
 Fáith deliberately does not implement this, as there is no CORS/origin.
 
-### `priority`
+### `FetchOptions.priority`
 
 Not supported.
 
-### `redirect`
+### `FetchOptions.redirect`
 
 Fáith does not respect this option on the `RequestInit` dictionary. Instead, the option is present
 on `Agent` and applies to all requests made with that `Agent`.
 
-### `referrer`
+### `FetchOptions.referrer`
 
 Fáith deliberately does not implement this, as there is no origin.
 
 However, Fáith does set the `Referer` header when redirecting automatically.
 
-### `referrerPolicy`
+### `FetchOptions.referrerPolicy`
 
 Fáith deliberately does not implement this, as there is no origin.
 
 However, Fáith does set the `Referer` header when redirecting automatically.
 
-### `signal`
+### `FetchOptions.signal: AbortSignal`
 
 *An `AbortSignal`. If this option is set, the request can be canceled by calling `abort()` on the
 corresponding `AbortController`.*
 
-### `timeout`
+### `FetchOptions.timeout: number`
 
 Custom to Fáith. Cancels the request after this many milliseconds.
 
@@ -273,7 +309,7 @@ response receipt.
 Fáith does not allow its `Response` object to be constructed. If you need to, you may use the
 `webResponse()` method to convert one into a Web API `Response` object; note the caveats.
 
-### `Response.body`
+### `Response.body: ReadableStream | null`
 
 *The `body` read-only property of the `Response` interface is a `ReadableStream` of the body
 contents,* or `null` for any actual HTTP response that has no body, such as `HEAD` requests and
@@ -282,7 +318,7 @@ contents,* or `null` for any actual HTTP response that has no body, such as `HEA
 Note that browsers currently do not return `null` for those responses, but the spec requires it.
 Fáith chooses to respect the spec rather than the browsers in this case.
 
-### `Response.bodyUsed`
+### `Response.bodyUsed: boolean`
 
 *The `bodyUsed` read-only property of the `Response` interface is a boolean value that indicates
 whether the body has been read yet.*
@@ -291,7 +327,7 @@ In Fáith, this indicates whether the body stream has ever been read from or can
 [in the spec](https://streams.spec.whatwg.org/#is-readable-stream-disturbed). Note that accessing
 the `.body` property counts as a read, even if you don't actually consume any bytes of content.
 
-### `Response.headers`
+### `Response.headers: Headers`
 
 *The `headers` read-only property of the `Response` interface contains the `Headers` object
 associated with the response.*
@@ -299,12 +335,27 @@ associated with the response.*
 Note that Fáith does not provide a custom `Headers` class; instead the Web API `Headers` structure
 is used directly and constructed by Fáith when needed.
 
-### `Response.ok`
+### `Response.ok: boolean`
 
 *The `ok` read-only property of the `Response` interface contains a boolean stating whether the
 response was successful (status in the range 200-299) or not.*
 
-### `Response.redirected`
+### `Response.peer: object`
+
+Custom to Fáith.
+
+The `peer` read-only property of the `Response` interface contains an object with information about
+the remote peer that sent this response:
+
+#### `Response.peer.address: string | null`
+
+The IP address and port of the peer, if available.
+
+#### `Response.peer.certificate: Buffer | null`
+
+When connected over HTTPS, this is the DER-encoded leaf certificate of the peer.
+
+### `Response.redirected: boolean`
 
 *The `redirected` read-only property of the `Response` interface indicates whether or not the
 response is the result of a request you made which was redirected.*
@@ -312,14 +363,12 @@ response is the result of a request you made which was redirected.*
 *Note that by the time you read this property, the redirect will already have happened, and you
 cannot prevent it by aborting the fetch at this point.*
 
-### `Response.status`
+### `Response.status: number`
 
 *The `status` read-only property of the `Response` interface contains the HTTP status codes of the
 response. For example, 200 for success, 404 if the resource could not be found.*
 
-*A value is `0` is returned for a response whose `type` is `opaque`, `opaqueredirect`, or `error`.*
-
-### `Response.statusText`
+### `Response.statusText: string`
 
 *The `statusText` read-only property of the `Response` interface contains the status message
 corresponding to the HTTP status code in `Response.status`. For example, this would be `OK` for a
@@ -329,58 +378,57 @@ In HTTP/1, servers can send custom status text. This is returned here. In HTTP/2
 status text is not supported at all, and the `statusText` property is either empty or simulated
 from well-known status codes.
 
-### `Response.type`
+### `Response.type: string`
 
 *The `type` read-only property of the `Response` interface contains the type of the response. The
 type determines whether scripts are able to access the response body and headers.*
 
 In Fáith, this is always set to `basic`.
 
-### `Response.url`
+### `Response.url: string`
 
 *The `url` read-only property of the `Response` interface contains the URL of the response. The
 value of the `url` property will be the final URL obtained after any redirects.*
 
-### `Response.version`
+### `Response.version: string`
 
 The `version` read-only property of the `Response` interface contains the HTTP version of the
 response. The value will be the final HTTP version after any redirects and protocol upgrades.
 
 This is custom to Fáith.
 
-### `Response.arrayBuffer()`
+### `Response.arrayBuffer(): Promise<ArrayBuffer>`
 
 *The `arrayBuffer()` method of the `Response` interface takes a `Response` stream and reads it to
 completion. It returns a promise that resolves with an `ArrayBuffer`.*
 
-### `Response.blob()`
+### `Response.blob(): Promise<Blob>`
 
 *The `blob()` method of the `Response` interface takes a `Response` stream and reads it to
 completion. It returns a promise that resolves with a `Blob`.*
 
 *The `type` of the `Blob` is set to the value of the `Content-Type` response header.*
 
-### `Response.bytes()`
+### `Response.bytes(): Promise<Buffer>`
 
 *The `bytes()` method of the `Response` interface takes a `Response` stream and reads it to
 completion. It returns a promise that resolves with a `Uint8Array`.*
 
 In Fáith, this returns a Node.js `Buffer`, which can be used as (and is a subclass of) a `Uint8Array`.
 
-### `Response.clone()`
+### `Response.clone(): Response`
 
 *The `clone()` method of the `Response` interface creates a clone of a response object, identical
 in every way, but stored in a different variable.*
 
-*`clone()` throws* an `Error` *if the response body has already been used.*
-
-(In-spec, this should throw a `TypeError`, but for technical reasons this is not possible with Fáith.)
+*`clone()` throws an error if the response body has already been used.*
 
-### `Response.formData()`
+### `Response.formData(): !`
 
-Fáith deliberately does not implement this.
+Fáith deliberately does not implement this. The method exists so the types work out, but it will
+always throw.
 
-### `Response.json()`
+### `Response.json(): Promise<unknown>`
 
 *The `json()` method of the `Response` interface takes a `Response` stream and reads it to
 completion. It returns a promise which resolves with the result of parsing the body text as
@@ -393,13 +441,13 @@ Further note that, at least in Fáith, this method first reads the entire respon
 and then parses that as JSON. This can use up to double the amount of memory. If you need more
 efficient access, consider handling the response body as a stream.
 
-### `Response.text()`
+### `Response.text(): Promise<string>`
 
 *The `text()` method of the `Response` interface takes a `Response` stream and reads it to
 completion. It returns a promise that resolves with a `String`. The response is always decoded
 using UTF-8.*
 
-### `Response.webResponse()`
+### `Response.webResponse(): globalThis.Response`
 
 This is entirely custom to Fáith. It returns a Web API `Response` instead of Fáith's custom
 `Response` class. However, it's not possible to construct a Web API `Response` that has all the
@@ -429,6 +477,8 @@ For this reason, and also because in browsers this behaviour is standard, **all*
 Fáith use an `Agent`. For `fetch()` calls that don't specify one explicitly, a global agent with
 default options is created on first use.
 
+There are a lot more options that could be exposed here; if you want one, open an issue.
+
 ### Syntax
 
 ```javascript
@@ -436,8 +486,45 @@ new Agent()
 new Agent(options)
 ```
 
-### `cache`
-### `cookies: bool`
+### `AgentOptions.cache: object`
+
+Settings related to the HTTP cache. This is a nested object.
+
+#### `AgentOptions.cache.store: string`
+
+Which cache store to use: either `disk` or `memory`.
+
+Default: none (cache disabled).
+
+#### `AgentOptions.cache.capacity: number`
+
+If `cache.store: "memory"`, the maximum amount of items stored.
+
+Default: 10_000.
+
+#### `AgentOptions.cache.mode: string`
+
+Default cache mode. This is the same as [`FetchOptions.cache`](#fetchoptionscache), and is used if
+no cache mode is set on a request.
+
+Default: `"default"`.
+
+#### `AgentOptions.cache.path: string`
+
+If `cache.store: "disk"`, then this is the path at which the cache data is. Must be writeable.
+
+Required if `cache.store: "disk"`.
+
+#### `AgentOptions.cache.shared: boolean`
+
+If `true`, then the response is evaluated from a perspective of a shared cache (i.e. `private` is
+not cacheable and `s-maxage` is respected). If `false`, then the response is evaluated from a
+perspective of a single-user cache (i.e. `private` is cacheable and `s-maxage` is ignored).
+`shared: true` is required for proxies and multi-user caches.
+
+Default: true.
+
+### `AgentOptions.cookies: bool`
 
 Enable a persistent cookie store for the agent. Cookies received in responses will be preserved and
 included in additional requests.
@@ -447,8 +534,36 @@ Default: `false`.
 You may use `agent.getCookie(url: string)` and `agent.addCookie(url: string, value: string)` to add
 and retrieve cookies from the store.
 
-### `dns`
-### `headers: Array<{ name: string, value: string, sensitive?: bool }>`
+### `AgentOptions.dns: object`
+
+Settings related to DNS. This is a nested object.
+
+#### `AgentOptions.dns.system: boolean`
+
+Use the system's DNS (via `getaddrinfo` or equivalent) rather than Fáith's own DNS client (based on
+[Hickory]). If you experience issues with DNS where Fáith does not work but e.g. curl or native
+fetch does, this should be your first port of call.
+
+Enabling this also disables Happy Eyeballs (for IPv6 / IPv4 best-effort resolution), the in-memory
+DNS cache, and may lead to worse performance even discounting the cache.
+
+Default: false.
+
+[Hickory]: https://hickory-dns.org/
+
+#### `AgentOptions.dns.overrides: Array<{ domain: string; addresses: string[] }>`
+
+Override DNS resolution for specific domains. This takes effect even with `dns.system: true`.
+
+Will throw if addresses are in invalid formats. You may provide a port number as part of the
+address, it will default to port 0 otherwise, which will select the conventional port for the
+protocol in use (e.g. 80 for plaintext HTTP). If the URL passed to `fetch()` has an explicit port
+number, that one will be used instead. Resolving a domain to an empty `addresses` array effectively
+blocks that domain from this agent.
+
+Default: no overrides.
+
+### `AgentOptions.headers: Array<{ name: string, value: string, sensitive?: bool }>`
 
 Sets the default headers for every request.
 
@@ -457,23 +572,123 @@ Sensitive headers (e.g. `Authorization`) should be marked.
 
 Default: none.
 
-### `http3`
-#### `congestion`
-### `pool`
-#### `maxIdlePerHost`
-#### `idleTimeout`
-### `redirect`
-### `retry`
-### `timeout`
-#### `connect`
-#### `read`
-#### `total`
-### `tls`
-#### `earlyData`
-#### `identity`
-#### `required`
-
-### `userAgent`
+### `AgentOptions.http3: object`
+
+Settings related to HTTP/3. This is a nested object.
+
+#### `AgentOptions.http3.congestion: string`
+
+The congestion control algorithm. The default is `cubic`, which is the same used in TCP in the
+Linux stack. It's fair for all traffic, but not the most optimal, especially for networks with
+a lot of available bandwidth, high latency, or a lot of packet loss. Cubic reacts to packet loss by
+dropping the speed by 30%, and takes a long time to recover. BBR instead tries to maximise
+bandwidth use and optimises for round-trip time, while ignoring packet loss.
+
+In some networks, BBR can lead to pathological degradation of overall network conditions, by
+flooding the network by up to **100 times** more retransmissions. This is fixed in BBRv2 and BBRv3,
+but Fáith (or rather its underlying QUIC library quinn, [does not implement those yet][2]).
+
+[2]: https://github.com/quinn-rs/quinn/issues/1254
+
+Default: `cubic`. Accepted values: `cubic`, `bbr1`.
+
+#### `AgentOptions.http3.maxIdleTimeout: number`
+
+Maximum duration of inactivity to accept before timing out the connection, in seconds. Note that
+this only sets the timeout on this side of the connection: the true idle timeout is the _minimum_
+of this and the peer’s own max idle timeout. While the underlying library has no limits, Fáith
+defines bounds for safety: minimum 1 second, maximum 2 minutes (120 seconds).
+
+Default: 30.
+
+### `AgentOptions.pool: object`
+
+Settings related to the connection pool. This is a nested object.
+
+#### `AgentOptions.pool.idleTimeout: number`
+
+How many seconds of inactivity before a connection is closed.
+
+Default: 90 seconds.
+
+#### `AgentOptions.pool.maxIdlePerHost: number | null`
+
+The maximum amount of idle connections per host to allow in the pool. Connections will be closed
+to keep the idle connections (per host) under that number.
+
+Default: `null` (no limit).
+
+### `AgentOptions.redirect: string`
+
+*Determines the behavior in case the server replies with a redirect status.
+One of the following values:*
+
+- *`follow`: automatically follow redirects.* Fáith limits this to 10 redirects.
+- *`error`: reject the promise with a network error when a redirect status is returned.*
+- ~~*`manual`*:~~ not supported.
+- `stop`: (Fáith custom) don't follow any redirects, return the responses.
+
+*Defaults to `follow`.*
+
+### `AgentOptions.timeout: object`
+
+Timeouts for requests made with this agent. This is a nested object.
+
+#### `AgentOptions.timeout.connect: number | null`
+
+Set a timeout for only the connect phase, in milliseconds.
+
+Default: none.
+
+#### `AgentOptions.timeout.read: number | null`
+
+Set a timeout for read operations, in milliseconds.
+
+The timeout applies to each read operation, and resets after a successful read. This is more
+appropriate for detecting stalled connections when the size isn’t known beforehand.
+
+Default: none.
+
+#### `AgentOptions.timeout.total: number | null`
+
+Set a timeout for the entire request-response cycle, in milliseconds.
+
+The timeout applies from when the request starts connecting until the response body has finished.
+Also considered a total deadline.
+
+Default: none.
+
+### `AgentOptions.tls: object`
+
+Settings related to the connection pool. This is a nested object.
+
+#### `AgentOptions.tls.earlyData: boolean`
+
+Enable TLS 1.3 Early Data. Early data is an optimisation where the client sends the first packet
+of application data alongside the opening packet of the TLS handshake. That can enable the server
+to answer faster, improving latency by up to one round-trip. However, Early Data has significant
+security implications: it's vulnerable to replay attacks and has weaker forward secrecy. It should
+really only be used for static assets or to squeeze out the last drop of performance for endpoints
+that are replay-safe.
+
+Default: false.
+
+#### `AgentOptions.tls.identity: string | Buffer`
+
+Provide a PEM-formatted certificate and private key to present as a TLS client certificate (also
+called mutual TLS or mTLS) authentication.
+
+The input should contain a PEM encoded private key and at least one PEM encoded certificate. The
+private key must be in RSA, SEC1 Elliptic Curve or PKCS#8 format. This is one of the few options
+that will cause the `Agent` constructor to throw if the input is in the wrong format.
+
+#### `AgentOptions.tls.required`
+
+Disables plain-text HTTP.
+
+Default: false.
+
+### `AgentOptions.userAgent`
 
 Custom user agent string.
 
@@ -488,7 +703,7 @@ const agent = new Agent({
 });
 ```
 
-### `addCookie(url: string, cookie: string)`
+### `Agent.addCookie(url: string, cookie: string)`
 
 Add a cookie into the agent.
 
@@ -496,7 +711,7 @@ Does nothing if:
 - the cookie store is disabled
 - the url is malformed
 
-### `getCookie(url: string): string | null`
+### `Agent.getCookie(url: string): string | null`
 
 Retrieve a cookie from the store.
 
@@ -506,7 +721,7 @@ Returns `null` if:
 - the url is malformed
 - the cookie cannot be represented as a string
 
-### `stats(): object`
+### `Agent.stats(): object`
 
 Returns statistics gathered by this agent:
 
@@ -524,8 +739,10 @@ error kind, documented in this comprehensive mapping:
   - `Timeout` — request timed out
 - JS `NetworkError`:
   - `Network` — network error
+  - `Redirect` — when the agent is configured to error on redirects
 - JS `SyntaxError`:
   - `JsonParse` — JSON parse error for `response.json()`
+  - `PemParse` — PEM parse error for `AgentOptions.tls.identity`
   - `Utf8Parse` — UTF8 decoding error for `response.text()`
 - JS `TypeError`:
   - `InvalidHeader` — invalid header name or value
@@ -535,6 +752,7 @@ error kind, documented in this comprehensive mapping:
   - `ResponseBodyNotAvailable` — body is null or not available
 - JS generic `Error`:
   - `BodyStream` — internal stream handling error
+  - `Config` — invalid agent configuration
   - `RuntimeThread` — failed to start or schedule threads on the internal tokio runtime
 
 The library exports an `ERROR_CODES` object which has every error code the library throws, and
@@ -544,4 +762,4 @@ constant from `ERROR_CODES`, instead of doing string matching on the error messa
 `instance of` matching.
 
 Due to technical limitations, when reading a body stream, reads might fail, but that error
-will not have a `.code` property.
+will not have a `code` property.