miniflare 2.14.0 → 3.0.0-rc.2

package/README.md

@@ -1,178 +1,494 @@
 # 🔥 Miniflare
 
-**Miniflare** is a simulator for developing and testing
-[**Cloudflare Workers**](https://workers.cloudflare.com/).
-
-- 🎉 **Fun:** develop workers easily with detailed logging, file watching and
-  pretty error pages supporting source maps.
-- 🔋 **Full-featured:** supports most Workers features, including KV, Durable
-  Objects, WebSockets, modules and more.
-- ⚡ **Fully-local:** test and develop Workers without an internet connection.
-  Reload code on change quickly.
-
-It's an alternative to `wrangler dev`, written in TypeScript, that runs your
-workers in a sandbox implementing Workers' runtime APIs.
-
-**See <https://miniflare.dev> for more detailed documentation.**
-
-## Features
-
-- 📨 Fetch Events (with HTTP(S) server and manual dispatch)
-- ⏰ Scheduled Events (with cron triggering and manual dispatch)
-- 🔑 Variables and Secrets with `.env` Files
-- 📚 Modules Support
-- 📦 KV (with optional persistence)
-- 🪣 R2 (with optional persistence)
-- ✨ Cache (with optional persistence)
-- 📌 Durable Objects (with optional persistence)
-- 🌐 Workers Sites
-- ✉️ WebSockets
-- 🛠 Custom & Wrangler Builds Support
-- ⚙️ WebAssembly Support
-- 🗺 Source Map Support
-- 🕸 Web Standards: Base64, Timers, Fetch, Encoding, URL, Streams, Crypto
-- 📄 HTMLRewriter
-- ⚡️ Live Reload on File Changes
-- 📅 Compatibility Dates/Flags Support
-- 🔌 Multiple Workers Support
-- 🤹 Custom Jest Environment (with isolated per-test storage)
-- 💪 Written in TypeScript
-
-## Install
-
-Miniflare is installed using npm:
-
-```sh
-$ npm install -g miniflare # either globally..
-$ npm install -D miniflare # ...or as a dev dependency
-```
+**Miniflare 3** is a simulator for developing and testing
+[**Cloudflare Workers**](https://workers.cloudflare.com/), powered by
+[`workerd`](https://github.com/cloudflare/workerd).
 
-## Using the CLI
-
-```sh
-$ miniflare worker.js --watch --debug
-[mf:dbg] Options:
-[mf:dbg] - Scripts: worker.js
-[mf:dbg] Reloading worker.js...
-[mf:inf] Worker reloaded! (97B)
-[mf:dbg] Watching .env, package.json, worker.js, wrangler.toml...
-[mf:inf] Listening on :8787
-[mf:inf] - http://127.0.0.1:8787
-```
+> :warning: Miniflare 3 is API-only, and does not expose a CLI. Use Wrangler
+> with `wrangler dev --experimental-local` to develop your Workers locally with
+> Miniflare 3.
+
+## Quick Start
 
-## Using the API
+```shell
+$ npm install miniflare --save-dev
+```
 
 ```js
 import { Miniflare } from "miniflare";
 
+// Create a new Miniflare instance, starting a workerd server
 const mf = new Miniflare({
-  script: `
-  addEventListener("fetch", (event) => {
+  script: `addEventListener("fetch", (event) => {
     event.respondWith(new Response("Hello Miniflare!"));
-  });
-  `,
+  })`,
 });
-const res = await mf.dispatchFetch("http://localhost:8787/");
-console.log(await res.text()); // Hello Miniflare!
-```
 
-## CLI Reference
+// Send a request to the workerd server, the host is ignored
+const response = await mf.dispatchFetch("http://localhost:8787/");
+console.log(await response.text()); // Hello Miniflare!
 
+// Cleanup Miniflare, shutting down the workerd server
+await mf.dispose();
 ```
-Usage: miniflare [script] [options]
-
-Core Options:
- -h, --help              Show help                                                   [boolean]
- -v, --version           Show version number                                         [boolean]
- -c, --wrangler-config   Path to wrangler.toml                                        [string]
-     --wrangler-env      Environment in wrangler.toml to use                          [string]
-     --package           Path to package.json                                         [string]
- -m, --modules           Enable modules                                              [boolean]
-     --modules-rule      Modules import rule                                 [array:TYPE=GLOB]
-     --compat-date       Opt into backwards-incompatible changes from                 [string]
-     --compat-flag       Control specific backwards-incompatible changes               [array]
-     --usage-model       Usage model (bundled by default)                             [string]
- -u, --upstream          URL of upstream origin                                       [string]
- -w, --watch             Watch files for changes                                     [boolean]
- -d, --debug             Enable debug logging                                        [boolean]
- -V, --verbose           Enable verbose logging                                      [boolean]
-     --(no-)update-check Enable update checker (enabled by default)                  [boolean]
-     --repl              Enable interactive REPL                                     [boolean]
-     --root              Path to resolve files relative to                            [string]
-     --mount             Mount additional named workers                [array:NAME=PATH[@ENV]]
-     --name              Name of service                                              [string]
-     --route             Route to respond with this worker on                          [array]
-     --global-async-io   Allow async I/O outside handlers                            [boolean]
-     --global-timers     Allow setting timers outside handlers                       [boolean]
-     --global-random     Allow secure random generation outside handlers             [boolean]
-     --actual-time       Always return correct time from Date methods                [boolean]
-     --inaccurate-cpu    Log inaccurate CPU time measurements                        [boolean]
-
-HTTP Options:
- -H, --host              Host for HTTP(S) server to listen on                         [string]
- -p, --port              Port for HTTP(S) server to listen on                         [number]
- -O, --open              Automatically open browser to URL                    [boolean/string]
-     --https             Enable self-signed HTTPS (with optional cert path)   [boolean/string]
-     --https-key         Path to PEM SSL key                                          [string]
-     --https-cert        Path to PEM SSL cert chain                                   [string]
-     --https-ca          Path to SSL trusted CA certs                                 [string]
-     --https-pfx         Path to PFX/PKCS12 SSL key/cert chain                        [string]
-     --https-passphrase  Passphrase to decrypt SSL files                              [string]
-     --(no-)cf-fetch     Path for cached Request cf object from Cloudflare    [boolean/string]
-     --live-reload       Reload HTML pages whenever worker is reloaded               [boolean]
-
-Scheduler Options:
- -t, --cron              CRON expression for triggering scheduled events               [array]
-
-Build Options:
- -B, --build-command     Command to build project                                     [string]
-     --build-base-path   Working directory for build command                          [string]
-     --build-watch-path  Directory to watch for rebuilding on changes                  [array]
-
-KV Options:
- -k, --kv                KV namespace to bind                                          [array]
-     --kv-persist        Persist KV data (to optional path)                   [boolean/string]
-
-R2 Options:
- -r, --r2                R2 bucket to bind                                             [array]
-     --r2-persist        Persist R2 data (to optional path)                   [boolean/string]
-
-Durable Objects Options:
- -o, --do                Durable Object to bind                     [array:NAME=CLASS[@MOUNT]]
-     --do-persist        Persist Durable Object data (to optional path)       [boolean/string]
-     --(no-)do-alarms    Enable Durable Object alarms (enabled by default)           [boolean]
-
-Cache Options:
-     --(no-)cache        Enable default/named caches (enabled by default)            [boolean]
-     --cache-persist     Persist cached data (to optional path)               [boolean/string]
-
-Sites Options:
- -s, --site              Path to serve Workers Site files from                        [string]
-     --site-include      Glob pattern of site files to serve                           [array]
-     --site-exclude      Glob pattern of site files not to serve                       [array]
-
-Bindings Options:
- -e, --env               Path to .env file                                            [string]
- -b, --binding           Binds variable/secret to environment                [array:KEY=VALUE]
-     --global            Binds variable/secret to global scope               [array:KEY=VALUE]
-     --wasm              WASM module to bind                                 [array:NAME=PATH]
-     --text-blob         Text blob to bind                                   [array:NAME=PATH]
-     --data-blob         Data blob to bind                                   [array:NAME=PATH]
- -S, --service           Mounted service to bind                      [array:NAME=MOUNT[@ENV]]
-```
 
-## Acknowledgements
+## API
+
+### `type Awaitable<T>`
+
+`T | Promise<T>`
+
+Represents a value that can be `await`ed. Used in callback types to allow
+`Promise`s to be returned if necessary.
+
+### `type Json`
+
+`string | number | boolean | null | Record<string, Json> | Json[]`
+
+Represents a JSON-serialisable value.
+
+### `type ModuleRuleType`
+
+`"ESModule" | "CommonJS" | "Text" | "Data" | "CompiledWasm"`
+
+Represents how a module's contents should be interpreted.
+
+- `"ESModule"`: interpret as
+  [ECMAScript module](https://tc39.es/ecma262/#sec-modules)
+- `"CommonJS"`: interpret as
+  [CommonJS module](https://nodejs.org/api/modules.html#modules-commonjs-modules)
+- `"Text"`: interpret as UTF8-encoded data, expose in runtime with
+  `string`-typed `default` export
+- `"Data"`: interpret as arbitrary binary data, expose in runtime with
+  `ArrayBuffer`-typed `default` export
+- `"CompiledWasm"`: interpret as binary WebAssembly module data, expose in
+  runtime with `WebAssembly.Module`-typed `default` export
+
+### `interface ModuleDefinition`
+
+Represents a manually defined module.
+
+- `type: ModuleRuleType`
+
+  How this module's contents should be interpreted.
+
+- `path: string`
+
+  Path of this module. The module's "name" will be obtained by converting this
+  to a relative path. The original path will be used to read `contents` if it's
+  omitted.
+
+- `contents?: string | Uint8Array`
+
+  Contents override for this module. Binary data should be passed as
+  `Uint8Array`s. If omitted, will be read from `path`.
+
+### `interface ModuleRule`
+
+Represents a rule for identifying the `ModuleRuleType` of automatically located
+modules.
+
+- `type: ModuleRuleType`
+
+  How to interpret modules that match the `include` patterns.
+
+- `include: string[]`
+
+  Glob patterns to match located module paths against (e.g. `["**/*.txt"]`).
+
+- `fallthrough?: boolean`
+
+  If `true`, ignore any further rules of this `type`. This is useful for
+  disabling the built-in `ESModule` and `CommonJS` rules that match `*.mjs` and
+  `*.js`/`*.cjs` files respectively.
+
+### `type Persistence`
+
+`boolean | string | undefined`
+
+Represents where data should be persisted, if anywhere.
+
+- If this is `undefined` or `false`, data will be stored in-memory and only
+  persist between `Miniflare#setOptions()` calls, not restarts nor
+  `new Miniflare` instances.
+- If this is `true`, data will be stored on the file-system, in the `$PWD/.mf`
+  directory.
+- If this looks like a URL, then:
+  - If the protocol is `memory:`, data will be stored in-memory as above.
+  - If the protocol is `file:`, data will be stored on the file-system, in the
+    specified directory (e.g. `file:///path/to/directory`). If the `unsanitise`
+    search parameter is `true`, path sanitisation will be disabled.
+- Otherwise, if this is just a regular `string`, data will be stored on the
+  file-system, using the value as the directory path.
+
+### `enum LogLevel`
+
+`NONE, ERROR, WARN, INFO, DEBUG, VERBOSE`
+
+Controls which messages Miniflare logs. All messages at or below the selected
+level will be logged.
+
+### `interface LogOptions`
+
+- `prefix?: string`
+
+  String to add before the level prefix when logging messages. Defaults to `mf`.
+
+- `suffix?: string`
+
+  String to add after the level prefix when logging messages.
+
+### `class Log`
+
+- `constructor(level?: LogLevel, opts?: LogOptions)`
+
+  Creates a new logger that logs all messages at or below the specified level to
+  the `console`.
+
+- `error(message: Error)`
+
+  Logs a message at the `ERROR` level. If the constructed log `level` is less
+  than `ERROR`, `throw`s the `message` instead.
+
+- `warn(message: string)`
+
+  Logs a message at the `WARN` level.
+
+- `info(message: string)`
+
+  Logs a message at the `INFO` level.
+
+- `debug(message: string)`
+
+  Logs a message at the `DEBUG` level.
+
+- `verbose(message: string)`
+
+  Logs a message at the `VERBOSE` level.
+
+### `class NoOpLog extends Log`
+
+- `constructor()`
+
+  Creates a new logger that logs nothing to the `console`, and always `throw`s
+  `message`s logged at the `ERROR` level.
+
+### `interface WorkerOptions`
+
+Options for an individual Worker/"nanoservice". All bindings are accessible on
+the global scope in service-worker format Workers, or via the 2nd `env`
+parameter in module format Workers.
+
+#### Core
+
+- `name?: string`
+
+  Unique name for this worker. Only required if multiple `workers` are
+  specified.
+
+- `script?: string`
+
+  JavaScript code for this worker. If this is a service worker format Worker, it
+  must not have any imports. If this is a modules format Worker, it must not
+  have any _npm_ imports, and `modules: true` must be set. If it does have
+  imports, `scriptPath` must also be set so Miniflare knows where to resolve
+  them relative to.
+
+- `scriptPath?: string`
+
+  Path of JavaScript entrypoint. If this is a service worker format Worker, it
+  must not have any imports. If this is a modules format Worker, it must not
+  have any _npm_ imports, and `modules: true` must be set.
+
+- `modules?: boolean | ModuleDefinition[]`
+
+  - If `true`, Miniflare will treat `script`/`scriptPath` as an ES Module and
+    automatically locate transitive module dependencies according to
+    `modulesRules`. Note that automatic location is not perfect: if the
+    specifier to a dynamic `import()` or `require()` is not a string literal, an
+    exception will be thrown.
+
+  - If set to an array, modules can be defined manually. Transitive dependencies
+    must also be defined. Note the first module must be the entrypoint and have
+    type `"ESModule"`.
+
+- `modulesRoot?: string`
+
+  If `modules` is set to an array, modules' "name"s will be their `path`s
+  relative to this value. This ensures file paths in stack traces are correct.
+
+<!-- prettier-ignore-start -->
+<!-- (for disabling `;` insertion in `js` code block) -->
+
+- `modulesRules?: ModuleRule[]`
+
+  Rules for identifying the `ModuleRuleType` of automatically located modules
+  when `modules: true` is set. Note the following default rules are always
+  included at the end:
+
+  ```js
+  [
+    { type: "ESModule", include: ["**/*.mjs"] },
+    { type: "CommonJS", include: ["**/*.js", "**/*.cjs"] },
+  ]
+  ```
+
+  > If `script` and `scriptPath` are set, and `modules` is set to an array,
+  > `modules` takes priority for a Worker's code, followed by `script`, then
+  > `scriptPath`.
+
+<!-- prettier-ignore-end -->
+
+- `compatibilityDate?: string`
+
+  [Compatibility date](https://developers.cloudflare.com/workers/platform/compatibility-dates/)
+  to use for this Worker. Defaults to a date far in the past.
+
+- `compatibilityFlags?: string[]`
+
+  [Compatibility flags](https://developers.cloudflare.com/workers/platform/compatibility-dates/)
+  to use for this Worker.
+
+- `bindings?: Record<string, Json>`
+
+  Record mapping binding name to arbitrary JSON-serialisable values to inject as
+  bindings into this Worker.
+
+- `wasmBindings?: Record<string, string>`
+
+  Record mapping binding name to paths containing binary WebAssembly module data
+  to inject as `WebAssembly.Module` bindings into this Worker.
+
+- `textBlobBindings?: Record<string, string>`
+
+  Record mapping binding name to paths containing UTF8-encoded data to inject as
+  `string` bindings into this Worker.
+
+- `dataBlobBindings?: Record<string, string>`
+
+  Record mapping binding name to paths containing arbitrary binary data to
+  inject as `ArrayBuffer` bindings into this Worker.
+
+- `serviceBindings?: Record<string, string | { network: Network } | { external: ExternalServer } | { disk: DiskDirectory } | (request: Request) => Awaitable<Response>>`
+
+  Record mapping binding name to service designators to inject as
+  `{ fetch: typeof fetch }`
+  [service bindings](https://developers.cloudflare.com/workers/platform/bindings/about-service-bindings/)
+  into this Worker.
+
+  - If the designator is a `string`, requests will be dispatched to the Worker
+    with that `name`.
+  - If the designator is an object of the form `{ network: { ... } }`, where
+    `network` is a
+    [`workerd` `Network` struct](https://github.com/cloudflare/workerd/blob/bdbd6075c7c53948050c52d22f2dfa37bf376253/src/workerd/server/workerd.capnp#L555-L598),
+    requests will be dispatched according to the `fetch`ed URL.
+  - If the designator is an object of the form `{ external: { ... } }` where
+    `external` is a
+    [`workerd` `ExternalServer` struct](https://github.com/cloudflare/workerd/blob/bdbd6075c7c53948050c52d22f2dfa37bf376253/src/workerd/server/workerd.capnp#L504-L553),
+    requests will be dispatched to the specified remote server.
+  - If the designator is an object of the form `{ disk: { ... } }` where `disk`
+    is a
+    [`workerd` `DiskDirectory` struct](https://github.com/cloudflare/workerd/blob/bdbd6075c7c53948050c52d22f2dfa37bf376253/src/workerd/server/workerd.capnp#L600-L643),
+    requests will be dispatched to an HTTP service backed by an on-disk
+    directory.
+  - If the designator is a function, requests will be dispatched to your custom
+    handler. This allows you to access data and functions defined in Node.js
+    from your Worker.
+
+#### Cache
+
+- `cache?: boolean`
+
+  If `false`, default and named caches will be disabled. The Cache API will
+  still be available, it just won't cache anything.
+
+- `cacheWarnUsage?: boolean`
+
+  If `true`, the first use of the Cache API will log a warning stating that the
+  Cache API is unsupported on `workers.dev` subdomains.
+
+#### Durable Objects
+
+- `durableObjects?: Record<string, string | { className: string, scriptName?: string }>`
+
+  Record mapping binding name to Durable Object class designators to inject as
+  `DurableObjectNamespace` bindings into this Worker.
+
+  - If the designator is a `string`, it should be the name of a `class` exported
+    by this Worker.
+  - If the designator is an object, and `scriptName` is `undefined`, `className`
+    should be the name of a `class` exported by this Worker.
+  - Otherwise, `className` should be the name of a `class` exported by the
+    Worker with a `name` of `scriptName`.
+
+#### KV
+
+- `kvNamespaces?: Record<string, string> | string[]`
+
+  Record mapping binding name to KV namespace IDs to inject as `KVNamespace`
+  bindings into this Worker. Different Workers may bind to the same namespace ID
+  with different binding names. If a `string[]` of binding names is specified,
+  the binding name and KV namespace ID are assumed to be the same.
+
+- `sitePath?: string`
+
+  Path to serve Workers Sites files from. If set, `__STATIC_CONTENT` and
+  `__STATIC_CONTENT_MANIFEST` bindings will be injected into this Worker. In
+  modules mode, `__STATIC_CONTENT_MANIFEST` will also be exposed as a module
+  with a `string`-typed `default` export, containing the JSON-stringified
+  manifest. Note Workers Sites files are never cached in Miniflare.
+
+- `siteInclude?: string[]`
+
+  If set, only files with paths matching these glob patterns will be served.
+
+- `siteExclude?: string[]`
+
+  If set, only files with paths _not_ matching these glob patterns will be
+  served.
+
+#### R2
+
+- `r2Buckets?: Record<string, string> | string[]`
+
+  Record mapping binding name to R2 bucket names to inject as `R2Bucket`
+  bindings into this Worker. Different Workers may bind to the same bucket name
+  with different binding names. If a `string[]` of binding names is specified,
+  the binding name and bucket name are assumed to be the same.
+
+#### D1
+
+- `d1Databases?: Record<string, string> | string[]`
+
+  Record mapping binding name to D1 database IDs to inject as `Fetcher` bindings
+  into this Worker. Note these bindings must be wrapped with a facade to provide
+  the expected `D1Database` API. Different Workers may bind to the same database
+  ID with different binding names. If a `string[]` of binding names is
+  specified, the binding name and database ID are assumed to be the same.
+
+#### Analytics Engine and Queues
+
+_Not yet supported_
+
+### `interface SharedOptions`
+
+Options shared between all Workers/"nanoservices".
+
+#### Core
+
+- `host?: string`
+
+  Hostname that the `workerd` server should listen on. Defaults to `127.0.0.1`.
+
+- `port?: number`
+
+  Port that the `workerd` server should listen on. Tries to default to `8787`,
+  but falls back to a random free port if this is in use. Note if a manually
+  specified port is in use, Miniflare throws an error, rather than attempting to
+  find a free port.
+
+- `inspectorPort?: number`
+
+  Port that `workerd` should start a DevTools inspector server on. Visit
+  `chrome://inspect` in a Chromium-based browser to connect to this. This can be
+  used to see detailed `console.log`s, profile CPU usage, and will eventually
+  allow step-through debugging.
+
+- `verbose?: boolean`
+
+  Enable `workerd`'s `--verbose` flag for verbose logging. This can be used to
+  see simplified `console.log`s.
+
+- `log?: Log`
+
+  Logger implementation for Miniflare's errors, warnings and informative
+  messages.
+
+- `cf?: boolean | string | Record<string, any>`
+
+  Controls the object returned from incoming `Request`'s `cf` property.
+
+  - If set to a falsy value, an object with default placeholder values will be
+    used
+  - If set to an object, that object will be used
+  - If set to `true`, a real `cf` object will be fetched from a trusted
+    Cloudflare endpoint and cached in `node_modules/.mf` for 30 days
+  - If set to a `string`, a real `cf` object will be fetched and cached at the
+    provided path for 30 days
+
+- `liveReload?: boolean`
+
+  If `true`, Miniflare will inject a script into HTML responses that
+  automatically reloads the page in-browser whenever the Miniflare instance's
+  options are updated.
+
+#### Cache, Durable Objects, KV, R2 and D1
+
+- `cachePersist?: Persistence`
+
+  Where to persist data cached in default or named caches. See docs for
+  `Persistence`.
+
+- `durableObjectsPersist?: Persistence`
+
+  _Not yet supported_, Miniflare will throw if this is truthy and Durable Object
+  bindings are specified.
+
+- `kvPersist?: Persistence`
+
+  Where to persist data stored in KV namespaces. See docs for `Persistence`.
+
+- `r2Persist?: Persistence`
+
+  Where to persist data stored in R2 buckets. See docs for `Persistence`.
+
+- `d1Persist?: Persistence`
+
+  Where to persist data stored in D1 databases. See docs for `Persistence`.
+
+#### Analytics Engine and Queues
+
+_Not yet supported_
+
+### `type MiniflareOptions`
+
+`SharedOptions & (WorkerOptions | { workers: WorkerOptions[] })`
+
+Miniflare accepts either a single Worker configuration or multiple Worker
+configurations in the `workers` array. When specifying an array of Workers, the
+first Worker is designated the entrypoint and will receive all incoming HTTP
+requests. Some options are shared between all workers and should always be
+defined at the top-level.
+
+### `class Miniflare`
+
+- `constructor(opts: MiniflareOptions)`
+
+  Creates a Miniflare instance and starts a new `workerd` server. Note unlike
+  Miniflare 2, Miniflare 3 _always_ starts a HTTP server listening on the
+  configured `host` and `port`: there are no `createServer`/`startServer`
+  functions.
+
+- `setOptions(opts: MiniflareOptions)`
+
+  Updates the configuration for this Miniflare instance and restarts the
+  `workerd` server. Note unlike Miniflare 2, this does _not_ merge the new
+  configuration with the old configuration.
+
+- `ready: Promise<URL>`
+
+  Returns a `Promise` that resolves with a `http` `URL` to the `workerd` server
+  once it has started and is able to accept requests.
+
+- `dispatchFetch(input: RequestInfo, init?: RequestInit): Promise<Response>`
 
-Miniflare was created by [Brendan Coll](https://github.com/mrbbot).
+  Sends a HTTP request to the `workerd` server, dispatching a `fetch` event in
+  the entrypoint Worker. Returns a `Promise` that resolves with the response.
+  Note that this implicitly waits for the `ready` `Promise` to resolve, there's
+  no need to do that yourself first. Additionally, the host of the request's URL
+  is always ignored and replaced with the `workerd` server's.
 
-Many thanks to
-[dollarshaveclub/cloudworker](https://github.com/dollarshaveclub/cloudworker)
-and
-[gja/cloudflare-worker-local](https://github.com/gja/cloudflare-worker-local)
-for inspiration.
+- `dispose(): Promise<void>`
 
-Durable Object's transactions are implemented using Optimistic Concurrency
-Control (OCC) as described in
-["On optimistic methods for concurrency control." ACM Transactions on Database Systems](https://dl.acm.org/doi/10.1145/319566.319567).
-Thanks to [Alistair O'Brien](https://github.com/johnyob) for helping the
-Miniflare creator understand this.
+  Cleans up the Miniflare instance, and shuts down the `workerd` server. Note
+  that after this is called, `setOptions` and `dispatchFetch` cannot be called.