@delali/narsil 0.3.0 → 0.3.1-next.101

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (165) hide show
  1. package/README.md +9 -8
  2. package/dist/adapters/filesystem.d.ts +1 -1
  3. package/dist/adapters/filesystem.mjs +1 -1
  4. package/dist/adapters/indexeddb.d.ts +1 -1
  5. package/dist/adapters/indexeddb.mjs +1 -1
  6. package/dist/adapters/memory.d.ts +1 -1
  7. package/dist/{adapters-79OIa4xm.d.ts → adapters-BQFQ4PRz.d.ts} +27 -1
  8. package/dist/browser/chunk-BDOSMEEP.mjs +493 -0
  9. package/dist/browser/chunk-EJDUFWSO.mjs +602 -0
  10. package/dist/browser/chunk-HOZW3PKP.mjs +9 -0
  11. package/dist/browser/chunk-JOVZ6HMT.mjs +4358 -0
  12. package/dist/browser/chunk-JPTQZWJQ.mjs +10 -0
  13. package/dist/browser/chunk-KPJMDPHG.mjs +24558 -0
  14. package/dist/browser/chunk-PGIM3HIM.mjs +2743 -0
  15. package/dist/browser/chunk-RHG4O77A.mjs +206 -0
  16. package/dist/browser/chunk-RIJSLY2I.mjs +360 -0
  17. package/dist/browser/durability-wiring-SRUYT3VV.mjs +3875 -0
  18. package/dist/browser/module-CBB2ETYP.mjs +3111 -0
  19. package/dist/browser/release-76MXRPGV.mjs +33 -0
  20. package/dist/browser/replace-RURXTGVG.mjs +57 -0
  21. package/dist/browser/restore-queue-EEZQO6RF.mjs +35 -0
  22. package/dist/browser/runtime-7ZAHCHWR.mjs +557 -0
  23. package/dist/browser/snapshot-OAAA5UJ7.mjs +1210 -0
  24. package/dist/browser/write-7D6VIK6O.mjs +208 -0
  25. package/dist/{capabilities-DSsOGz6F.d.ts → capabilities-DiGlB6Sr.d.ts} +68 -7
  26. package/dist/chunk-2RIRGOUL.mjs +113 -0
  27. package/dist/chunk-37CD3OKS.mjs +87 -0
  28. package/dist/chunk-44W3CBNG.mjs +7 -0
  29. package/dist/chunk-46D6JQIG.mjs +426 -0
  30. package/dist/{chunk-VMRR3DQU.mjs → chunk-5JNA5SKS.mjs} +546 -35
  31. package/dist/chunk-747OHOUA.mjs +11 -0
  32. package/dist/chunk-75XIEF6H.mjs +126 -0
  33. package/dist/chunk-7X5JST5L.mjs +114 -0
  34. package/dist/chunk-BOFBLJFZ.mjs +209 -0
  35. package/dist/{chunk-USKFU7J5.mjs → chunk-BWJVNZPR.mjs} +8 -1
  36. package/dist/chunk-C7SLA6CM.mjs +19 -0
  37. package/dist/{chunk-POWOTUKJ.mjs → chunk-CQUMNIIG.mjs} +3 -6
  38. package/dist/chunk-CVXLLEQ3.mjs +1011 -0
  39. package/dist/chunk-DJHHF2L5.mjs +17 -0
  40. package/dist/chunk-E74YLAIG.mjs +24 -0
  41. package/dist/{chunk-UXNWQZST.mjs → chunk-EMRMGYRE.mjs} +236 -18
  42. package/dist/chunk-EWZLIYHV.mjs +57 -0
  43. package/dist/chunk-GBEEG5AN.mjs +35 -0
  44. package/dist/chunk-GES7U2PM.mjs +68 -0
  45. package/dist/chunk-HJSN7UYG.mjs +10 -0
  46. package/dist/chunk-HLPRHOSO.mjs +17 -0
  47. package/dist/chunk-HMFNFVP7.mjs +14 -0
  48. package/dist/chunk-J5QP52HA.mjs +1751 -0
  49. package/dist/{chunk-YNVIUGF5.mjs → chunk-JZVARCRZ.mjs} +3 -28
  50. package/dist/chunk-KOKM4PQN.mjs +52 -0
  51. package/dist/{chunk-B2TFROFX.mjs → chunk-KWTW6VTG.mjs} +465 -250
  52. package/dist/chunk-KZ3NX2P7.mjs +21 -0
  53. package/dist/chunk-L5ORED7V.mjs +25 -0
  54. package/dist/{chunk-THYRHHO2.mjs → chunk-LGAMKHA2.mjs} +2009 -2351
  55. package/dist/chunk-LKOB5COA.mjs +117 -0
  56. package/dist/chunk-LPQOEU5M.mjs +96 -0
  57. package/dist/{chunk-3LHGNRYE.mjs → chunk-LXWDQLTW.mjs} +7 -2
  58. package/dist/{chunk-L6TNPLAR.mjs → chunk-OEYI3KRB.mjs} +270 -108
  59. package/dist/chunk-OM362BRO.mjs +948 -0
  60. package/dist/chunk-OZDFA4WC.mjs +67 -0
  61. package/dist/chunk-P36MUFEJ.mjs +10 -0
  62. package/dist/chunk-PC2G76VW.mjs +2540 -0
  63. package/dist/{chunk-GCM3JFVA.mjs → chunk-PNEYIHA4.mjs} +11 -2
  64. package/dist/chunk-PNFKUCG3.mjs +1130 -0
  65. package/dist/chunk-Q6XWVUZX.mjs +44 -0
  66. package/dist/chunk-R27EMH5M.mjs +617 -0
  67. package/dist/{chunk-YMZCMH5M.mjs → chunk-R6A773WK.mjs} +19 -24
  68. package/dist/chunk-RF7PLG43.mjs +106 -0
  69. package/dist/chunk-RFBLQLLZ.mjs +16 -0
  70. package/dist/{chunk-Y3L5MDRV.mjs → chunk-RFVUDM5E.mjs} +17 -2
  71. package/dist/chunk-S7FL6UAH.mjs +521 -0
  72. package/dist/chunk-S7GNDRPS.mjs +651 -0
  73. package/dist/chunk-SP3NM3ZG.mjs +3537 -0
  74. package/dist/chunk-U476IXKQ.mjs +10 -0
  75. package/dist/chunk-UA3AUGNV.mjs +462 -0
  76. package/dist/chunk-UTG5YNXV.mjs +507 -0
  77. package/dist/chunk-VI4R6W25.mjs +8484 -0
  78. package/dist/chunk-WQBCBKY3.mjs +8 -0
  79. package/dist/{chunk-24RXHMEL.mjs → chunk-WVCOCKBU.mjs} +3794 -7570
  80. package/dist/chunk-X5CV2E2B.mjs +1 -0
  81. package/dist/chunk-XADZPPZI.mjs +614 -0
  82. package/dist/chunk-YEEQHT4V.mjs +212 -0
  83. package/dist/chunk-YTJCGKM4.mjs +56 -0
  84. package/dist/chunk-YYQIODMF.mjs +275 -0
  85. package/dist/chunk-ZI34TVOA.mjs +144 -0
  86. package/dist/{chunk-OOSIDHA3.mjs → chunk-ZKWYWW4Y.mjs} +1 -1
  87. package/dist/chunk-ZM7KU4YW.mjs +35 -0
  88. package/dist/{client-BQK6Tf6A.d.ts → client-BOStAkc5.d.ts} +160 -37
  89. package/dist/client.d.ts +11 -10
  90. package/dist/client.mjs +209 -45
  91. package/dist/{config-DmXULPa-.d.ts → config-Cjvzbs_j.d.ts} +51 -3
  92. package/dist/config-DffQlmRq.d.ts +421 -0
  93. package/dist/direct-executor-ZD64PPEZ.mjs +24 -0
  94. package/dist/distribution/coordinator/etcd.d.ts +79 -18
  95. package/dist/distribution/coordinator/etcd.mjs +553 -109
  96. package/dist/distribution/coordinator/in-memory.d.ts +4 -3
  97. package/dist/distribution/coordinator/in-memory.mjs +22 -3
  98. package/dist/distribution/transport/grpc.d.ts +2 -2
  99. package/dist/distribution/transport/grpc.mjs +79 -14
  100. package/dist/distribution/transport/in-memory.d.ts +2 -2
  101. package/dist/distribution/transport/in-memory.mjs +12 -7
  102. package/dist/distribution/transport/tcp.d.ts +2 -2
  103. package/dist/distribution/transport/tcp.mjs +50 -28
  104. package/dist/distribution.d.ts +144 -23
  105. package/dist/distribution.mjs +14479 -8173
  106. package/dist/durability-wiring-FEUBR5BT.mjs +3330 -0
  107. package/dist/embeddings/openai.d.ts +2 -2
  108. package/dist/embeddings/openai.mjs +22 -133
  109. package/dist/{engine-CIOyFozK.d.ts → engine-rC0vjjY-.d.ts} +165 -141
  110. package/dist/{memory-yFaVn2xZ.d.ts → events-DqOIg5xa.d.ts} +645 -136
  111. package/dist/{types-DAK7mnUZ.d.ts → index-Bkdt8nDw.d.ts} +182 -45
  112. package/dist/index.browser.mjs +4 -32180
  113. package/dist/index.d.ts +91 -20
  114. package/dist/index.mjs +33 -16
  115. package/dist/invalidation/broadcast-channel.d.ts +1 -1
  116. package/dist/invalidation/filesystem.d.ts +1 -1
  117. package/dist/invalidation/filesystem.mjs +2 -1
  118. package/dist/invalidation/noop.d.ts +1 -1
  119. package/dist/module-3S65MVCM.mjs +2151 -0
  120. package/dist/partial-words-DTIHO8G4.d.ts +19 -0
  121. package/dist/partial-words.d.ts +22 -0
  122. package/dist/partial-words.mjs +17 -0
  123. package/dist/pattern-Cledccbl.d.ts +18 -0
  124. package/dist/pattern.d.ts +22 -0
  125. package/dist/pattern.mjs +12 -0
  126. package/dist/persistence/durability/checkpoint-worker.d.ts +119 -72
  127. package/dist/persistence/durability/checkpoint-worker.mjs +51 -18
  128. package/dist/react.d.ts +279 -183
  129. package/dist/react.mjs +201 -48
  130. package/dist/release-BH3DKW3T.mjs +33 -0
  131. package/dist/replace-CEO5KJJ3.mjs +57 -0
  132. package/dist/rerank-K7C4WZFG.mjs +60 -0
  133. package/dist/rerankers/http.d.ts +50 -0
  134. package/dist/rerankers/http.mjs +104 -0
  135. package/dist/restore-queue-KQHA7ZV2.mjs +35 -0
  136. package/dist/runtime-6Y4ZYXOG.mjs +177 -0
  137. package/dist/{schema-d5Afu03A.d.ts → schema-4W_7tk1f.d.ts} +81 -11
  138. package/dist/server.d.ts +13 -12
  139. package/dist/server.mjs +611 -80
  140. package/dist/snapshot-QGZPODM5.mjs +799 -0
  141. package/dist/synonyms-CpOAHPa-.d.ts +52 -0
  142. package/dist/synonyms.d.ts +22 -0
  143. package/dist/synonyms.mjs +12 -0
  144. package/dist/{tasks-CH2Dod8w.d.ts → tasks-CwPTz-tP.d.ts} +10 -3
  145. package/dist/thread-N3IUGUS3.mjs +697 -0
  146. package/dist/{types-BQDlIvfS.d.ts → types-2qoitTXg.d.ts} +1 -1
  147. package/dist/{types-D5OwhtsQ.d.ts → types-Cz5okLml.d.ts} +2 -2
  148. package/dist/vector/search-worker.d.ts +46 -4
  149. package/dist/vector/search-worker.mjs +21 -11
  150. package/dist/workers/entry.mjs +9 -6
  151. package/dist/write-U5RI7MAX.mjs +241 -0
  152. package/package.json +55 -9
  153. package/dist/chunk-3L4U6EJQ.mjs +0 -49
  154. package/dist/chunk-IFBKLBGB.mjs +0 -7
  155. package/dist/chunk-ORBLD3EL.mjs +0 -6
  156. package/dist/chunk-U7KYW4BA.mjs +0 -135
  157. package/dist/chunk-ZJ4CSAB2.mjs +0 -13
  158. package/dist/chunk-ZNZBXMP5.mjs +0 -2117
  159. package/dist/chunk-ZZT3EAUC.mjs +0 -11168
  160. package/dist/config-BhldZgaK.d.ts +0 -194
  161. package/dist/direct-executor-ALAVE7FC.mjs +0 -12
  162. package/dist/serialization/crc32-worker.d.ts +0 -20
  163. package/dist/serialization/crc32-worker.mjs +0 -62
  164. package/dist/simd-DW5AtJ6B.d.ts +0 -41
  165. package/dist/thread-DYHEQRVY.mjs +0 -402
