@delali/narsil 0.3.1-next.72 → 0.3.1-next.74

package/dist/{client-C2TiW29y.d.ts → client-C-I70ArH.d.ts}

@@ -1,6 +1,6 @@
-import { P as PartitionConfig, A as AnyDocument, a as InsertOptions, W as WriteOptions } from './schema-BBOCdhND.js';
-import { V as VectorMaintenanceResult, B as BatchResult, L as ListParams, g as ListResult, I as IndexInfo, f as IndexStats, P as PartitionStatsResult, Q as QueryParams, e as QueryResult, h as PreflightResult, j as SuggestParams, k as SuggestResult } from './memory-CKHTU1CL.js';
-import { e as TaskRecord, M as MemoryStatsResponse, b as ImportResult, H as HttpIndexConfig, c as TaskListQuery, T as TaskListPage } from './tasks-BECd0b__.js';
+import { P as PartitionConfig, A as AnyDocument, a as InsertOptions, W as WriteOptions } from './schema-DgyDijhf.js';
+import { V as VectorMaintenanceResult, B as BatchResult, L as ListParams, h as ListResult, I as IndexInfo, g as IndexStats, P as PartitionStatsResult, Q as QueryParams, e as QueryResult, j as PreflightResult, k as SuggestParams, l as SuggestResult } from './memory-DJEwWoCi.js';
+import { e as TaskRecord, M as MemoryStatsResponse, b as ImportResult, H as HttpIndexConfig, c as TaskListQuery, T as TaskListPage } from './tasks-BVmAKYBh.js';
 
 /**
  * This is the `fetch` implementation the client sends every request through.
@@ -74,14 +74,15 @@ interface RequestOptions {
 }
 
 /**
- * These methods run the operations that maintain an index: checkpoints,
- * snapshots, vector maintenance, partitioning, and analysis rebuilds.
+ * These methods carry out the operations that maintain an index: checkpoints,
+ * snapshots, document exports, vector maintenance, partitioning, and analysis
+ * rebuilds.
  *
- * Four of them can run for minutes, so each answers with a {@link TaskRecord}
- * while the work carries on, and you follow it with
- * {@link TaskOperations.waitForTask}. The {@link Narsil} methods they mirror
- * return nothing and finish before they resolve, which is the one place this
- * client parts from the engine.
+ * Five of them can take minutes, so each answers with a {@link TaskRecord}
+ * while the work continues. Follow that task with
+ * {@link TaskOperations.waitForTask}. The {@link Narsil} methods that they
+ * mirror finish their work before they resolve, which is the one place where
+ * this client differs from the engine.
  *
  * @public
  */
