@passcod/faith 0.0.2

package/README.md

@@ -0,0 +1,547 @@
+# fáith - Rust-powered fetch API for Node.js
+
+/ˈɸaːθj/ — pronounced FATH, like FATHER without the ER. This is an old irish word with the same
+root as "fetch", meaning _poet_, _soothsayer_, _seer_, and later, _prophet_.
+
+Fáith is of course a pun with _faith_, and is meant to be a _faithful_ implementation of the fetch
+API for Node.js, but using a Rust-based network stack instead of undici + libuv.
+
+Most `fetch` implementations for Node.js are based on the Node.js TCP stack (via libuv) and cannot
+easily work around its limitations. The native fetch implementation, `undici`, explicitly targets
+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.
+
+## Installation
+
+```bash
+npm install @passcod/faith
+```
+
+## Usage
+
+### Basic fetch
+
+```javascript
+import { fetch } from '@passcod/faith';
+
+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
+}
+```
+
+### Fetch with options
+
+```javascript
+const response = await fetch('https://httpbin.org/post', {
+  method: 'POST',
+  headers: {
+    'Content-Type': 'application/json',
+    'X-Custom-Header': 'value'
+  },
+  body: JSON.stringify({ message: 'Hello' }),
+  timeout: 30 // seconds
+});
+```
+
+# API Reference
+
+Conforms to the [fetch API](https://developer.mozilla.org/en-US/docs/Web/API/Fetch_API).
+
+In the following documentation, italics are parts that are *identical to how native fetch works*
+(as per MDN), and non-italics document where behaviour varies and is specific to fáith (unless
+otherwise specified).
+
+## `fetch()`
+
+### Syntax
+
+```javascript
+import { fetch } from '@passcod/faith';
+fetch(resource);
+fetch(resource, options);
+```
+
+### Parameters
+
+#### `resource`
+
+*This defines the resource that you wish to fetch. This can either be:*
+
+- *A string or any other object with a stringifier — including a `URL` object — that provides the
+  URL of the resource you want to fetch.* The URL must be absolute and include a scheme.
+
+- *A `Request` object.*
+
+#### `options` (Optional)
+
+*A `RequestInit` object containing any custom settings that you want to apply to the request.* In
+practice the `RequestInit` class does not exist in browsers or Node.js, and so this is always a
+"plain object" or "dictionary". The fields supported by Fáith are documented below.
+
+### Return value
+
+*A `Promise` that resolves to a `Response` object.*
+
+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
+body has not yet finished sending. Most HTTP servers will not send response headers until they've
+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`
+
+Fáith does not implement its own `Request` object. Instead, you can pass a Web API `Request` object
+to `fetch()`, and it will internally be converted to the right options.
+
+## `RequestInit` object
+
+*The `RequestInit` dictionary of the Fetch API represents the set of options that can be used to
+configure a fetch request.*
+
+*You can pass a `RequestInit` object into the `Request()` constructor, or directly into the
+`fetch()` function call.* Note that Fáith has additional options available, and those will not
+survive a trip through `Request`. Prefer to supply `RequestInit` directly to `fetch()`.
+
+*You can also construct a `Request` with a `RequestInit`, and pass the `Request` to a `fetch()`
+call along with another `RequestInit`. If you do this, and the same option is set in both places,
+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`
+
+This is custom to Fáith.
+
+You can create an `Agent`, and pass it here to have the request executed by the `Agent`. See the
+documentation for the `Agent` options you can set with this, and the agent data you can access.
+Notably an agent has a DNS cache, and may be configured to handle cookies and/or an HTTP cache.
+
+When not provided, a global default `Agent` is created on first use.
+
+### `attributionReporting`
+
+Fáith deliberately does not implement this.
+
+### `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:*
+
+- *a string*
+- *`ArrayBuffer`*
+- *`Blob`*
+- *`DataView`*
+- *`File`*
+- *`FormData`*
+- *`TypedArray`*
+- *`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`
+
+Fáith deliberately does not implement this.
+
+### `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`.
+
+### `credentials`
+
+*Controls whether or not the browser 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`).
+
+### `duplex`
+
+*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`
+
+*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.*
+
+Fáith allows all request headers to be set (unlike browsers, which [forbid][1] a number of them).
+
+[1]: https://developer.mozilla.org/en-US/docs/Glossary/Forbidden_request_header
+
+### `integrity`
+
+Not implemented yet.
+
+*Contains the subresource integrity value of the request.*
+
+*The format of this option is `<hash-algo>-<hash-source>` where:*
+
+- *`<hash-algo>` is one of the following values: `sha256`, `sha384`, or `sha512`*
+- *`<hash-source>` is the Base64-encoding of the result of hashing the resource with the specified
+  hash algorithm.*
+
+Fáith only checks the integrity when using `bytes()`, `json()`, `text()`, `arrayBuffer()`, and
+`blob()`. Verification when reading through the `body` stream is not currently supported.
+
+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`
+
+Not supported.
+
+Note that this is different from `Connection: keep-alive`; Fáith connections are pooled within each
+single `Agent`, so subsequent requests to the same endpoint are faster until the pooled connection
+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`
+
+*The request method. Defaults to `GET`.*
+
+### `mode`
+
+Fáith deliberately does not implement this, as there is no CORS/origin.
+
+### `priority`
+
+Not supported.
+
+### `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`
+
+Fáith deliberately does not implement this, as there is no origin.
+
+However, Fáith does set the `Referer` header when redirecting automatically.
+
+### `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`
+
+*An `AbortSignal`. If this option is set, the request can be canceled by calling `abort()` on the
+corresponding `AbortController`.*
+
+### `timeout`
+
+Custom to Fáith. Cancels the request after this many milliseconds.
+
+This will give a different error to using `signal` with a timeout, which might be preferable in
+some cases. It also has a slightly different internal behaviour: `signal` may abort the request
+only until the response headers have been received, while `timeout` will apply through the entire
+response receipt.
+
+## `Response`
+
+*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.
+
+### `Response.body`
+
+*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.
+
+### `Response.bodyUsed`
+
+*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.
+
+### `Response.headers`
+
+*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.
+
+### `Response.ok`
+
+*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`
+
+*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.*
+
+### `Response.status`
+
+*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`
+
+*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.
+
+### `Response.type`
+
+*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`
+
+*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`
+
+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()`
+
+*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()`
+
+*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()`
+
+*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()`
+
+*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.)
+
+### `Response.formData()`
+
+Fáith deliberately does not implement this.
+
+### `Response.json()`
+
+*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.
+
+### `Response.text()`
+
+*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()`
+
+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
+properties of a Fáith Response (or of another Web Response, for that matter). So this method only
+returns a Response from:
+
+- the `body` stream
+- the `status`, `statusCode`, and `headers` properties
+
+Note that if `json()`, `bytes()`, etc has been called on the original response, the body stream
+of the new Web `Response` will be empty or inaccessible. If the body stream of the original
+response has been partially read, only the remaining bytes will be available in the new `Response`.
+
+## `Agent`
+
+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.
+
+### Syntax
+
+```javascript
+new Agent()
+new Agent(options)
+```
+
+### `cache`
+### `cookies: bool`
+
+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.
+
+### `dns`
+### `headers: Array<{ name: string, value: string, sensitive?: bool }>`
+
+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.
+
+### `http3`
+#### `congestion`
+### `pool`
+#### `maxIdlePerHost`
+#### `idleTimeout`
+### `redirect`
+### `retry`
+### `timeout`
+#### `connect`
+#### `read`
+#### `total`
+### `tls`
+#### `earlyData`
+#### `identity`
+#### `required`
+
+### `userAgent`
+
+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}`,
+});
+```
+
+### `addCookie(url: string, cookie: string)`
+
+Add a cookie into the agent.
+
+Does nothing if:
+- the cookie store is disabled
+- the url is malformed
+
+### `getCookie(url: string): string | null`
+
+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
+
+### `stats(): object`
+
+Returns statistics gathered by this agent:
+
+- `requestsSent`
+- `responsesReceived`
+
+## Error mapping
+
+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
+- JS `SyntaxError`:
+  - `JsonParse` — JSON parse error for `response.json()`
+  - `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
+  - `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.

package/index.d.ts

@@ -0,0 +1,109 @@
+/* auto-generated by NAPI-RS */
+/* eslint-disable */
+export declare class Agent {
+  constructor(options?: AgentOptions | undefined | null)
+  addCookie(url: string, cookie: string): void
+  getCookie(url: string): string | null
+  stats(): AgentStats
+}
+
+export declare class AgentStats {
+  requestsSent: number
+  responsesReceived: number
+}
+
+export declare class FaithResponse {
+  get headers(): Array<[string, string]>
+  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
+   *
+   * 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.
+   */
+  bytes(): Async<Buffer>
+  /** Convert response body to text (UTF-8) */
+  text(): Async<string>
+  /** Parse response body as JSON */
+  json(): Async<any>
+  /**
+   * Create a clone of the response
+   *
+   * 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.
+   *
+   * 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.
+   */
+  clone(): FaithResponse
+}
+
+export interface AgentOptions {
+  cookies?: boolean
+  headers?: Array<Header>
+  userAgent?: string
+}
+
+export declare const enum CredentialsOption {
+  Omit = 'omit',
+  SameOrigin = 'same-origin',
+  Include = 'include'
+}
+
+export declare const enum DuplexOption {
+  Half = 'half'
+}
+
+export declare function errorCodes(): Array<string>
+
+export const FAITH_VERSION: string
+
+export declare const enum FaithErrorKind {
+  Aborted = 'Aborted',
+  BodyStream = 'BodyStream',
+  InvalidHeader = 'InvalidHeader',
+  InvalidMethod = 'InvalidMethod',
+  InvalidUrl = 'InvalidUrl',
+  JsonParse = 'JsonParse',
+  Network = 'Network',
+  ResponseAlreadyDisturbed = 'ResponseAlreadyDisturbed',
+  ResponseBodyNotAvailable = 'ResponseBodyNotAvailable',
+  RuntimeThread = 'RuntimeThread',
+  Timeout = 'Timeout',
+  Utf8Parse = 'Utf8Parse'
+}
+
+export declare function faithFetch(url: string, options: FaithOptionsAndBody, signal?: AbortSignal | undefined | null): Async<FaithResponse>
+
+export interface FaithOptionsAndBody {
+  method?: string
+  headers?: Array<[string, string]>
+  body?: string | Buffer | Uint8Array
+  timeout?: number
+  credentials?: CredentialsOption
+  duplex?: DuplexOption
+  agent: Agent
+}
+
+export interface Header {
+  name: string
+  value: string
+  sensitive?: boolean
+}
+
+export const REQWEST_VERSION: string
+
+export const USER_AGENT: string