@@ -0,0 +1,421 @@
1
+ import { N as NarsilConfig } from './config-Cjvzbs_j.js';
2
+ import { A as AllocationTable, N as NodeRole, a as NodeRegistration, C as ClusterCoordinator, b as NodeCapacity } from './index-Bkdt8nDw.js';
3
+ import { N as NodeTransport } from './types-Cz5okLml.js';
4
+
5
+ /**
6
+ * How much replication history a primary keeps, and how many replicas have to
7
+ * confirm a write before it is acknowledged.
8
+ *
9
+ * A replica that falls further behind than the retained log recovers from a
10
+ * whole snapshot instead of replaying entries, so a larger retention trades
11
+ * memory for cheaper recovery.
12
+ *
13
+ * @public
14
+ */
15
+ interface ReplicationConfig {
16
+ /** A primary keeps this many bytes of replication log before it drops the oldest entries. */
17
+ logRetentionBytes: number;
18
+ /** This many replicas must acknowledge a write before the primary reports it as done. */
19
+ waitForActiveReplicas: number;
20
+ }
21
+
22
+ /**
23
+ * How well the cluster holds an index, or the whole cluster, from the best status to the worst.
24
+ *
25
+ * `green` means every partition is `ACTIVE` with a primary and `replicationFactor` in-sync replicas. `yellow` means
26
+ * every partition has a primary but some partition holds fewer in-sync replicas. `red` means some partition has no
27
+ * primary, so the documents that it holds can be neither read nor written. A primary or a replica counts only while
28
+ * its node stays registered with the coordinator, because a copy on a node that has left serves nothing.
29
+ *
30
+ * @public
31
+ */
32
+ type ClusterHealthStatus = 'green' | 'yellow' | 'red';
33
+ /**
34
+ * How well the cluster holds one index.
35
+ *
36
+ * @public
37
+ */
38
+ interface IndexHealth {
39
+ /** The index that the cluster holds. */
40
+ indexName: string;
41
+ /** The status of the index, which its weakest partition sets. */
42
+ status: ClusterHealthStatus;
43
+ /** The number of partitions that the index has. */
44
+ partitionCount: number;
45
+ /** The number of in-sync replicas besides the primary that each partition should keep. */
46
+ replicationFactor: number;
47
+ /** The number of partitions that have no primary. */
48
+ partitionsWithoutPrimary: number;
49
+ /** The number of partitions that have a primary but are not `ACTIVE` or hold fewer in-sync replicas than the factor. */
50
+ underReplicatedPartitions: number;
51
+ }
52
+ /**
53
+ * How well the cluster holds every index that it serves.
54
+ *
55
+ * @public
56
+ */
57
+ interface ClusterHealth {
58
+ /** The worst status of any index, or `green` for a cluster that holds no index. */
59
+ status: ClusterHealthStatus;
60
+ /** One entry per index, sorted by name. */
61
+ indexes: IndexHealth[];
62
+ }
63
+ /**
64
+ * How far one replica trails the primary of its partition.
65
+ *
66
+ * @public
67
+ */
68
+ interface ReplicaLagFigure {
69
+ /** The index that the partition belongs to. */
70
+ indexName: string;
71
+ /** The partition within that index. */
72
+ partitionId: number;
73
+ /** The node that holds the replica. */
74
+ replica: string;
75
+ /** The primary's last sequence number minus the highest sequence number that the replica acknowledged. */
76
+ lag: number;
77
+ }
78
+ /**
79
+ * What the allocation table records for one partition.
80
+ *
81
+ * @public
82
+ */
83
+ interface PartitionReplicationFigure {
84
+ /** The index that the partition belongs to. */
85
+ indexName: string;
86
+ /** The partition within that index. */
87
+ partitionId: number;
88
+ /**
89
+ * The floor on the commit point that the allocation table stores, which the controller raises only when it admits
90
+ * a replica, so it can trail the commit point of the partition's leader by many writes.
91
+ */
92
+ commitPointFloor: number;
93
+ /** The number of replicas besides the primary that are in the in-sync set. */
94
+ inSyncReplicas: number;
95
+ }
96
+ /**
97
+ * The live commit point of one partition that this node leads.
98
+ *
99
+ * @public
100
+ */
101
+ interface CommitPointFigure {
102
+ /** The index that the partition belongs to. */
103
+ indexName: string;
104
+ /** The partition within that index. */
105
+ partitionId: number;
106
+ /** The highest sequence number that this node has acknowledged to a client for the partition. */
107
+ commitPoint: number;
108
+ }
109
+ /**
110
+ * How long this node's calls to the coordinator took, for one kind of call.
111
+ *
112
+ * @public
113
+ */
114
+ interface CoordinatorRequestFigure {
115
+ /** The coordinator method that the node called, such as `getAllocation`. */
116
+ operation: string;
117
+ /** The upper bound of each bucket in seconds, in ascending order. */
118
+ bucketBoundsSeconds: number[];
119
+ /** The number of calls that took no longer than each bound, so each count includes the ones before it. */
120
+ bucketCounts: number[];
121
+ /** The number of calls, including those slower than every bound. */
122
+ count: number;
123
+ /** The total time that the calls took, in seconds. */
124
+ sumSeconds: number;
125
+ }
126
+ /**
127
+ * The replication and coordinator figures that one node reports.
128
+ *
129
+ * @public
130
+ */
131
+ interface ClusterMetrics {
132
+ /** The lag of each replica of each partition that this node leads. */
133
+ replicationLag: ReplicaLagFigure[];
134
+ /** The live commit point of each partition that this node leads. */
135
+ commitPoints: CommitPointFigure[];
136
+ /** The stored commit point floor and the in-sync replica count of every partition in the cluster. */
137
+ partitions: PartitionReplicationFigure[];
138
+ /** The timing of this node's coordinator calls, one entry per kind of call that the node has made. */
139
+ coordinatorRequests: CoordinatorRequestFigure[];
140
+ }
141
+
142
+ /**
143
+ * Everything {@link createClusterNode} needs to join a node to a cluster.
144
+ *
145
+ * The coordinator and the transport are the two pieces you choose: the
146
+ * coordinator holds the cluster's shared state, and the transport carries
147
+ * messages between nodes.
148
+ *
149
+ * @public
150
+ */
151
+ interface ClusterNodeConfig {
152
+ /** This node reads and writes the cluster's shared state here. Every node in a cluster must point at the same one. */
153
+ coordinator: ClusterCoordinator;
154
+ /** This node reaches its peers through this transport. */
155
+ transport: NodeTransport;
156
+ /** Peers reach this node at this address, as the transport writes it. */
157
+ address: string;
158
+ /** This node holds these roles in the cluster, and holds data alone by default. */
159
+ roles?: NodeRole[];
160
+ /**
161
+ * This identifies the node across the cluster. Where you leave it out, a node
162
+ * with a durability directory generates an id once, stores it in that
163
+ * directory, and reuses it on every later start, so that the controller
164
+ * recognises the copies that the node holds after a restart. A node without a
165
+ * durability directory takes a new id on every start.
166
+ */
167
+ nodeId?: string;
168
+ /** This node offers this much capacity, which the allocator weighs. It offers {@link DEFAULT_CAPACITY} by default. */
169
+ capacity?: NodeCapacity;
170
+ /**
171
+ * These settings configure the engine this node runs locally, such as its persistence and durability.
172
+ *
173
+ * 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
174
+ * in memory. The copy goes into a `.snapshot-transfer` directory inside the durability directory, or into the
175
+ * system's temporary directory when the engine has no durability directory, and the node deletes it once the
176
+ * transfer ends.
177
+ */
178
+ engine?: NarsilConfig;
179
+ /** These replication settings override the engine's own, and anything you leave out keeps its value. */
180
+ replication?: Partial<ReplicationConfig>;
181
+ /** These settings govern how this node gathers each search from the cluster, and anything you leave out keeps its default. */
182
+ query?: ClusterQueryConfig;
183
+ /** These settings govern how this node stands for controller election, and anything you leave out keeps its default. */
184
+ controller?: ClusterControllerConfig;
185
+ /** These settings govern when this node's memory blocks writes across the cluster, and anything you leave out keeps its default. */
186
+ memory?: ClusterMemoryConfig;
187
+ /** This receives the failures the node reports while running on its own, away from any call you made. */
188
+ onError?: (error: Error) => void;
189
+ }
190
+ /**
191
+ * When this node counts as full, which is what makes the cluster refuse inserts and updates to every index with a
192
+ * copy on the node.
193
+ *
194
+ * The node measures its process memory against the container's limit, or the host's memory where no container sets
195
+ * one, and its main thread's heap against the heap limit, once a second. It counts as full once either figure passes
196
+ * `blockWritesAbove` of its limit, and as clear again once both fall below `resumeWritesBelow`, so that a node hovering
197
+ * at the threshold does not switch writes on and off. Removes and searches go through while the node is full, which is
198
+ * how an operator frees memory.
199
+ *
200
+ * @public
201
+ */
202
+ interface ClusterMemoryConfig {
203
+ /**
204
+ * The node counts as full once either memory figure passes this fraction of its limit. It must lie above
205
+ * `resumeWritesBelow` and at most 1, and it is 0.9 where you name none.
206
+ *
207
+ * The node compares its heap with the smaller of this setting and 0.75. V8, the engine that runs Node.js, stops the
208
+ * process after four full collections in a row that each leave the old generation holding at least 0.8 of its limit,
209
+ * so a full node keeps its heap below that line. The node compares its resident memory with the setting as it is.
210
+ */
211
+ blockWritesAbove?: number;
212
+ /**
213
+ * A full node counts as clear again once both memory figures fall below this fraction of their limits. It must lie
214
+ * above 0 and below `blockWritesAbove`, and it is 0.8 where you name none.
215
+ *
216
+ * The node compares its heap with the smaller of this setting and 0.65, for the same V8 rule that caps the heap side
217
+ * of `blockWritesAbove` at 0.75. The node compares its resident memory with the setting as it is.
218
+ */
219
+ resumeWritesBelow?: number;
220
+ /**
221
+ * The node holds at most this fraction of its heap limit in the documents of inserts and updates that it has
222
+ * accepted and not yet finished, counting both the writes that clients send it and the writes that other nodes
223
+ * forward to it as primary. It refuses a write whose documents would carry that total past the limit with
224
+ * `CLUSTER_WRITE_BLOCKED`, and the error's details include the reason `write_bytes_in_flight`. It accepts a write
225
+ * of any size when no other insert or update is in progress, and it never refuses a replicated entry or a remove. The fraction must lie above 0 and at most 1, and it is 0.02 where you name none,
226
+ * which is low because indexing a document can take many times the size of its text in heap. A value of 1 allows
227
+ * writes in flight up to the whole heap limit.
228
+ */
229
+ inFlightWriteFraction?: number;
230
+ }
231
+ /**
232
+ * How long this node's turn as controller survives a fault, and how often it
233
+ * stands for election again.
234
+ *
235
+ * A cluster fails over no faster than the lease it grants the controller, so a
236
+ * demonstration lowers both figures and a busy cluster leaves them alone. Every
237
+ * controller-capable node in a cluster should carry the same pair.
238
+ *
239
+ * @public
240
+ */
241
+ interface ClusterControllerConfig {
242
+ /**
243
+ * The controller lease survives this many milliseconds without a renewal, so
244
+ * a controller that loses the coordinator keeps its claim for that long. The
245
+ * active controller renews the lease every third of this, and a standby takes
246
+ * the lease over up to {@link ClusterControllerConfig.standbyRetryMs} after it
247
+ * expires. It is 15000 milliseconds where you name none.
248
+ */
249
+ leaseTtlMs?: number;
250
+ /**
251
+ * A node that holds no lease stands for election again after this many
252
+ * milliseconds, whether the lease was taken or the coordinator refused the
253
+ * attempt. It is 5000 milliseconds where you name none.
254
+ */
255
+ standbyRetryMs?: number;
256
+ /**
257
+ * The controller waits this many milliseconds after a data node leaves
258
+ * before it moves that node's replicas to other nodes, which is 60000
259
+ * milliseconds where you set none. It promotes a replica at once for every
260
+ * partition that the node led, and a node that registers again under the
261
+ * same node id within this time keeps its replicas and catches up on the
262
+ * writes that it missed. Set 0 to move the replicas as soon as the node
263
+ * leaves.
264
+ */
265
+ nodeLeftDelayMs?: number;
266
+ }
267
+ /**
268
+ * How this node answers a search when one of the nodes it asked runs slowly or
269
+ * drops out.
270
+ *
271
+ * The defaults let a search answer from the nodes that did reply, so set
272
+ * `allowPartialResults` to false where a caller must never act on an
273
+ * incomplete count. Every search reports what it read in
274
+ * {@link QueryResult.coverage} whichever way you set these.
275
+ *
276
+ * @public
277
+ */
278
+ interface ClusterQueryConfig {
279
+ /**
280
+ * Set this true and a search returns the hits the reachable nodes gave,
281
+ * counting the rest in {@link QueryResult.coverage}, which is what a node
282
+ * does by default. Set it false, and a partition that times out or errors on
283
+ * every copy, or that has no active copy, fails the whole search with
284
+ * `QUERY_PARTIAL_FAILURE`.
285
+ */
286
+ allowPartialResults?: boolean;
287
+ /**
288
+ * A search waits this many milliseconds for each copy that it asks, and it
289
+ * asks the next in-sync copy of a partition once that wait runs out. The
290
+ * search counts the partition as timed out only when every copy has timed
291
+ * out, and the wait is 5000 milliseconds where you set none.
292
+ */
293
+ partitionTimeout?: number;
294
+ }
295
+ /**
296
+ * How an index is spread across the cluster when a node creates it.
297
+ *
298
+ * @public
299
+ */
300
+ interface CreateIndexOptions {
301
+ /** The cluster splits the index into this many partitions, and into {@link DEFAULT_PARTITION_COUNT} by default. */
302
+ partitionCount?: number;
303
+ /**
304
+ * The cluster keeps this many replicas of each partition besides its primary, and
305
+ * {@link DEFAULT_REPLICATION_FACTOR} by default.
306
+ */
307
+ replicationFactor?: number;
308
+ /**
309
+ * The creation returns once every partition is in service or once this many milliseconds have passed, which is
310
+ * 30000 where you name none. It returns either way, so a write sent after the deadline may be refused with
311
+ * `QUERY_ROUTING_FAILED` while the controller is still allocating. Pass 0 to return as soon as the schema is
312
+ * published.
313
+ */
314
+ waitForServingMs?: number;
315
+ }
316
+ /**
317
+ * Where a node stands between starting and shutting down, which is what a
318
+ * readiness probe reads.
319
+ *
320
+ * A node reports `STARTING` until it holds a registration. It reports
321
+ * `JOINING` while it bootstraps a partition the controller gave it, and
322
+ * `SERVING` once it serves every one of them. It reports `LEAVING` from the
323
+ * moment shutdown begins.
324
+ *
325
+ * @public
326
+ */
327
+ type NodeReadiness = 'STARTING' | 'JOINING' | 'SERVING' | 'LEAVING';
328
+ /**
329
+ * The cluster-facing side of a node, which is where you look at the cluster
330
+ * rather than at the data.
331
+ *
332
+ * @public
333
+ */
334
+ interface ClusterNamespace {
335
+ /**
336
+ * Reads how one index is spread across the cluster.
337
+ *
338
+ * After a change of the partition count, this returns the table of the layout that serves the index, carrying the
339
+ * index name that you passed.
340
+ *
341
+ * @param indexName - The index to describe.
342
+ * @returns Its allocation, or `null` when the index has none yet.
343
+ */
344
+ getAllocation(indexName: string): Promise<AllocationTable | null>;
345
+ /**
346
+ * Describes this node.
347
+ *
348
+ * @returns Its id, its roles, and where it stands.
349
+ */
350
+ getNodeInfo(): ClusterNodeInfo;
351
+ /**
352
+ * Reports whether this node is the cluster's active controller, which is the
353
+ * one node making allocation decisions.
354
+ *
355
+ * @returns True while this node holds the controller lease.
356
+ */
357
+ isControllerActive(): boolean;
358
+ /**
359
+ * Reports whether this node serves work, which is what a readiness probe
360
+ * answers with.
361
+ *
362
+ * @returns The node's readiness as it stands.
363
+ */
364
+ getReadiness(): NodeReadiness;
365
+ /**
366
+ * Lists the nodes the coordinator holds a registration for.
367
+ *
368
+ * @returns One registration per node, as each node published it.
369
+ */
370
+ listNodes(): Promise<NodeRegistration[]>;
371
+ /**
372
+ * Names the node holding the controller lease.
373
+ *
374
+ * @returns Its id, or `null` while no node holds the lease.
375
+ */
376
+ getControllerNodeId(): Promise<string | null>;
377
+ /**
378
+ * Changes how many replicas besides its primary each partition of an index keeps.
379
+ *
380
+ * The node sends the change to the active controller, which stores the factor in the index metadata and writes an
381
+ * allocation table that carries it before this call returns. A higher factor adds replicas, and each new copy
382
+ * catches up from its primary. A lower factor removes the surplus replicas, lagging ones first, and never the
383
+ * primary.
384
+ *
385
+ * @param indexName - The index to change.
386
+ * @param replicationFactor - The number of replicas besides the primary, an integer from 0 to 255.
387
+ * @returns A promise that settles once the controller has stored the factor and written the table.
388
+ * @throws A `NarsilError` with `CONFIG_INVALID` for a factor outside that range, with `INDEX_NOT_FOUND` where the
389
+ * cluster holds no index of that name, and with `NODE_NOT_CONTROLLER` while no node holds the controller lease.
390
+ */
391
+ setReplicationFactor(indexName: string, replicationFactor: number): Promise<void>;
392
+ /**
393
+ * Reports how well the cluster holds each index, from the allocation tables in the coordinator.
394
+ *
395
+ * @returns The status of each index and the worst of them as the status of the cluster.
396
+ */
397
+ getHealth(): Promise<ClusterHealth>;
398
+ /**
399
+ * Reports the replication lag and the live commit point of each partition that this node leads, the stored commit
400
+ * point floor and in-sync replica count of every partition in the cluster, and the timing of this node's
401
+ * coordinator calls.
402
+ *
403
+ * @returns The figures as they stand when the call reads them.
404
+ */
405
+ getMetrics(): Promise<ClusterMetrics>;
406
+ }
407
+ /**
408
+ * What one node reports about itself.
409
+ *
410
+ * @public
411
+ */
412
+ interface ClusterNodeInfo {
413
+ /** This identifies the node across the cluster. */
414
+ nodeId: string;
415
+ /** The node holds these roles in the cluster. */
416
+ roles: ReadonlyArray<NodeRole>;
417
+ /** This says where the node stands, from joining through to shut down. */
418
+ status: string;
419
+ }
420
+
421
+ export type { ClusterNamespace as C, IndexHealth as I, NodeReadiness as N, PartitionReplicationFigure as P, ReplicaLagFigure as R, CreateIndexOptions as a, ClusterNodeConfig as b, ClusterControllerConfig as c, ClusterHealth as d, ClusterHealthStatus as e, ClusterMemoryConfig as f, ClusterMetrics as g, ClusterNodeInfo as h, ClusterQueryConfig as i, CommitPointFigure as j, CoordinatorRequestFigure as k, ReplicationConfig as l };
@@ -0,0 +1,24 @@
1
+ export { createDirectExecutor } from './chunk-SP3NM3ZG.mjs';
2
+ import './chunk-VI4R6W25.mjs';
3
+ import './chunk-ZM7KU4YW.mjs';
4
+ import './chunk-LPQOEU5M.mjs';
5
+ import './chunk-TGP5M5R7.mjs';
6
+ import './chunk-U2BKYEC7.mjs';
7
+ import './chunk-PC2G76VW.mjs';
8
+ import './chunk-WQBCBKY3.mjs';
9
+ import './chunk-OM362BRO.mjs';
10
+ import './chunk-OEYI3KRB.mjs';
11
+ import './chunk-U476IXKQ.mjs';
12
+ import './chunk-E74YLAIG.mjs';
13
+ import './chunk-HMFNFVP7.mjs';
14
+ import './chunk-GES7U2PM.mjs';
15
+ import './chunk-LKOB5COA.mjs';
16
+ import './chunk-46D6JQIG.mjs';
17
+ import './chunk-X5CV2E2B.mjs';
18
+ import './chunk-7X5JST5L.mjs';
19
+ import './chunk-UTG5YNXV.mjs';
20
+ import './chunk-R6A773WK.mjs';
21
+ import './chunk-YTJCGKM4.mjs';
22
+ import './chunk-Q6XWVUZX.mjs';
23
+ import './chunk-L5ORED7V.mjs';
24
+ import './chunk-BWJVNZPR.mjs';
@@ -1,20 +1,68 @@
1
- import { C as ClusterCoordinator } from '../../types-DAK7mnUZ.js';
2
- import '../../schema-d5Afu03A.js';
3
- import '../../adapters-79OIa4xm.js';
1
+ import { C as ClusterCoordinator } from '../../index-Bkdt8nDw.js';
2
+ import '../../schema-4W_7tk1f.js';
3
+ import '../../adapters-BQFQ4PRz.js';
4
+ import '../../synonyms-CpOAHPa-.js';
4
5
 