@@ -96,35 +97,85 @@ interface AdminOperations {
      */
     checkpoint(indexName: string, options?: RequestOptions): Promise<void>;
     /**
-     * Downloads one index as a portable `.nrsl` file, which any Narsil
-     * implementation can read back.
+     * Returns a stream of an index's snapshot archive. Any implementation of
+     * the Narsil format can restore the archive.
      *
-     * The whole index crosses the network, so this call sets no deadline of its
-     * own and waits for as long as the download takes until
-     * {@link NarsilClientOptions.timeoutMs} or a per-call `timeoutMs` sets one.
+     * The download takes longer as the index grows, so this method sets no
+     * deadline of its own. It waits until the download ends, unless
+     * {@link NarsilClientOptions.timeoutMs} or a per-call `timeoutMs` sets a
+     * deadline.
      *
-     * @param indexName - This names the index to serialise.
+     * @param indexName - This names the index to stream.
      * @param options - This sets the signal, the deadline, and the headers for
      * this request.
-     * @returns The bytes make up the file.
+     * @returns The stream holds the archive's bytes in the order that the server
+     * sends them.
      */
-    snapshot(indexName: string, options?: RequestOptions): Promise<Uint8Array>;
+    snapshot(indexName: string, options?: RequestOptions): Promise<ReadableStream<Uint8Array>>;
     /**
-     * Replaces an index with the contents of a `.nrsl` file, dropping whatever
-     * the index held.
+     * Uploads a snapshot archive and replaces the named index with the
+     * archive's contents. The method also accepts the single `.nrsl` file that
+     * `snapshot` returned in release 0.3.
      *
-     * The load runs as a task, so this resolves once the server has read the
-     * bytes, and the index comes back afterwards.
+     * The server writes the upload to a temporary file and restores the index
+     * in a task. This method therefore resolves once the server holds the whole
+     * upload, and the task's status changes to `succeeded` once the restored
+     * index is ready.
      *
      * @param indexName - This names the index to replace.
-     * @param data - These are the file's bytes.
+     * @param data - This is the archive, as one byte array or a stream of bytes.
      * @param options - This sets the signal, the deadline, and the headers for
      * this request.
      * @returns The record is the task to follow.
-     * @throws A `NarsilError` with `DOC_VALIDATION_FAILED` or an `ENVELOPE_`
-     * code, reported on the task, when the bytes hold no readable snapshot.
+     * @throws A `NarsilError` with `PAYLOAD_TOO_LARGE` when the upload passes
+     * the server's `maxRestoreBytes` limit, and with `EMPTY_BODY` for an empty
+     * upload. The task reports `PERSISTENCE_LOAD_FAILED`,
+     * `PERSISTENCE_CRC_MISMATCH`, `ENVELOPE_VERSION_MISMATCH`, or
+     * `CONFIG_INVALID` in its `error` when a check of the archive fails.
      */
-    restore(indexName: string, data: Uint8Array, options?: RequestOptions): Promise<TaskRecord>;
+    restore(indexName: string, data: Uint8Array | ReadableStream<Uint8Array>, options?: RequestOptions): Promise<TaskRecord>;
+    /**
+     * Returns a stream of an index's document export. The export is JSON Lines
+     * text, with the index configuration on the first line and one document on
+     * each later line. Pass the export to
+     * {@link AdminOperations.importDocumentExport} to load it into a server of
+     * this release or a later one.
+     *
+     * The download takes longer as the index grows, so this method sets no
+     * deadline of its own. It waits until the download ends, unless
+     * {@link NarsilClientOptions.timeoutMs} or a per-call `timeoutMs` sets a
+     * deadline.
+     *
+     * @param indexName - This names the index to export.
+     * @param options - This sets the signal, the deadline, and the headers for
+     * this request.
+     * @returns The stream holds the export's UTF-8 bytes in the order that the
+     * server sends them.
+     */
+    exportDocuments(indexName: string, options?: RequestOptions): Promise<ReadableStream<Uint8Array>>;
+    /**
+     * Uploads a document export and imports it into an index in a task. Where
+     * the name is free, the engine creates the index from the export's
+     * configuration. The engine replaces each document whose ID the index
+     * already contains.
+     *
+     * The server writes the upload to a temporary file before the task starts,
+     * so this method resolves once the server holds the whole upload. When the
+     * task finishes, its result holds the number of imported documents and the
+     * refused lines.
+     *
+     * @param indexName - This names the index that receives the documents.
+     * @param data - This is the export, as one byte array or a stream of bytes.
+     * @param options - This sets the signal, the deadline, and the headers for
+     * this request.
+     * @returns The record is the task to follow.
+     * @throws A `NarsilError` with `PAYLOAD_TOO_LARGE` when the upload passes
+     * the server's `maxRestoreBytes` limit, and with `EMPTY_BODY` for an empty
+     * upload. The task reports `CONFIG_INVALID` in its `error` when the first
+     * line is anything other than an export header, or when the named index
+     * exists with a different schema.
+     */
+    importDocumentExport(indexName: string, data: Uint8Array | ReadableStream<Uint8Array>, options?: RequestOptions): Promise<TaskRecord>;
     /**
      * Reports the state of each vector field, and what maintenance would cost.
      *

package/dist/client.d.ts

@@ -1,10 +1,10 @@
-export { C as ClientErrorCode, a as ClientErrorCodes, E as ErrorCode, b as ErrorCodes, N as NarsilError, c as NarsilErrorCode, S as ServerErrorCode, d as ServerErrorCodes, i as isNarsilError } from './memory-CKHTU1CL.js';
-export { A as ASYNC_IMPORT_CAPABILITY, E as ErrorEnvelope, I as INDEX_LIFECYCLE_CAPABILITY, R as REBUILD_ANALYSIS_CAPABILITY, S as SERVER_CAPABILITIES, T as TASK_CANCEL_CAPABILITY, a as TASK_FILTER_CAPABILITY } from './capabilities-D6gjjQyA.js';
-export { C as CapabilitiesResponse, a as CreateIndexEmbedding, H as HttpIndexConfig, I as ImportError, b as ImportResult, M as MemoryStatsResponse, T as TaskListPage, c as TaskListQuery, d as TaskProgress, e as TaskRecord, f as TaskStatus, g as TaskType } from './tasks-BECd0b__.js';
-export { A as AdminOperations, B as BulkOperations, D as DocumentOperations, F as FetchFunction, I as ImportSource, a as IndexOperations, N as NarsilClient, b as NarsilClientOptions, P as PutResult, R as RequestOptions, S as SearchOperations, c as ServerOperations, d as ServerVersion, T as TaskOperations, W as WaitForTaskOptions, e as createNarsilClient } from './client-C2TiW29y.js';
-import './schema-BBOCdhND.js';
+export { C as ClientErrorCode, a as ClientErrorCodes, E as ErrorCode, b as ErrorCodes, N as NarsilError, c as NarsilErrorCode, S as ServerErrorCode, d as ServerErrorCodes, i as isNarsilError } from './memory-DJEwWoCi.js';
+export { A as ASYNC_IMPORT_CAPABILITY, D as DOCUMENT_EXPORT_CAPABILITY, E as ErrorEnvelope, I as INDEX_LIFECYCLE_CAPABILITY, R as REBUILD_ANALYSIS_CAPABILITY, S as SERVER_CAPABILITIES, T as TASK_CANCEL_CAPABILITY, a as TASK_FILTER_CAPABILITY } from './capabilities-CAMzmkAg.js';
+export { C as CapabilitiesResponse, a as CreateIndexEmbedding, H as HttpIndexConfig, I as ImportError, b as ImportResult, M as MemoryStatsResponse, T as TaskListPage, c as TaskListQuery, d as TaskProgress, e as TaskRecord, f as TaskStatus, g as TaskType } from './tasks-BVmAKYBh.js';
+export { A as AdminOperations, B as BulkOperations, D as DocumentOperations, F as FetchFunction, I as ImportSource, a as IndexOperations, N as NarsilClient, b as NarsilClientOptions, P as PutResult, R as RequestOptions, S as SearchOperations, c as ServerOperations, d as ServerVersion, T as TaskOperations, W as WaitForTaskOptions, e as createNarsilClient } from './client-C-I70ArH.js';
+import './schema-DgyDijhf.js';
 import './adapters-79OIa4xm.js';
-import './config-BLguB-om.js';
-import './config-C7Ip8Ife.js';
-import './types-BiUmaiWT.js';
-import './types-D5OwhtsQ.js';
+import './config-C6Iw5rCX.js';
+import './config-DJPH3IQB.js';
+import './types-ChrVy4lH.js';
+import './types-Cb9kiY5P.js';

package/dist/client.mjs

@@ -72,7 +72,6 @@ var ErrorCodes = {
   SNAPSHOT_SYNC_UNAUTHORIZED: "SNAPSHOT_SYNC_UNAUTHORIZED",
   SNAPSHOT_SYNC_REQUEST_INVALID: "SNAPSHOT_SYNC_REQUEST_INVALID",
   SNAPSHOT_SYNC_INDEX_NOT_FOUND: "SNAPSHOT_SYNC_INDEX_NOT_FOUND",
-  SNAPSHOT_SYNC_TOO_LARGE: "SNAPSHOT_SYNC_TOO_LARGE",
   SNAPSHOT_SYNC_CAPACITY_EXHAUSTED: "SNAPSHOT_SYNC_CAPACITY_EXHAUSTED",
   SNAPSHOT_SYNC_SNAPSHOT_FAILED: "SNAPSHOT_SYNC_SNAPSHOT_FAILED",
   SNAPSHOT_SYNC_DECODE_FAILED: "SNAPSHOT_SYNC_DECODE_FAILED",
@@ -155,12 +154,14 @@ var TASK_CANCEL_CAPABILITY = "tasks.cancel";
 var TASK_FILTER_CAPABILITY = "tasks.filter";
 var REBUILD_ANALYSIS_CAPABILITY = "indexes.rebuildAnalysis";
 var INDEX_LIFECYCLE_CAPABILITY = "indexes.lifecycle";
+var DOCUMENT_EXPORT_CAPABILITY = "indexes.documentExport";
 var SERVER_CAPABILITIES = [
   ASYNC_IMPORT_CAPABILITY,
   TASK_CANCEL_CAPABILITY,
   TASK_FILTER_CAPABILITY,
   REBUILD_ANALYSIS_CAPABILITY,
-  INDEX_LIFECYCLE_CAPABILITY
+  INDEX_LIFECYCLE_CAPABILITY,
+  DOCUMENT_EXPORT_CAPABILITY
 ];
 
 // src/json-encoding.ts
@@ -241,10 +242,9 @@ function createAdminOperations(transport) {
       await transport.json({ method: "POST", path: `${indexPath(indexName)}/_checkpoint`, options });
     },
     snapshot(indexName, options) {
-      return transport.binary({
+      return transport.stream({
         method: "GET",
         path: `${indexPath(indexName)}/snapshot`,
-        binaryAnswer: true,
         defaultTimeoutMs: NO_TIMEOUT,
         options
       });
@@ -261,6 +261,26 @@ function createAdminOperations(transport) {
       });
       return readBody(payload, path);
     },
+    exportDocuments(indexName, options) {
+      return transport.stream({
+        method: "GET",
+        path: `${indexPath(indexName)}/export`,
+        defaultTimeoutMs: NO_TIMEOUT,
+        options
+      });
+    },
+    async importDocumentExport(indexName, data, options) {
+      const path = `${indexPath(indexName)}/import`;
+      const payload = await transport.json({
+        method: "POST",
+        path,
+        body: data,
+        contentType: "application/x-ndjson",
+        defaultTimeoutMs: NO_TIMEOUT,
+        options
+      });
+      return readBody(payload, path);
+    },
     async vectorMaintenanceStatus(indexName, options) {
       const path = `${indexPath(indexName)}/vector-maintenance`;
       const payload = await transport.json({ method: "GET", path, options });
@@ -517,20 +537,14 @@ async function readStreamCapped(stream, limitBytes) {
   }
   return body;
 }
-async function readAnswer(response, limitBytes, wantsBytes) {
+async function readAnswer(response, limitBytes) {
   const stream = response.body;
   if (limitBytes > 0 && stream !== null && stream !== void 0) {
-    const body = await readStreamCapped(stream, limitBytes);
-    return wantsBytes ? { text: "", bytes: body } : { text: new TextDecoder().decode(body), bytes: null };
-  }
-  if (wantsBytes) {
-    const bytes = new Uint8Array(await response.arrayBuffer());
-    if (limitBytes > 0 && bytes.byteLength > limitBytes) throw new ResponseTooLargeError(limitBytes);
-    return { text: "", bytes };
+    return new TextDecoder().decode(await readStreamCapped(stream, limitBytes));
   }
   const text = await response.text();
   if (limitBytes > 0 && text.length > limitBytes) throw new ResponseTooLargeError(limitBytes);
-  return { text, bytes: null };
+  return text;
 }
 function invalidResponse(message, details) {
   return new NarsilError(ClientErrorCodes.CLIENT_INVALID_RESPONSE, message, details);
@@ -592,19 +606,27 @@ function createTransport(options) {
     if (perCall !== void 0) return perCall;
     return options.maxResponseBytes ?? 0;
   }
-  async function exchange(spec) {
+  async function exchange(spec, keepsStream = false) {
     const url = `${base}${withQuery(spec.path, spec.query)}`;
     const headers = { ...baseHeaders, ...spec.options?.headers };
     if (spec.contentType !== void 0) headers["content-type"] = spec.contentType;
     const timeoutMs = resolveTimeout(spec);
     const deadline = startDeadline(timeoutMs, spec.options?.signal);
+    let handedOver = false;
     try {
       const init = { method: spec.method, headers, signal: deadline.signal };
       if (spec.body !== void 0) init.body = spec.body;
+      if (spec.body instanceof ReadableStream) init.duplex = "half";
       const response = await send(url, init);
-      const wantsBytes = spec.binaryAnswer === true && response.ok;
-      const answer = await readAnswer(response, resolveResponseCeiling(spec), wantsBytes);
-      return { status: response.status, url, ...answer };
+      if (keepsStream && response.ok && response.body !== null) {
+        handedOver = true;
+        const stream = response.body.pipeThrough(
+          new TransformStream({ flush: () => deadline.release() })
+        );
+        return { status: response.status, url, text: "", stream };
+      }
+      const text = await readAnswer(response, resolveResponseCeiling(spec));
+      return { status: response.status, url, stream: null, text };
     } catch (err) {
       if (err instanceof ResponseTooLargeError) {
         throw invalidResponse(`The server at ${url} answered more than this client reads: ${err.message}`, {
@@ -630,7 +652,7 @@ function createTransport(options) {
         { url }
       );
     } finally {
-      deadline.release();
+      if (!handedOver) deadline.release();
     }
   }
   function parse(status, text, path) {
@@ -657,9 +679,9 @@ function createTransport(options) {
         throw err;
       }
     },
-    async binary(spec) {
-      const { status, text, bytes, url } = await exchange(spec);
-      if (bytes !== null) return bytes;
+    async stream(spec) {
+      const { status, text, stream, url } = await exchange(spec, true);
+      if (stream !== null) return stream;
       throw errorFromBody(status, parse(status, text, url), url);
     },
     async probe(spec) {
@@ -874,4 +896,4 @@ function createNarsilClient(options) {
   };
 }
 
-export { ASYNC_IMPORT_CAPABILITY, ClientErrorCodes, ErrorCodes, INDEX_LIFECYCLE_CAPABILITY, NarsilError, REBUILD_ANALYSIS_CAPABILITY, SERVER_CAPABILITIES, ServerErrorCodes, TASK_CANCEL_CAPABILITY, TASK_FILTER_CAPABILITY, createNarsilClient, isNarsilError };
+export { ASYNC_IMPORT_CAPABILITY, ClientErrorCodes, DOCUMENT_EXPORT_CAPABILITY, ErrorCodes, INDEX_LIFECYCLE_CAPABILITY, NarsilError, REBUILD_ANALYSIS_CAPABILITY, SERVER_CAPABILITIES, ServerErrorCodes, TASK_CANCEL_CAPABILITY, TASK_FILTER_CAPABILITY, createNarsilClient, isNarsilError };

package/dist/{config-BLguB-om.d.ts → config-C6Iw5rCX.d.ts}

@@ -1,6 +1,6 @@
-import { N as NarsilConfig } from './config-C7Ip8Ife.js';
-import { A as AllocationTable, N as NodeRole, a as NodeRegistration, C as ClusterCoordinator, b as NodeCapacity } from './types-BiUmaiWT.js';
-import { N as NodeTransport } from './types-D5OwhtsQ.js';
+import { N as NarsilConfig } from './config-DJPH3IQB.js';
+import { A as AllocationTable, N as NodeRole, a as NodeRegistration, C as ClusterCoordinator, b as NodeCapacity } from './types-ChrVy4lH.js';
+import { N as NodeTransport } from './types-Cb9kiY5P.js';
 
 /**
  * How much replication history a primary keeps, and how many replicas have to
@@ -41,7 +41,14 @@ interface ClusterNodeConfig {
     nodeId?: string;
     /** This node offers this much capacity, which the allocator weighs. It offers {@link DEFAULT_CAPACITY} by default. */
     capacity?: NodeCapacity;
-    /** These settings configure the engine this node runs locally, such as its persistence and durability. */
+    /**
+     * These settings configure the engine this node runs locally, such as its persistence and durability.
+     *
+     * When the node sends or receives a copy of an index, it writes that copy to disk so that the copy never has to fit
+     * in memory. The copy goes into a `.snapshot-transfer` directory inside the durability directory, or into the
+     * system's temporary directory when the engine has no durability directory, and the node deletes it once the
+     * transfer ends.
+     */
     engine?: NarsilConfig;
     /** These replication settings override the engine's own, and anything you leave out keeps its value. */
     replication?: Partial<ReplicationConfig>;

package/dist/{config-C7Ip8Ife.d.ts → config-DJPH3IQB.d.ts}

@@ -1,6 +1,6 @@
 import { P as PersistenceAdapter, I as InvalidationAdapter, E as EmbeddingAdapter } from './adapters-79OIa4xm.js';
-import { Q as QueryParams, e as QueryResult } from './memory-CKHTU1CL.js';
-import { I as IndexConfig, A as AnyDocument } from './schema-BBOCdhND.js';
+import { Q as QueryParams, e as QueryResult, f as NarsilEventHandlers } from './memory-DJEwWoCi.js';
+import { I as IndexConfig, A as AnyDocument } from './schema-DgyDijhf.js';
 
 /**
  * Hooks that the engine calls alongside its own work, so that an application
@@ -197,6 +197,15 @@ interface NarsilConfig {
     analysis?: AnalysisConfig;
     /** These limits close indexes while keeping their durable files ready to reopen. */
     lifecycle?: IndexLifecycleConfig;
+    /**
+     * These listeners receive events from the moment that the engine starts.
+     * The engine registers each one before it recovers any index, so a listener
+     * here receives the `layoutUpgrade` events of that recovery, which come
+     * before {@link createNarsil} returns the engine. For a name outside
+     * {@link NarsilEventMap}, or an entry that is not a function,
+     * {@link createNarsil} throws `CONFIG_INVALID`.
+     */
+    events?: NarsilEventHandlers;
     /**
      * This is the most work that the engine may do on the pattern tests of one
      * search, counted over every partition that it searches. The engine adds one

package/dist/direct-executor-KFAGILJC.mjs

@@ -0,0 +1,17 @@
+export { createDirectExecutor } from './chunk-BVBIQQKG.mjs';
+import './chunk-VKX2BPXD.mjs';
+import './chunk-4MQ5F4IL.mjs';
+import './chunk-3DDUNI6N.mjs';
+import './chunk-TGP5M5R7.mjs';
+import './chunk-PO53FV4Q.mjs';
+import './chunk-ZJ4CSAB2.mjs';
+import './chunk-2E35UM3G.mjs';
+import './chunk-XW25X6AU.mjs';
+import './chunk-ZKRV5M2P.mjs';
+import './chunk-T5ZWEWVD.mjs';
+import './chunk-I23G3IZC.mjs';
+import './chunk-Z3DQPOJQ.mjs';
+import './chunk-KEHK2O6P.mjs';
+import './chunk-U2BKYEC7.mjs';
+import './chunk-LJYTW7GT.mjs';
+import './chunk-I64LXKO3.mjs';

package/dist/distribution/coordinator/etcd.d.ts

@@ -1,20 +1,31 @@
-import { C as ClusterCoordinator } from '../../types-BiUmaiWT.js';
-import '../../schema-BBOCdhND.js';
+import { C as ClusterCoordinator } from '../../types-ChrVy4lH.js';
+import '../../schema-DgyDijhf.js';
 import '../../adapters-79OIa4xm.js';
 
 /**
- * How {@link createEtcdCoordinator} reaches etcd, and how long a node's
- * registration survives there.
+ * Configures where {@link createEtcdCoordinator} connects, how long etcd keeps
+ * a node's registration, and how large a request the coordinator sends.
  *
  * @public
  */
 interface EtcdCoordinatorConfig {
     /** The coordinator connects to these etcd endpoints. */
     endpoints: string[];
-    /** The coordinator writes every key under this prefix, which lets one etcd cluster hold several Narsil clusters. */
+    /** The coordinator writes every key under this prefix, so that one etcd cluster can store several Narsil clusters. */
     keyPrefix: string;
-    /** A node's registration survives this many seconds without a heartbeat, after which peers treat the node as gone. */
+    /** etcd keeps a node's registration for this many seconds without a heartbeat, after which peers count the node as gone. */
     nodeHeartbeatTtlSeconds: number;
+    /**
+     * The coordinator sends etcd requests of at most this many bytes, so set it
+     * to the `--max-request-bytes` value of every etcd member. The default of
+     * 1,572,864 matches the etcd default. The coordinator raises
+     * `CONFIG_INVALID` for a write whose request would be larger, and for a
+     * write that etcd reports as too large. When this value is more than
+     * 524,288 bytes above the etcd setting, a write in that gap can fail at the
+     * gRPC layer of etcd, after which the `etcd3` client stops sending requests
+     * to that member for five seconds.
+     */
+    maxRequestBytes: number;
 }
 
 /**
@@ -34,19 +45,21 @@ interface EtcdCoordinatorConfig {
 declare function validateNodeId(nodeId: string): void;
 
 /**
- * Builds a coordinator backed by etcd, which is what holds a cluster's shared
- * state across hosts and restarts.
+ * Builds a coordinator backed by etcd, which stores a cluster's shared state
+ * across hosts and restarts.
  *
- * etcd gives the coordinator what a cluster depends on: leases that expire once
- * a node misses its heartbeats, and compare-and-set writes that keep two
- * controllers from disagreeing. Install `etcd3` alongside this package,
- * because it is an optional peer dependency this call loads on demand.
+ * etcd provides the two mechanisms that a cluster uses: leases, which expire
+ * once a node misses its heartbeats, and compare-and-set writes, which stop two
+ * controllers from writing conflicting state. Install `etcd3` alongside this
+ * package, because it is an optional peer dependency that this call loads on
+ * demand.
  *
- * @param config - Endpoints, key prefix, and heartbeat lifetime to override.
- * Anything you leave out keeps its default.
- * @returns A coordinator you pass as a cluster node's `coordinator`.
+ * @param config - The endpoints, key prefix, heartbeat lifetime, and request
+ * size to override. Every setting that you leave out keeps its default.
+ * @returns A coordinator that you pass as a cluster node's `coordinator`.
  * @throws A `NarsilError` with `COORDINATOR_DEPENDENCY_MISSING` when `etcd3`
- * is not installed.
+ * is not installed, or with `CONFIG_INVALID` when `maxRequestBytes` is not a
+ * whole number from 1,025 to 2,147,483,647.
  *
  * @public
  */