foldkit-sync 0.1.0
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.
- package/LICENSE +21 -0
- package/README.md +154 -0
- package/dist/index.d.mts +378 -0
- package/dist/index.d.mts.map +1 -0
- package/dist/index.mjs +817 -0
- package/dist/index.mjs.map +1 -0
- package/package.json +52 -0
package/dist/index.mjs
ADDED
|
@@ -0,0 +1,817 @@
|
|
|
1
|
+
import { Context, Effect, Layer, Metric, Ref, Schedule, Schema, SynchronizedRef } from "effect";
|
|
2
|
+
//#region src/indexedDb.ts
|
|
3
|
+
/** One database per document/replica; CAS prevents two tabs from sharing a writer identity. */
|
|
4
|
+
const indexedDb = async (name, factory = globalThis.indexedDB) => {
|
|
5
|
+
const database = await new Promise((resolve, reject) => {
|
|
6
|
+
const request = factory.open(name, 1);
|
|
7
|
+
request.onupgradeneeded = () => request.result.createObjectStore("replica");
|
|
8
|
+
request.onsuccess = () => resolve(request.result);
|
|
9
|
+
request.onerror = () => reject(request.error);
|
|
10
|
+
});
|
|
11
|
+
database.onversionchange = () => database.close();
|
|
12
|
+
return {
|
|
13
|
+
load: () => new Promise((resolve, reject) => {
|
|
14
|
+
const transaction = database.transaction("replica", "readonly");
|
|
15
|
+
const request = transaction.objectStore("replica").get("state");
|
|
16
|
+
transaction.oncomplete = () => resolve(request.result);
|
|
17
|
+
transaction.onabort = () => reject(transaction.error ?? /* @__PURE__ */ new Error("IndexedDB read aborted"));
|
|
18
|
+
}),
|
|
19
|
+
save: (state, expectedRevision) => new Promise((resolve, reject) => {
|
|
20
|
+
const transaction = database.transaction("replica", "readwrite", { durability: "strict" });
|
|
21
|
+
const store = transaction.objectStore("replica");
|
|
22
|
+
const request = store.get("state");
|
|
23
|
+
let conflict = false;
|
|
24
|
+
request.onsuccess = () => {
|
|
25
|
+
if ((request.result?.revision ?? null) !== expectedRevision) {
|
|
26
|
+
conflict = true;
|
|
27
|
+
transaction.abort();
|
|
28
|
+
return;
|
|
29
|
+
}
|
|
30
|
+
store.put(state, "state");
|
|
31
|
+
};
|
|
32
|
+
transaction.oncomplete = () => resolve();
|
|
33
|
+
transaction.onabort = () => reject(conflict ? /* @__PURE__ */ new Error("Replica was changed by another writer") : transaction.error ?? /* @__PURE__ */ new Error("IndexedDB write aborted"));
|
|
34
|
+
}),
|
|
35
|
+
close: () => database.close()
|
|
36
|
+
};
|
|
37
|
+
};
|
|
38
|
+
//#endregion
|
|
39
|
+
//#region src/errors.ts
|
|
40
|
+
/** The persisted storage could not be read or written. */
|
|
41
|
+
var StorageError = class extends Schema.TaggedError()("StorageError", {
|
|
42
|
+
message: Schema.String,
|
|
43
|
+
cause: Schema.optional(Schema.Unknown)
|
|
44
|
+
}) {};
|
|
45
|
+
/** The storage holds a different replica's state. */
|
|
46
|
+
var WrongReplicaStorageError = class extends Schema.TaggedError()("WrongReplicaStorageError", {
|
|
47
|
+
documentId: Schema.String,
|
|
48
|
+
replicaId: Schema.String,
|
|
49
|
+
message: Schema.String
|
|
50
|
+
}) {};
|
|
51
|
+
/** The persisted replica history is internally inconsistent. */
|
|
52
|
+
var InvalidReplicaHistoryError = class extends Schema.TaggedError()("InvalidReplicaHistoryError", {
|
|
53
|
+
message: Schema.String,
|
|
54
|
+
cause: Schema.optional(Schema.Unknown)
|
|
55
|
+
}) {};
|
|
56
|
+
/** A persisted pending operation could not have been produced by this replica. */
|
|
57
|
+
var InvalidOutboxError = class extends Schema.TaggedError()("InvalidOutboxError", { message: Schema.String }) {};
|
|
58
|
+
/** The server sent a checkpoint older than the replica's cursor. */
|
|
59
|
+
var CheckpointRegressionError = class extends Schema.TaggedError()("CheckpointRegressionError", {
|
|
60
|
+
cursor: Schema.Number,
|
|
61
|
+
checkpointCursor: Schema.Number,
|
|
62
|
+
message: Schema.String
|
|
63
|
+
}) {};
|
|
64
|
+
/** Committed operations were not contiguous from the replica's cursor. */
|
|
65
|
+
var CommittedOrderError = class extends Schema.TaggedError()("CommittedOrderError", {
|
|
66
|
+
expected: Schema.Number,
|
|
67
|
+
actual: Schema.Number,
|
|
68
|
+
message: Schema.String
|
|
69
|
+
}) {};
|
|
70
|
+
/** The server rejected an operation the replica never sent. */
|
|
71
|
+
var ForeignRejectionError = class extends Schema.TaggedError()("ForeignRejectionError", {
|
|
72
|
+
opId: Schema.String,
|
|
73
|
+
message: Schema.String
|
|
74
|
+
}) {};
|
|
75
|
+
/** The replica was closed while work was still being submitted. */
|
|
76
|
+
var ReplicaClosedError = class extends Schema.TaggedError()("ReplicaClosedError", { message: Schema.String }) {};
|
|
77
|
+
//#endregion
|
|
78
|
+
//#region src/lww.ts
|
|
79
|
+
/** A logical write time; replica ids break concurrent ties using UTF-16 order. */
|
|
80
|
+
const Stamp = Schema.Struct({
|
|
81
|
+
counter: Schema.Number.check(Schema.isInt(), Schema.isGreaterThanOrEqualTo(0), Schema.isLessThanOrEqualTo(Number.MAX_SAFE_INTEGER)),
|
|
82
|
+
replicaId: Schema.NonEmptyString
|
|
83
|
+
});
|
|
84
|
+
const ClockState = Schema.Struct({
|
|
85
|
+
schemaVersion: Schema.Literal(1),
|
|
86
|
+
documentId: Schema.NonEmptyString,
|
|
87
|
+
replicaId: Stamp.fields.replicaId,
|
|
88
|
+
revision: Stamp.fields.counter
|
|
89
|
+
});
|
|
90
|
+
const decodeClock = Schema.decodeUnknownSync(ClockState, { onExcessProperty: "error" });
|
|
91
|
+
const decodeCounter = Schema.decodeUnknownSync(Stamp.fields.counter);
|
|
92
|
+
/** Opens a durable clock in its own storage, taking ownership even if opening fails. */
|
|
93
|
+
const openLwwClock = async ({ documentId, replicaId, storage }) => {
|
|
94
|
+
let state;
|
|
95
|
+
try {
|
|
96
|
+
const initial = decodeClock({
|
|
97
|
+
schemaVersion: 1,
|
|
98
|
+
documentId,
|
|
99
|
+
replicaId,
|
|
100
|
+
revision: 0
|
|
101
|
+
});
|
|
102
|
+
const saved = await storage.load();
|
|
103
|
+
state = saved === void 0 ? initial : decodeClock(saved);
|
|
104
|
+
if (state.documentId !== documentId || state.replicaId !== replicaId) throw new Error("Wrong clock storage");
|
|
105
|
+
if (saved === void 0) await storage.save(state, null);
|
|
106
|
+
} catch (error) {
|
|
107
|
+
storage.close();
|
|
108
|
+
throw error;
|
|
109
|
+
}
|
|
110
|
+
let tail = Promise.resolve();
|
|
111
|
+
let closing;
|
|
112
|
+
return {
|
|
113
|
+
next: (observedCounter = 0) => {
|
|
114
|
+
if (closing !== void 0) return Promise.reject(/* @__PURE__ */ new Error("Clock is closed"));
|
|
115
|
+
const allocation = tail.then(async () => {
|
|
116
|
+
const next = decodeClock({
|
|
117
|
+
...state,
|
|
118
|
+
revision: Math.max(state.revision, decodeCounter(observedCounter)) + 1
|
|
119
|
+
});
|
|
120
|
+
await storage.save(next, state.revision);
|
|
121
|
+
state = next;
|
|
122
|
+
return {
|
|
123
|
+
counter: next.revision,
|
|
124
|
+
replicaId
|
|
125
|
+
};
|
|
126
|
+
});
|
|
127
|
+
tail = allocation.then(() => {}, () => {});
|
|
128
|
+
return allocation;
|
|
129
|
+
},
|
|
130
|
+
close: () => closing ??= tail.then(() => storage.close())
|
|
131
|
+
};
|
|
132
|
+
};
|
|
133
|
+
/**
|
|
134
|
+
* A schema and reducer helper for a last-writer-wins register.
|
|
135
|
+
* Allocate a unique stamp per write before dispatch, and retain it in the Message.
|
|
136
|
+
* Merge is for decoded values; the application's schema validates wire input.
|
|
137
|
+
*/
|
|
138
|
+
const lwwRegister = (value) => {
|
|
139
|
+
const schema = Schema.Struct({
|
|
140
|
+
stamp: Stamp,
|
|
141
|
+
value
|
|
142
|
+
});
|
|
143
|
+
const equivalent = Schema.toEquivalence(value);
|
|
144
|
+
const merge = (left, right) => {
|
|
145
|
+
if (left.stamp.counter !== right.stamp.counter) return left.stamp.counter > right.stamp.counter ? left : right;
|
|
146
|
+
if (left.stamp.replicaId !== right.stamp.replicaId) return left.stamp.replicaId > right.stamp.replicaId ? left : right;
|
|
147
|
+
if (!equivalent(left.value, right.value)) throw new Error("Conflicting LWW write identity");
|
|
148
|
+
return left;
|
|
149
|
+
};
|
|
150
|
+
return {
|
|
151
|
+
schema,
|
|
152
|
+
merge
|
|
153
|
+
};
|
|
154
|
+
};
|
|
155
|
+
//#endregion
|
|
156
|
+
//#region src/presence.ts
|
|
157
|
+
/**
|
|
158
|
+
* Tracks ephemeral peers with a time-to-live.
|
|
159
|
+
*
|
|
160
|
+
* Nothing here touches the durable log: presence is state a peer refreshes, and
|
|
161
|
+
* a peer that stops refreshing is dropped, not replayed.
|
|
162
|
+
*/
|
|
163
|
+
const createPresence = (options) => {
|
|
164
|
+
const now = options.now ?? (() => Date.now());
|
|
165
|
+
const peers = /* @__PURE__ */ new Map();
|
|
166
|
+
const listeners = /* @__PURE__ */ new Set();
|
|
167
|
+
/** A subscriber must never fail an update. */
|
|
168
|
+
const notify = () => {
|
|
169
|
+
for (const listener of [...listeners]) try {
|
|
170
|
+
listener();
|
|
171
|
+
} catch {}
|
|
172
|
+
};
|
|
173
|
+
const expired = (peer, at) => at - peer.updatedAt > options.ttl;
|
|
174
|
+
const receive = (update) => {
|
|
175
|
+
if (update.id === options.id) return;
|
|
176
|
+
if (update.value === null) {
|
|
177
|
+
if (peers.delete(update.id)) notify();
|
|
178
|
+
return;
|
|
179
|
+
}
|
|
180
|
+
let value;
|
|
181
|
+
try {
|
|
182
|
+
value = options.decodeValue(update.value);
|
|
183
|
+
} catch {
|
|
184
|
+
return;
|
|
185
|
+
}
|
|
186
|
+
peers.set(update.id, {
|
|
187
|
+
id: update.id,
|
|
188
|
+
value,
|
|
189
|
+
updatedAt: now()
|
|
190
|
+
});
|
|
191
|
+
notify();
|
|
192
|
+
};
|
|
193
|
+
const unsubscribe = options.channel?.subscribe(receive);
|
|
194
|
+
return {
|
|
195
|
+
set: (value) => {
|
|
196
|
+
peers.set(options.id, {
|
|
197
|
+
id: options.id,
|
|
198
|
+
value,
|
|
199
|
+
updatedAt: now()
|
|
200
|
+
});
|
|
201
|
+
options.channel?.publish({
|
|
202
|
+
id: options.id,
|
|
203
|
+
value
|
|
204
|
+
});
|
|
205
|
+
notify();
|
|
206
|
+
},
|
|
207
|
+
leave: () => {
|
|
208
|
+
peers.delete(options.id);
|
|
209
|
+
options.channel?.publish({
|
|
210
|
+
id: options.id,
|
|
211
|
+
value: null
|
|
212
|
+
});
|
|
213
|
+
notify();
|
|
214
|
+
},
|
|
215
|
+
peers: () => {
|
|
216
|
+
const at = now();
|
|
217
|
+
return [...peers.values()].filter((peer) => !expired(peer, at)).map((peer) => ({ ...peer }));
|
|
218
|
+
},
|
|
219
|
+
prune: () => {
|
|
220
|
+
const at = now();
|
|
221
|
+
let changed = false;
|
|
222
|
+
for (const [id, peer] of peers) if (expired(peer, at)) {
|
|
223
|
+
peers.delete(id);
|
|
224
|
+
changed = true;
|
|
225
|
+
}
|
|
226
|
+
if (changed) notify();
|
|
227
|
+
},
|
|
228
|
+
subscribe: (listener) => {
|
|
229
|
+
listeners.add(listener);
|
|
230
|
+
return () => listeners.delete(listener);
|
|
231
|
+
},
|
|
232
|
+
close: () => {
|
|
233
|
+
unsubscribe?.();
|
|
234
|
+
listeners.clear();
|
|
235
|
+
}
|
|
236
|
+
};
|
|
237
|
+
};
|
|
238
|
+
/** An in-process channel, for tests and single-process demos. */
|
|
239
|
+
const loopbackPresenceChannel = () => {
|
|
240
|
+
const listeners = /* @__PURE__ */ new Set();
|
|
241
|
+
return {
|
|
242
|
+
publish: (update) => {
|
|
243
|
+
for (const listener of [...listeners]) try {
|
|
244
|
+
listener(update);
|
|
245
|
+
} catch {}
|
|
246
|
+
},
|
|
247
|
+
subscribe: (listener) => {
|
|
248
|
+
listeners.add(listener);
|
|
249
|
+
return () => listeners.delete(listener);
|
|
250
|
+
}
|
|
251
|
+
};
|
|
252
|
+
};
|
|
253
|
+
const createPresenceHub = () => {
|
|
254
|
+
const peers = /* @__PURE__ */ new Set();
|
|
255
|
+
return {
|
|
256
|
+
join: (send) => {
|
|
257
|
+
peers.add(send);
|
|
258
|
+
return () => peers.delete(send);
|
|
259
|
+
},
|
|
260
|
+
publish: (update) => {
|
|
261
|
+
for (const send of [...peers]) try {
|
|
262
|
+
send(update);
|
|
263
|
+
} catch {}
|
|
264
|
+
}
|
|
265
|
+
};
|
|
266
|
+
};
|
|
267
|
+
const frameType = "presence";
|
|
268
|
+
/** Decodes a presence frame, ignoring anything else a socket may carry. */
|
|
269
|
+
const decodePresence = (data) => {
|
|
270
|
+
let frame;
|
|
271
|
+
try {
|
|
272
|
+
frame = JSON.parse(data);
|
|
273
|
+
} catch {
|
|
274
|
+
return;
|
|
275
|
+
}
|
|
276
|
+
const value = frame[frameType];
|
|
277
|
+
if (typeof value !== "object" || value === null) return void 0;
|
|
278
|
+
const { id, value: payload } = value;
|
|
279
|
+
if (typeof id !== "string") return void 0;
|
|
280
|
+
return {
|
|
281
|
+
id,
|
|
282
|
+
value: payload ?? null
|
|
283
|
+
};
|
|
284
|
+
};
|
|
285
|
+
/** A presence channel carried on a socket, alongside exchange frames. */
|
|
286
|
+
const socketPresenceChannel = (socket) => ({
|
|
287
|
+
publish: (update) => socket.send(JSON.stringify({ [frameType]: update })),
|
|
288
|
+
subscribe: (listener) => socket.onMessage((data) => {
|
|
289
|
+
const update = decodePresence(data);
|
|
290
|
+
if (update !== void 0) listener(update);
|
|
291
|
+
})
|
|
292
|
+
});
|
|
293
|
+
/** Serves presence frames on an accepted socket, fanning them through the hub. */
|
|
294
|
+
const servePresence = (socket, hub) => {
|
|
295
|
+
const send = (update) => socket.send(JSON.stringify({ [frameType]: update }));
|
|
296
|
+
const leave = hub.join(send);
|
|
297
|
+
const off = socket.onMessage((data) => {
|
|
298
|
+
const update = decodePresence(data);
|
|
299
|
+
if (update !== void 0) hub.publish(update);
|
|
300
|
+
});
|
|
301
|
+
return () => {
|
|
302
|
+
off();
|
|
303
|
+
leave();
|
|
304
|
+
};
|
|
305
|
+
};
|
|
306
|
+
//#endregion
|
|
307
|
+
//#region src/transport.ts
|
|
308
|
+
/** The wire failure of a transport. A refusal is a result, not an error. */
|
|
309
|
+
var TransportError = class extends Schema.TaggedError()("SyncTransportError", { message: Schema.String }) {};
|
|
310
|
+
/**
|
|
311
|
+
* The seam the replica syncs through.
|
|
312
|
+
*
|
|
313
|
+
* A service, not a concrete client, so an application substitutes an in-process
|
|
314
|
+
* transport, a socket, or a test double without the replica knowing. A refusal
|
|
315
|
+
* arrives in the exchange result; only a wire failure is a `TransportError`.
|
|
316
|
+
*/
|
|
317
|
+
var Transport = class extends Context.Service()("foldkit-sync/Transport") {};
|
|
318
|
+
const failure = (error) => new TransportError({ message: error instanceof Error ? error.message : String(error) });
|
|
319
|
+
/** A transport backed by an in-process handler, for tests and single-process demos. */
|
|
320
|
+
const layerLoopback = (handler) => Layer.succeed(Transport, { exchange: (cursor, pending) => Effect.tryPromise({
|
|
321
|
+
try: () => Promise.resolve(handler(cursor, pending)),
|
|
322
|
+
catch: failure
|
|
323
|
+
}) });
|
|
324
|
+
/** Wraps the promise-based client the replica already speaks. */
|
|
325
|
+
const layerFromPromise = (transport) => Layer.succeed(Transport, { exchange: (cursor, pending) => Effect.tryPromise({
|
|
326
|
+
try: () => transport.exchange(cursor, pending),
|
|
327
|
+
catch: failure
|
|
328
|
+
}) });
|
|
329
|
+
/** Bridges the service back to the promise client the replica consumes. */
|
|
330
|
+
const toPromise = (transport) => ({ exchange: (cursor, pending) => Effect.runPromise(transport.exchange(cursor, pending)) });
|
|
331
|
+
/**
|
|
332
|
+
* Serves one accepted socket, answering each exchange frame.
|
|
333
|
+
*
|
|
334
|
+
* The counterpart to `layerSocket`: the handler returns the exchange result, or
|
|
335
|
+
* throws and the failure is written back as an error frame. Returns a function
|
|
336
|
+
* that stops serving.
|
|
337
|
+
*/
|
|
338
|
+
const serveSocket = (socket, options) => {
|
|
339
|
+
const send = (reply) => {
|
|
340
|
+
try {
|
|
341
|
+
socket.send(JSON.stringify(reply));
|
|
342
|
+
} catch {}
|
|
343
|
+
};
|
|
344
|
+
const stopMessage = socket.onMessage((data) => {
|
|
345
|
+
let parsed;
|
|
346
|
+
try {
|
|
347
|
+
parsed = JSON.parse(data);
|
|
348
|
+
} catch {
|
|
349
|
+
return;
|
|
350
|
+
}
|
|
351
|
+
if (typeof parsed !== "object" || parsed === null) return;
|
|
352
|
+
const { id, cursor, pending } = parsed;
|
|
353
|
+
if (typeof id !== "string") return;
|
|
354
|
+
if (typeof cursor !== "number" || !Number.isSafeInteger(cursor) || cursor < 0 || !Array.isArray(pending)) {
|
|
355
|
+
send({
|
|
356
|
+
id,
|
|
357
|
+
error: "Invalid exchange frame"
|
|
358
|
+
});
|
|
359
|
+
return;
|
|
360
|
+
}
|
|
361
|
+
const frame = {
|
|
362
|
+
id,
|
|
363
|
+
cursor,
|
|
364
|
+
pending
|
|
365
|
+
};
|
|
366
|
+
(async () => {
|
|
367
|
+
try {
|
|
368
|
+
const result = await options.exchange(frame.cursor, frame.pending);
|
|
369
|
+
send({
|
|
370
|
+
id: frame.id,
|
|
371
|
+
result
|
|
372
|
+
});
|
|
373
|
+
} catch (error) {
|
|
374
|
+
send({
|
|
375
|
+
id: frame.id,
|
|
376
|
+
error: error instanceof Error ? error.message : String(error)
|
|
377
|
+
});
|
|
378
|
+
}
|
|
379
|
+
})();
|
|
380
|
+
});
|
|
381
|
+
const stopClose = socket.onClose(() => stopMessage());
|
|
382
|
+
return () => {
|
|
383
|
+
stopMessage();
|
|
384
|
+
stopClose();
|
|
385
|
+
};
|
|
386
|
+
};
|
|
387
|
+
/** The default socket factory: the platform `WebSocket`, as a `SocketLike`. */
|
|
388
|
+
const nativeSocket = (url) => {
|
|
389
|
+
const socket = new WebSocket(url);
|
|
390
|
+
return {
|
|
391
|
+
send: (data) => socket.send(data),
|
|
392
|
+
close: () => socket.close(),
|
|
393
|
+
onOpen: (listener) => {
|
|
394
|
+
if (socket.readyState === WebSocket.OPEN) {
|
|
395
|
+
listener();
|
|
396
|
+
return () => {};
|
|
397
|
+
}
|
|
398
|
+
socket.addEventListener("open", listener);
|
|
399
|
+
return () => socket.removeEventListener("open", listener);
|
|
400
|
+
},
|
|
401
|
+
onMessage: (listener) => {
|
|
402
|
+
const handler = (event) => listener(String(event.data));
|
|
403
|
+
socket.addEventListener("message", handler);
|
|
404
|
+
return () => socket.removeEventListener("message", handler);
|
|
405
|
+
},
|
|
406
|
+
onClose: (listener) => {
|
|
407
|
+
const handler = () => listener();
|
|
408
|
+
socket.addEventListener("close", handler);
|
|
409
|
+
return () => socket.removeEventListener("close", handler);
|
|
410
|
+
}
|
|
411
|
+
};
|
|
412
|
+
};
|
|
413
|
+
/**
|
|
414
|
+
* A WebSocket client transport.
|
|
415
|
+
*
|
|
416
|
+
* One connection is live at a time. While it is connecting, exchanges queue; if
|
|
417
|
+
* it closes, the transport reconnects on an exponential, jittered backoff and
|
|
418
|
+
* re-sends every queued and in-flight frame with its original id, so a lost
|
|
419
|
+
* reply is answered rather than dropped and a late reply cannot resolve a newer
|
|
420
|
+
* frame. Once the retries are exhausted (or the layer closes) queued work fails
|
|
421
|
+
* with a `TransportError`; a queue over `maxQueue` fails new exchanges with
|
|
422
|
+
* backpressure. The socket is released when the layer's scope ends.
|
|
423
|
+
*/
|
|
424
|
+
const layerSocket = (options) => Layer.effect(Transport, Effect.gen(function* () {
|
|
425
|
+
const makeSocket = options.makeSocket ?? nativeSocket;
|
|
426
|
+
const maxQueue = options.maxQueue ?? 64;
|
|
427
|
+
const retry = Schedule.exponential(options.retryBase ?? "50 millis").pipe(Schedule.jittered, Schedule.upTo({ times: options.maxRetries ?? 5 }));
|
|
428
|
+
const queued = [];
|
|
429
|
+
const inFlight = /* @__PURE__ */ new Map();
|
|
430
|
+
let socket;
|
|
431
|
+
let ready = false;
|
|
432
|
+
let nextId = 0;
|
|
433
|
+
let disposed = false;
|
|
434
|
+
const send = (entry) => {
|
|
435
|
+
inFlight.set(entry.id, entry);
|
|
436
|
+
socket?.send(JSON.stringify({
|
|
437
|
+
id: entry.id,
|
|
438
|
+
cursor: entry.cursor,
|
|
439
|
+
pending: entry.pending
|
|
440
|
+
}));
|
|
441
|
+
};
|
|
442
|
+
const flush = () => {
|
|
443
|
+
if (socket === void 0 || !ready) return;
|
|
444
|
+
for (const entry of queued.splice(0)) send(entry);
|
|
445
|
+
};
|
|
446
|
+
const requeue = () => {
|
|
447
|
+
queued.unshift(...inFlight.values());
|
|
448
|
+
inFlight.clear();
|
|
449
|
+
};
|
|
450
|
+
const failAll = (message) => {
|
|
451
|
+
const entries = [...queued.splice(0), ...inFlight.values()];
|
|
452
|
+
inFlight.clear();
|
|
453
|
+
for (const entry of entries) entry.resume(Effect.fail(new TransportError({ message })));
|
|
454
|
+
};
|
|
455
|
+
const connect = Effect.tryPromise({
|
|
456
|
+
try: () => new Promise((resolve, reject) => {
|
|
457
|
+
const next = makeSocket(options.url);
|
|
458
|
+
socket = next;
|
|
459
|
+
ready = next.onOpen === void 0;
|
|
460
|
+
const offOpen = next.onOpen?.(() => {
|
|
461
|
+
ready = true;
|
|
462
|
+
flush();
|
|
463
|
+
});
|
|
464
|
+
const offMessage = next.onMessage((data) => {
|
|
465
|
+
let reply;
|
|
466
|
+
try {
|
|
467
|
+
reply = JSON.parse(data);
|
|
468
|
+
} catch {
|
|
469
|
+
return;
|
|
470
|
+
}
|
|
471
|
+
const entry = inFlight.get(reply.id);
|
|
472
|
+
if (entry === void 0) return;
|
|
473
|
+
inFlight.delete(reply.id);
|
|
474
|
+
entry.resume(reply.error === void 0 ? Effect.succeed(reply.result) : Effect.fail(new TransportError({ message: reply.error })));
|
|
475
|
+
});
|
|
476
|
+
const offClose = next.onClose(() => {
|
|
477
|
+
offOpen?.();
|
|
478
|
+
offMessage();
|
|
479
|
+
offClose();
|
|
480
|
+
socket = void 0;
|
|
481
|
+
ready = false;
|
|
482
|
+
requeue();
|
|
483
|
+
reject(/* @__PURE__ */ new Error("transport closed"));
|
|
484
|
+
});
|
|
485
|
+
if (ready) flush();
|
|
486
|
+
}),
|
|
487
|
+
catch: () => new TransportError({ message: "transport closed" })
|
|
488
|
+
});
|
|
489
|
+
yield* Effect.forkScoped(connect.pipe(Effect.retry(retry), Effect.catch((error) => Effect.sync(() => {
|
|
490
|
+
if (!disposed) failAll(error.message);
|
|
491
|
+
}))));
|
|
492
|
+
yield* Effect.addFinalizer(() => Effect.sync(() => {
|
|
493
|
+
disposed = true;
|
|
494
|
+
ready = false;
|
|
495
|
+
socket?.close();
|
|
496
|
+
socket = void 0;
|
|
497
|
+
failAll("transport closed");
|
|
498
|
+
}));
|
|
499
|
+
return { exchange: (cursor, pending) => Effect.callback((resume) => {
|
|
500
|
+
if (disposed) {
|
|
501
|
+
resume(Effect.fail(new TransportError({ message: "transport closed" })));
|
|
502
|
+
return;
|
|
503
|
+
}
|
|
504
|
+
if (queued.length + inFlight.size >= maxQueue) {
|
|
505
|
+
resume(Effect.fail(new TransportError({ message: "transport queue full" })));
|
|
506
|
+
return;
|
|
507
|
+
}
|
|
508
|
+
const entry = {
|
|
509
|
+
id: String(nextId++),
|
|
510
|
+
cursor,
|
|
511
|
+
pending,
|
|
512
|
+
resume
|
|
513
|
+
};
|
|
514
|
+
if (ready) send(entry);
|
|
515
|
+
else queued.push(entry);
|
|
516
|
+
}) };
|
|
517
|
+
}));
|
|
518
|
+
//#endregion
|
|
519
|
+
//#region src/sync.ts
|
|
520
|
+
const Sequence = Schema.Number.check(Schema.isInt(), Schema.isGreaterThanOrEqualTo(0), Schema.isLessThanOrEqualTo(Number.MAX_SAFE_INTEGER));
|
|
521
|
+
/** A client-authored operation envelope. `message` is the application's encoded Message. */
|
|
522
|
+
const OperationSchema = Schema.Struct({
|
|
523
|
+
protocolVersion: Schema.Literal(1),
|
|
524
|
+
schemaVersion: Schema.Literal(1),
|
|
525
|
+
documentId: Schema.NonEmptyString,
|
|
526
|
+
replicaId: Schema.NonEmptyString,
|
|
527
|
+
localSequence: Sequence,
|
|
528
|
+
opId: Schema.NonEmptyString,
|
|
529
|
+
baseCursor: Sequence,
|
|
530
|
+
message: Schema.Unknown
|
|
531
|
+
});
|
|
532
|
+
/** An operation the server committed, with its authoritative order and actor. */
|
|
533
|
+
const CommittedSchema = Schema.Struct({
|
|
534
|
+
...OperationSchema.fields,
|
|
535
|
+
serverSequence: Sequence.check(Schema.isGreaterThanOrEqualTo(1)),
|
|
536
|
+
actorId: Schema.NonEmptyString
|
|
537
|
+
});
|
|
538
|
+
const decodeOperation = Schema.decodeUnknownSync(OperationSchema, { onExcessProperty: "error" });
|
|
539
|
+
const decodeCommitted = Schema.decodeUnknownSync(CommittedSchema, { onExcessProperty: "error" });
|
|
540
|
+
/** Counters and a histogram an application can scrape. */
|
|
541
|
+
const syncMetrics = {
|
|
542
|
+
exchanges: Metric.counter("foldkit_sync_exchanges_total"),
|
|
543
|
+
applied: Metric.counter("foldkit_sync_commits_applied_total"),
|
|
544
|
+
checkpoints: Metric.counter("foldkit_sync_checkpoints_adopted_total"),
|
|
545
|
+
exchangePending: Metric.histogram("foldkit_sync_exchange_pending", { boundaries: [
|
|
546
|
+
1,
|
|
547
|
+
4,
|
|
548
|
+
16,
|
|
549
|
+
64,
|
|
550
|
+
256,
|
|
551
|
+
1024
|
|
552
|
+
] })
|
|
553
|
+
};
|
|
554
|
+
/** Keeps the storage driver's message visible on the typed failure. */
|
|
555
|
+
const storageError = (context, cause) => new StorageError({
|
|
556
|
+
message: `${context}: ${cause instanceof Error ? cause.message : String(cause)}`,
|
|
557
|
+
cause
|
|
558
|
+
});
|
|
559
|
+
/**
|
|
560
|
+
* Binds the replicated-state protocol to one application contract.
|
|
561
|
+
*
|
|
562
|
+
* The returned codecs decide what is a valid operation and what the shared
|
|
563
|
+
* projection means; the replica owns the local outbox, optimistic projection,
|
|
564
|
+
* and reconciliation as Effects, and never runs a second reducer.
|
|
565
|
+
*/
|
|
566
|
+
const defineSync = (definition) => {
|
|
567
|
+
const documentId = definition.documentId;
|
|
568
|
+
const decodeMessage = Schema.decodeUnknownSync(definition.message, { onExcessProperty: "error" });
|
|
569
|
+
const encodeMessage = Schema.encodeSync(definition.message);
|
|
570
|
+
const ReplicaStateSchema = Schema.Struct({
|
|
571
|
+
protocolVersion: Schema.Literal(1),
|
|
572
|
+
schemaVersion: Schema.Literal(1),
|
|
573
|
+
documentId: Schema.NonEmptyString,
|
|
574
|
+
replicaId: Schema.NonEmptyString,
|
|
575
|
+
revision: Sequence,
|
|
576
|
+
nextLocalSequence: Sequence,
|
|
577
|
+
cursor: Sequence,
|
|
578
|
+
committed: definition.shared,
|
|
579
|
+
committedIds: Schema.Array(Schema.String),
|
|
580
|
+
pending: Schema.Array(OperationSchema)
|
|
581
|
+
});
|
|
582
|
+
const CheckpointSchema = Schema.Struct({
|
|
583
|
+
cursor: Sequence,
|
|
584
|
+
model: definition.shared
|
|
585
|
+
});
|
|
586
|
+
const ExchangeSchema = Schema.Struct({
|
|
587
|
+
operations: Schema.Array(Schema.Unknown),
|
|
588
|
+
rejected: Schema.Array(Schema.NonEmptyString),
|
|
589
|
+
acknowledged: Schema.optional(Schema.Array(Schema.NonEmptyString)),
|
|
590
|
+
checkpoint: Schema.optional(CheckpointSchema)
|
|
591
|
+
});
|
|
592
|
+
const decodeState = Schema.decodeUnknownSync(ReplicaStateSchema, { onExcessProperty: "error" });
|
|
593
|
+
const decodeExchange = (input) => Schema.decodeUnknownSync(ExchangeSchema, { onExcessProperty: "error" })(input);
|
|
594
|
+
const checkIdentity = (operation) => {
|
|
595
|
+
if (operation.localSequence < 1 || operation.opId !== `${operation.replicaId}:${operation.localSequence}`) throw new Error("Invalid operation identity");
|
|
596
|
+
};
|
|
597
|
+
const decodeDurable = (message) => {
|
|
598
|
+
const decoded = decodeMessage(message);
|
|
599
|
+
if (!definition.durable(decoded)) throw new Error("Message is local-only");
|
|
600
|
+
return decoded;
|
|
601
|
+
};
|
|
602
|
+
const shape = (operation) => {
|
|
603
|
+
checkIdentity(operation);
|
|
604
|
+
return {
|
|
605
|
+
...operation,
|
|
606
|
+
message: encodeMessage(decodeDurable(operation.message))
|
|
607
|
+
};
|
|
608
|
+
};
|
|
609
|
+
const assertDocument = (operation, key) => {
|
|
610
|
+
if (operation.documentId !== key) throw new Error("Wrong document");
|
|
611
|
+
return operation;
|
|
612
|
+
};
|
|
613
|
+
const normalizeOperation = (input) => shape(decodeOperation(input));
|
|
614
|
+
const operationFrom = (input, key) => assertDocument(normalizeOperation(input), key);
|
|
615
|
+
/**
|
|
616
|
+
* A committed operation arrives with its message already encoded, so decode it
|
|
617
|
+
* once for the contract check and hand it to `replay` instead of decoding and
|
|
618
|
+
* re-encoding it on the way through `shape`.
|
|
619
|
+
*/
|
|
620
|
+
const decodeCommittedOperation = (input, key) => {
|
|
621
|
+
const committed = assertDocument(decodeCommitted(input), key);
|
|
622
|
+
checkIdentity(committed);
|
|
623
|
+
return {
|
|
624
|
+
committed,
|
|
625
|
+
message: decodeDurable(committed.message)
|
|
626
|
+
};
|
|
627
|
+
};
|
|
628
|
+
const committedFrom = (input, key) => decodeCommittedOperation(input, key).committed;
|
|
629
|
+
const optimistic = (state) => state.pending.reduce((model, operation) => definition.replay(model, decodeMessage(operation.message)), state.committed);
|
|
630
|
+
const openReplica = (replicaId, storage) => Effect.gen(function* () {
|
|
631
|
+
const saved = yield* Effect.tryPromise({
|
|
632
|
+
try: () => storage.load(),
|
|
633
|
+
catch: (cause) => storageError("Could not read the replica", cause)
|
|
634
|
+
});
|
|
635
|
+
const initial = {
|
|
636
|
+
protocolVersion: 1,
|
|
637
|
+
schemaVersion: 1,
|
|
638
|
+
documentId,
|
|
639
|
+
replicaId,
|
|
640
|
+
revision: 0,
|
|
641
|
+
nextLocalSequence: 1,
|
|
642
|
+
cursor: 0,
|
|
643
|
+
committed: definition.empty,
|
|
644
|
+
committedIds: [],
|
|
645
|
+
pending: []
|
|
646
|
+
};
|
|
647
|
+
const state = saved === void 0 ? initial : yield* Effect.try({
|
|
648
|
+
try: () => decodeState(saved),
|
|
649
|
+
catch: (cause) => new InvalidReplicaHistoryError({
|
|
650
|
+
message: "Stored replica state is invalid",
|
|
651
|
+
cause
|
|
652
|
+
})
|
|
653
|
+
});
|
|
654
|
+
if (state.documentId !== documentId || state.replicaId !== replicaId) return yield* new WrongReplicaStorageError({
|
|
655
|
+
documentId,
|
|
656
|
+
replicaId,
|
|
657
|
+
message: "The stored replica belongs to a different document or replica"
|
|
658
|
+
});
|
|
659
|
+
const committedIds = new Set(state.committedIds);
|
|
660
|
+
if (state.nextLocalSequence < 1 || committedIds.size !== state.committedIds.length) return yield* new InvalidReplicaHistoryError({ message: "Invalid replica history" });
|
|
661
|
+
const pendingIds = /* @__PURE__ */ new Set();
|
|
662
|
+
for (const pending of state.pending) {
|
|
663
|
+
const operation = yield* Effect.try({
|
|
664
|
+
try: () => operationFrom(pending, documentId),
|
|
665
|
+
catch: () => new InvalidOutboxError({ message: "Invalid outbox" })
|
|
666
|
+
});
|
|
667
|
+
if (operation.replicaId !== replicaId || operation.localSequence >= state.nextLocalSequence || committedIds.has(operation.opId) || pendingIds.has(operation.opId)) return yield* new InvalidOutboxError({ message: "Invalid outbox" });
|
|
668
|
+
pendingIds.add(operation.opId);
|
|
669
|
+
}
|
|
670
|
+
if (saved === void 0) yield* Effect.tryPromise({
|
|
671
|
+
try: () => storage.save(state, null),
|
|
672
|
+
catch: (cause) => storageError("Could not save the replica", cause)
|
|
673
|
+
});
|
|
674
|
+
const stateRef = yield* SynchronizedRef.make(state);
|
|
675
|
+
const closed = yield* Ref.make(false);
|
|
676
|
+
const persist = (next, current) => Effect.tryPromise({
|
|
677
|
+
try: () => storage.save(next, current.revision),
|
|
678
|
+
catch: (cause) => storageError("Could not save the replica", cause)
|
|
679
|
+
});
|
|
680
|
+
const submit = (message) => SynchronizedRef.modifyEffect(stateRef, (current) => Effect.gen(function* () {
|
|
681
|
+
if (yield* Ref.get(closed)) return yield* new ReplicaClosedError({ message: "Replica is closed" });
|
|
682
|
+
const operation = yield* Effect.try({
|
|
683
|
+
try: () => operationFrom({
|
|
684
|
+
protocolVersion: 1,
|
|
685
|
+
schemaVersion: 1,
|
|
686
|
+
documentId,
|
|
687
|
+
replicaId,
|
|
688
|
+
localSequence: current.nextLocalSequence,
|
|
689
|
+
opId: `${replicaId}:${current.nextLocalSequence}`,
|
|
690
|
+
baseCursor: current.cursor,
|
|
691
|
+
message: encodeMessage(message)
|
|
692
|
+
}, documentId),
|
|
693
|
+
catch: () => new InvalidOutboxError({ message: "Invalid outbox" })
|
|
694
|
+
});
|
|
695
|
+
const next = yield* Effect.try({
|
|
696
|
+
try: () => decodeState({
|
|
697
|
+
...current,
|
|
698
|
+
revision: current.revision + 1,
|
|
699
|
+
nextLocalSequence: current.nextLocalSequence + 1,
|
|
700
|
+
pending: [...current.pending, operation]
|
|
701
|
+
}),
|
|
702
|
+
catch: (cause) => new InvalidReplicaHistoryError({
|
|
703
|
+
message: "Invalid replica state",
|
|
704
|
+
cause
|
|
705
|
+
})
|
|
706
|
+
});
|
|
707
|
+
yield* persist(next, current);
|
|
708
|
+
return [void 0, next];
|
|
709
|
+
})).pipe(Effect.withSpan("Sync.submit", { attributes: {
|
|
710
|
+
documentId,
|
|
711
|
+
replicaId
|
|
712
|
+
} }));
|
|
713
|
+
const synchronize = Effect.gen(function* () {
|
|
714
|
+
const transport = yield* Transport;
|
|
715
|
+
if (yield* Ref.get(closed)) return yield* new ReplicaClosedError({ message: "Replica is closed" });
|
|
716
|
+
const sent = yield* SynchronizedRef.get(stateRef);
|
|
717
|
+
yield* Metric.update(syncMetrics.exchanges, 1);
|
|
718
|
+
yield* Metric.update(syncMetrics.exchangePending, sent.pending.length);
|
|
719
|
+
const response = decodeExchange(yield* transport.exchange(sent.cursor, sent.pending).pipe(Effect.tapError((error) => Effect.logWarning("sync exchange failed", {
|
|
720
|
+
documentId,
|
|
721
|
+
replicaId,
|
|
722
|
+
error: error.message
|
|
723
|
+
}))));
|
|
724
|
+
yield* SynchronizedRef.modifyEffect(stateRef, (current) => Effect.gen(function* () {
|
|
725
|
+
if (yield* Ref.get(closed)) return yield* new ReplicaClosedError({ message: "Replica is closed" });
|
|
726
|
+
let cursor = current.cursor;
|
|
727
|
+
let committed = current.committed;
|
|
728
|
+
const ids = response.checkpoint === void 0 ? new Set(current.committedIds) : /* @__PURE__ */ new Set();
|
|
729
|
+
if (response.checkpoint !== void 0) {
|
|
730
|
+
if (response.checkpoint.cursor < cursor) return yield* new CheckpointRegressionError({
|
|
731
|
+
cursor,
|
|
732
|
+
checkpointCursor: response.checkpoint.cursor,
|
|
733
|
+
message: "Checkpoint is behind the replica"
|
|
734
|
+
});
|
|
735
|
+
committed = response.checkpoint.model;
|
|
736
|
+
cursor = response.checkpoint.cursor;
|
|
737
|
+
yield* Metric.update(syncMetrics.checkpoints, 1);
|
|
738
|
+
yield* Effect.logDebug("sync checkpoint adopted", {
|
|
739
|
+
documentId,
|
|
740
|
+
replicaId,
|
|
741
|
+
cursor
|
|
742
|
+
});
|
|
743
|
+
}
|
|
744
|
+
const acknowledged = new Set(response.acknowledged ?? []);
|
|
745
|
+
const rejected = new Set(response.rejected);
|
|
746
|
+
const sentIds = new Set(sent.pending.map((operation) => operation.opId));
|
|
747
|
+
for (const id of rejected) if (!sentIds.has(id)) return yield* new ForeignRejectionError({
|
|
748
|
+
opId: id,
|
|
749
|
+
message: "Server rejected an operation that was not sent"
|
|
750
|
+
});
|
|
751
|
+
let applied = 0;
|
|
752
|
+
for (const raw of response.operations) {
|
|
753
|
+
const { committed: operation, message } = yield* Effect.try({
|
|
754
|
+
try: () => decodeCommittedOperation(raw, documentId),
|
|
755
|
+
catch: (cause) => new InvalidReplicaHistoryError({
|
|
756
|
+
message: "Invalid committed operation",
|
|
757
|
+
cause
|
|
758
|
+
})
|
|
759
|
+
});
|
|
760
|
+
if (operation.serverSequence <= cursor) continue;
|
|
761
|
+
if (operation.serverSequence !== cursor + 1 || ids.has(operation.opId)) return yield* new CommittedOrderError({
|
|
762
|
+
expected: cursor + 1,
|
|
763
|
+
actual: operation.serverSequence,
|
|
764
|
+
message: "Invalid committed order"
|
|
765
|
+
});
|
|
766
|
+
committed = definition.replay(committed, message);
|
|
767
|
+
ids.add(operation.opId);
|
|
768
|
+
cursor = operation.serverSequence;
|
|
769
|
+
applied += 1;
|
|
770
|
+
}
|
|
771
|
+
if (applied > 0) yield* Metric.update(syncMetrics.applied, applied);
|
|
772
|
+
const next = yield* Effect.try({
|
|
773
|
+
try: () => decodeState({
|
|
774
|
+
...current,
|
|
775
|
+
revision: current.revision + 1,
|
|
776
|
+
committed,
|
|
777
|
+
cursor,
|
|
778
|
+
committedIds: [...ids].slice(-1024),
|
|
779
|
+
pending: current.pending.filter((operation) => !ids.has(operation.opId) && !acknowledged.has(operation.opId) && !rejected.has(operation.opId))
|
|
780
|
+
}),
|
|
781
|
+
catch: (cause) => new InvalidReplicaHistoryError({
|
|
782
|
+
message: "Invalid replica state",
|
|
783
|
+
cause
|
|
784
|
+
})
|
|
785
|
+
});
|
|
786
|
+
yield* persist(next, current);
|
|
787
|
+
return [void 0, next];
|
|
788
|
+
}));
|
|
789
|
+
}).pipe(Effect.withSpan("Sync.synchronize", { attributes: { documentId } }));
|
|
790
|
+
return {
|
|
791
|
+
shared: Effect.map(SynchronizedRef.get(stateRef), optimistic),
|
|
792
|
+
pending: Effect.map(SynchronizedRef.get(stateRef), (state) => state.pending),
|
|
793
|
+
cursor: Effect.map(SynchronizedRef.get(stateRef), (state) => state.cursor),
|
|
794
|
+
submit,
|
|
795
|
+
synchronize,
|
|
796
|
+
close: Effect.gen(function* () {
|
|
797
|
+
yield* Ref.set(closed, true);
|
|
798
|
+
yield* Effect.sync(() => storage.close());
|
|
799
|
+
})
|
|
800
|
+
};
|
|
801
|
+
}).pipe(Effect.withSpan("Sync.openReplica", { attributes: {
|
|
802
|
+
documentId,
|
|
803
|
+
replicaId
|
|
804
|
+
} }));
|
|
805
|
+
return {
|
|
806
|
+
documentId,
|
|
807
|
+
normalizeOperation,
|
|
808
|
+
operationFrom,
|
|
809
|
+
committedFrom,
|
|
810
|
+
decodeExchange,
|
|
811
|
+
openReplica
|
|
812
|
+
};
|
|
813
|
+
};
|
|
814
|
+
//#endregion
|
|
815
|
+
export { CheckpointRegressionError, CommittedOrderError, ForeignRejectionError, InvalidOutboxError, InvalidReplicaHistoryError, ReplicaClosedError, StorageError, Transport, TransportError, WrongReplicaStorageError, createPresence, createPresenceHub, defineSync, indexedDb, layerFromPromise, layerLoopback, layerSocket, loopbackPresenceChannel, lwwRegister, nativeSocket, openLwwClock, servePresence, serveSocket, socketPresenceChannel, syncMetrics, toPromise };
|
|
816
|
+
|
|
817
|
+
//# sourceMappingURL=index.mjs.map
|