@passcod/faith 0.0.2 → 0.0.4

package/index.d.ts

@@ -1,9 +1,48 @@
 /* auto-generated by NAPI-RS */
 /* eslint-disable */
+/**
+ * The `Agent` interface of the Fáith API represents an instance of an HTTP client. Each `Agent` has
+ * its own options, connection pool, caches, etc. There are also conveniences such as `headers` for
+ * setting default headers on all requests done with the agent, and statistics collected by the agent.
+ *
+ * Re-using connections between requests is a significant performance improvement: not only because
+ * the TCP and TLS handshake is only performed once across many different requests, but also because
+ * the DNS lookup doesn't need to occur for subsequent requests on the same connection. Depending on
+ * DNS technology (DoH and DoT add a whole separate handshake to the process) and overall latency,
+ * this can not only speed up requests on average, but also reduce system load.
+ *
+ * For this reason, and also because in browsers this behaviour is standard, **all** requests with
+ * 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.
+ */
 export declare class Agent {
   constructor(options?: AgentOptions | undefined | null)
+  /**
+   * Add a cookie into the agent.
+   *
+   * Does nothing if:
+   * - the cookie store is disabled
+   * - the url is malformed
+   */
   addCookie(url: string, cookie: string): void
+  /**
+   * Retrieve a cookie from the store.
+   *
+   * Returns `null` if:
+   * - there's no cookie at this url
+   * - the cookie store is disabled
+   * - the url is malformed
+   * - the cookie cannot be represented as a string
+   */
   getCookie(url: string): string | null
+  /**
+   * Returns statistics gathered by this agent:
+   *
+   * - `requestsSent`
+   * - `responsesReceived`
+   */
   stats(): AgentStats
 }
 
@@ -12,57 +51,436 @@ export declare class AgentStats {
   responsesReceived: number
 }
 