5
6
  /**
6
- * How {@link createEtcdCoordinator} reaches etcd, and how long a node's
7
- * registration survives there.
7
+ * The certificates that {@link createEtcdCoordinator} uses to reach etcd over
8
+ * TLS.
9
+ *
10
+ * @public
11
+ */
12
+ interface EtcdTlsConfig {
13
+ /** The coordinator trusts an etcd member only where its certificate chains to this authority, in PEM form. */
14
+ ca: Buffer | string;
15
+ /** The coordinator presents this client certificate, in PEM form, to an etcd that asks for one. Set it together with `key`. */
16
+ cert?: Buffer | string;
17
+ /** The private key that matches `cert`, in PEM form. */
18
+ key?: Buffer | string;
19
+ }
20
+ /**
21
+ * The etcd user that {@link createEtcdCoordinator} signs in as.
22
+ *
23
+ * @public
24
+ */
25
+ interface EtcdAuthConfig {
26
+ /** The coordinator signs in under this etcd user name. */
27
+ username: string;
28
+ /** The password of that etcd user. */
29
+ password: string;
30
+ }
31
+ /**
32
+ * Configures where {@link createEtcdCoordinator} connects, how long etcd keeps
33
+ * a node's registration, and how large a request the coordinator sends.
8
34
  *
9
35
  * @public
10
36
  */
11
37
  interface EtcdCoordinatorConfig {
12
38
  /** The coordinator connects to these etcd endpoints. */
13
39
  endpoints: string[];
14
- /** The coordinator writes every key under this prefix, which lets one etcd cluster hold several Narsil clusters. */
40
+ /** The coordinator writes every key under this prefix, so that one etcd cluster can store several Narsil clusters. */
15
41
  keyPrefix: string;
16
- /** A node's registration survives this many seconds without a heartbeat, after which peers treat the node as gone. */
42
+ /** etcd keeps a node's registration for this many seconds without a heartbeat, after which peers count the node as gone. */
17
43
  nodeHeartbeatTtlSeconds: number;
44
+ /**
45
+ * The coordinator sends etcd requests of at most this many bytes, so set it
46
+ * to the `--max-request-bytes` value of every etcd member. The default of
47
+ * 1,572,864 matches the etcd default. The coordinator raises
48
+ * `CONFIG_INVALID` for a write whose request would be larger, and for a
49
+ * write that etcd reports as too large. When this value is more than
50
+ * 524,288 bytes above the etcd setting, a write in that gap can fail at the
51
+ * gRPC layer of etcd, after which the `etcd3` client stops sending requests
52
+ * to that member for five seconds.
53
+ */
54
+ maxRequestBytes: number;
55
+ /**
56
+ * Setting this makes the coordinator reach etcd over TLS, so every endpoint
57
+ * has to start with `https://`.
58
+ */
59
+ tls?: EtcdTlsConfig;
60
+ /**
61
+ * Setting this makes the coordinator sign in to etcd as this user. The
62
+ * coordinator sends the password over TLS, or over plain HTTP to a loopback
63
+ * address alone, so that the password never crosses a network in clear text.
64
+ */
65
+ auth?: EtcdAuthConfig;
18
66
  }