+/**
+ * The `Response` interface of the Fetch API represents the response to a request.
+ *
+ * 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.
+ */
 export declare class FaithResponse {
+  /**
+   * The `headers` read-only property of the `Response` interface contains the `Headers` object
+   * 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.
+   */
   get headers(): Array<[string, string]>
+  /**
+   * 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.
+   */
   get ok(): boolean
-  get redirected(): boolean
-  get status(): number
-  get statusText(): string
-  get type(): string
-  get url(): string
-  get version(): string
-  /** Check if the response body has been disturbed (read) */
-  get bodyUsed(): boolean
-  /** Get the response body as a ReadableStream */
-  get body(): ReadableStream<Buffer> | null
   /**
-   * Get response body as bytes
+   * Custom to Fáith.
    *
-   * This may use up to 2x the amount of memory that the response body takes
-   * when the Response is cloned() and will create a full copy of the data.
+   * The `peer` read-only property of the `Response` interface contains an object with information about
+   * the remote peer that sent this response:
    */
-  bytes(): Async<Buffer>
-  /** Convert response body to text (UTF-8) */
-  text(): Async<string>
-  /** Parse response body as JSON */
-  json(): Async<any>
+get peer(): { address?: string; certificate?: Buffer }
+/**
+ * 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.
+ *
+ * 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.
+ */
+get redirected(): boolean
+/**
+ * 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`.
+ */
+get status(): number
+/**
+ * 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
+ * status code `200`, `Continue` for `100`, `Not Found` for `404`.
+ *
+ * In HTTP/1, servers can send custom status text. This is returned here. In HTTP/2 and HTTP/3, custom
+ * status text is not supported at all, and the `statusText` property is either empty or simulated
+ * from well-known status codes.
+ */
+get statusText(): 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`.
+ */
+get type(): 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.
+ */
+get url(): 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.
+ */
+get version(): string
+/**
+ * The `bodyUsed` read-only property of the `Response` interface is a boolean value that indicates
+ * whether the body has been read yet.
+ *
+ * In Fáith, this indicates whether the body stream has ever been read from or canceled, as defined
+ * [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.
+ */
+get bodyUsed(): boolean
+/**
+ * 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
+ * `204 No Content` responses.
+ *
+ * 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.
+ */
+get body(): ReadableStream<Buffer> | null
+/**
+ * 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`.
+ */
+bytes(): Async<Buffer>
+/**
+ * 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.
+ */
+text(): Async<string>
+/**
+ * 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
+ * `JSON`.
+ *
+ * Note that despite the method being named `json()`, the result is not JSON but is instead the
+ * result of taking JSON as input and parsing it to produce a JavaScript object.
+ *
+ * Further note that, at least in Fáith, this method first reads the entire response body as bytes,
+ * 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.
+ */
+json(): Async<any>
+/**
+ * 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(): FaithResponse
+}
+
+/** Settings related to the HTTP cache. This is a nested object. */
+export interface AgentCacheOptions {
+  /**
+   * Which cache store to use: either `disk` or `memory`.
+   *
+   * Default: none (cache disabled).
+   */
+  store?: CacheStore
+  /**
+   * If `cache.store: "memory"`, the maximum amount of items stored.
+   *
+   * Default: 10_000.
+   */
+  capacity?: number
   /**
-   * Create a clone of the response
+   * Default cache mode. This is the same as [`FetchOptions.cache`](#fetchoptionscache), and is used if
+   * no cache mode is set on a request.
    *
-   * Specially, this doesn't set the disturbed flag, so that `body()` or other such
-   * methods can work afterwards. However, it will throw if the body has already
-   * been read from.
+   * Default: `"default"`.
+   */
+  mode?: RequestCacheMode
+  /**
+   * If `cache.store: "disk"`, then this is the path at which the cache data is. Must be writeable.
    *
-   * Clones will cache in memory the section of the response body that is read
-   * from one clone and not yet consumed by all others. In the worst case, you can
-   * end up with a copy of the entire response body if you end up not consuming one
-   * of the clones.
+   * Required if `cache.store: "disk"`.
    */
-  clone(): FaithResponse
+  path?: string
+  /**
+   * 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.
+   */
+  shared?: boolean
+}
+
+/** Settings related to DNS. This is a nested object. */
+export interface AgentDnsOptions {
+  /**
+   * 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/
+   */
+  system?: boolean
+  /**
+   * 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.
+   */
+  overrides?: Array<DnsOverride>
+}
+
+/** Settings related to HTTP/3. This is a nested object. */
+export interface AgentHttp3Options {
+  /**
+   * 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`.
+   */
+  congestion?: Http3Congestion
+  /**
+   * 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.
+   */
+  maxIdleTimeout?: number
 }
 
 export interface AgentOptions {
+  /** Settings related to the HTTP cache. This is a nested object. */
+  cache?: AgentCacheOptions
+  /**
+   * Enable a persistent cookie store for the agent. Cookies received in responses will be preserved and
+   * included in additional requests.
+   *
+   * Default: `false`.
+   *
+   * You may use `agent.getCookie(url: string)` and `agent.addCookie(url: string, value: string)` to add
+   * and retrieve cookies from the store.
+   */
   cookies?: boolean
+  /** Settings related to DNS. This is a nested object. */
+  dns?: AgentDnsOptions
+  /**
+   * Sets the default headers for every request.
+   *
+   * If header names or values are invalid, they are silently omitted.
+   * Sensitive headers (e.g. `Authorization`) should be marked.
+   *
+   * Default: none.
+   */
   headers?: Array<Header>
+  /** Settings related to HTTP/3. This is a nested object. */
+  http3?: AgentHttp3Options
+  /** Settings related to the connection pool. This is a nested object. */
+  pool?: AgentPoolOptions
+  /** Determines the behavior in case the server replies with a redirect status. */
+  redirect?: Redirect
+  /** Timeouts for requests made with this agent. This is a nested object. */
+  timeout?: AgentTimeoutOptions
+  /** Settings related to the connection pool. This is a nested object. */
+  tls?: AgentTlsOptions
+  /**
+   * Custom user agent string.
+   *
+   * Default: `Faith/{version} reqwest/{version}`.
+   */
   userAgent?: string
 }
 
+/** Settings related to the connection pool. This is a nested object. */
+export interface AgentPoolOptions {
+  /**
+   * How many seconds of inactivity before a connection is closed.
+   *
+   * Default: 90 seconds.
+   */
+  idleTimeout?: number
+  /**
+   * 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).
+   */
+  maxIdlePerHost?: number
+}
+
+/** Timeouts for requests made with this agent. This is a nested object. */
+export interface AgentTimeoutOptions {
+  /**
+   * Set a timeout for only the connect phase, in milliseconds.
+   *
+   * Default: none.
+   */
+  connect?: number
+  /**
+   * 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.
+   */
+  read?: number
+  /**
+   * 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.
+   */
+  total?: number
+}
+
+/** Settings related to the connection pool. This is a nested object. */
+export interface AgentTlsOptions {
+  /**
+   * 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.
+   */
+  earlyData?: boolean
+  /**
+   * 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.
+   */
+  identity?: Buffer | string
+  /**
+   * Disables plain-text HTTP.
+   *
+   * Default: false.
+   */
+  required?: boolean
+}
+
+/**
+ * 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.
+ *
+ * - `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.
+ *
+ * - `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.
+ */
+export declare const enum CacheMode {
+  Default = 'default',
+  ForceCache = 'force-cache',
+  IgnoreRules = 'ignore-rules',
+  NoCache = 'no-cache',
+  NoStore = 'no-store',
+  OnlyIfCached = 'only-if-cached',
+  Reload = 'reload'
+}
+
+export declare const enum CacheStore {
+  Disk = 'disk',
+  Memory = 'memory'
+}
+
+/**
+ * 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:
+ *
+ * - `omit`: Never send credentials in the request or include credentials in the response.
+ * - ~~`same-origin`~~: Fáith does not implement this, as there is no concept of "origin" on the server.
+ * - `include`: Always include credentials, ~~even for cross-origin requests.~~
+ *
+ * Fáith ignores the `Access-Control-Allow-Credentials` and `Access-Control-Allow-Origin` headers.
+ *
+ * Fáith currently does not `omit` the TLS client certificate when the request's `Agent` has one
+ * configured. This is an upstream limitation.
+ *
+ * If the request's `Agent` has cookies enabled, new cookies from the response will be added to the
+ * cookie jar, even as Fáith strips them from the request and response headers returned to the user.
+ * This is an upstream limitation.
+ *
+ * Defaults to `include` (browsers default to `same-origin`).
+ */
 export declare const enum CredentialsOption {
   Omit = 'omit',
   SameOrigin = 'same-origin',
   Include = 'include'
 }
 
+export interface DnsOverride {
+  domain: string
+  addresses: Array<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`.
+ */
 export declare const enum DuplexOption {
   Half = 'half'
 }
@@ -71,14 +489,53 @@ export declare function errorCodes(): Array<string>
 
 export const FAITH_VERSION: string
 
+/**
+ * Fáith produces fine-grained errors, but maps them to a few javascript error types for fetch
+ * compatibility. The `.code` property on errors thrown from Fáith is set to a stable name for each
+ * error kind, documented in this comprehensive mapping:
+ *
+ * - JS `AbortError`:
+ *   - `Aborted` — request was aborted using `signal`
+ *   - `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
+ *   - `InvalidMethod` — invalid HTTP method
+ *   - `InvalidUrl` — invalid URL string
+ *   - `ResponseAlreadyDisturbed` — body already read (mutually exclusive operations)
+ *   - `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
+ * every error thrown also has a `code` property that is set to one of those codes. So you can
+ * accurately respond to the exact error kind by checking its code and matching against the right
+ * constant from `ERROR_CODES`, instead of doing string matching on the error message, or coarse
+ * `instance of` matching.
+ *
+ * Due to technical limitations, when reading a body stream, reads might fail, but that error
+ * will not have a `code` property.
+ */
 export declare const enum FaithErrorKind {
   Aborted = 'Aborted',
+  AddressParse = 'AddressParse',
   BodyStream = 'BodyStream',
+  Config = 'Config',
   InvalidHeader = 'InvalidHeader',
   InvalidMethod = 'InvalidMethod',
   InvalidUrl = 'InvalidUrl',
   JsonParse = 'JsonParse',
   Network = 'Network',
+  PemParse = 'PemParse',
+  Redirect = 'Redirect',
   ResponseAlreadyDisturbed = 'ResponseAlreadyDisturbed',
   ResponseBodyNotAvailable = 'ResponseBodyNotAvailable',
   RuntimeThread = 'RuntimeThread',
@@ -89,21 +546,67 @@ export declare const enum FaithErrorKind {
 export declare function faithFetch(url: string, options: FaithOptionsAndBody, signal?: AbortSignal | undefined | null): Async<FaithResponse>
 
 export interface FaithOptionsAndBody {
-  method?: string
-  headers?: Array<[string, string]>
+  agent: Agent
   body?: string | Buffer | Uint8Array
-  timeout?: number
+  cache?: CacheMode
   credentials?: CredentialsOption
   duplex?: DuplexOption
-  agent: Agent
+  headers?: Array<[string, string]>
+  method?: string
+  timeout?: number
 }
 
+/**
+ * Sets the default headers for every request.
+ *
+ * If header names or values are invalid, they are silently omitted.
+ * Sensitive headers (e.g. `Authorization`) should be marked.
+ *
+ * Default: none.
+ */
 export interface Header {
   name: string
   value: string
   sensitive?: boolean
 }
 
+export declare const enum Http3Congestion {
+  Cubic = 'cubic',
+  Bbr1 = 'bbr1'
+}
+
+/**
+ * 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`.
+ */
+export declare const enum Redirect {
+  Follow = 'follow',
+  Error = 'error',
+  Manual = 'manual',
+  Stop = 'stop'
+}
+
 export const REQWEST_VERSION: string
 
+/**
+ * Custom user agent string.
+ *
+ * Default: `Faith/{version} reqwest/{version}`.
+ *
+ * You may use the `USER_AGENT` constant if you wish to prepend your own agent to the default, e.g.
+ *
+ * ```javascript
+ * import { Agent, USER_AGENT } from '@passcod/faith';
+ * const agent = new Agent({
+ *   userAgent: `YourApp/1.2.3 ${USER_AGENT}`,
+ * });
+ * ```
+ */
 export const USER_AGENT: string