19
67
 
20
68
  /**
@@ -34,22 +82,35 @@ interface EtcdCoordinatorConfig {
34
82
  declare function validateNodeId(nodeId: string): void;
35
83
 
36
84
  /**
37
- * Builds a coordinator backed by etcd, which is what holds a cluster's shared
38
- * state across hosts and restarts.
85
+ * Builds a coordinator backed by etcd, which stores a cluster's shared state
86
+ * across hosts and restarts.
87
+ *
88
+ * etcd provides the two mechanisms that a cluster uses: leases, which expire
89
+ * once a node misses its heartbeats, and compare-and-set writes, which stop two
90
+ * controllers from writing conflicting state. Install `etcd3` alongside this
91
+ * package, because it is an optional peer dependency that this call loads on
92
+ * demand.
39
93
  *
40
- * etcd gives the coordinator what a cluster depends on: leases that expire once
41
- * a node misses its heartbeats, and compare-and-set writes that keep two
42
- * controllers from disagreeing. Install `etcd3` alongside this package,
43
- * because it is an optional peer dependency this call loads on demand.
94
+ * The call reads from etcd once before it returns, so that a wrong
95
+ * certificate, a wrong password, or an etcd that nobody can reach fails the
96
+ * call itself.
44
97
  *
45
- * @param config - Endpoints, key prefix, and heartbeat lifetime to override.
46
- * Anything you leave out keeps its default.
47
- * @returns A coordinator you pass as a cluster node's `coordinator`.
98
+ * @param config - The endpoints, key prefix, heartbeat lifetime, request
99
+ * size, TLS certificates, and etcd user to override. Every setting that you
100
+ * leave out keeps its default.
101
+ * @returns A coordinator that you pass as a cluster node's `coordinator`.
48
102
  * @throws A `NarsilError` with `COORDINATOR_DEPENDENCY_MISSING` when `etcd3`
49
- * is not installed.
103
+ * is not installed, or with `CONFIG_INVALID` when `maxRequestBytes` is not a
104
+ * whole number from 1,025 to 2,147,483,647, when `tls` sets one of `cert`
105
+ * and `key` without the other or comes with an endpoint outside `https://`,
106
+ * or when `auth` would send its password over plain HTTP to an address other
107
+ * than a loopback one. It throws with `COORDINATOR_AUTH_FAILED` when etcd
108
+ * refuses the user or the password, and with `COORDINATOR_UNAVAILABLE` when
109
+ * no endpoint answers within 10 seconds or every endpoint fails the TLS
110
+ * handshake.
50
111
  *
51
112
  * @public
52
113
  */
53
114
  declare function createEtcdCoordinator(config?: Partial<EtcdCoordinatorConfig>): Promise<ClusterCoordinator>;
54
115
 
55
- export { type EtcdCoordinatorConfig, createEtcdCoordinator, validateNodeId };
116
+ export { type EtcdAuthConfig, type EtcdCoordinatorConfig, type EtcdTlsConfig, createEtcdCoordinator, validateNodeId };