foldkit-sync 0.8.0 → 0.9.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/README.md +147 -23
- package/dist/entity.d.mts +231 -0
- package/dist/entity.d.mts.map +1 -0
- package/dist/entity.mjs +204 -0
- package/dist/entity.mjs.map +1 -0
- package/dist/index.d.mts +51 -485
- package/dist/index.d.mts.map +1 -1
- package/dist/index.mjs +132 -331
- package/dist/index.mjs.map +1 -1
- package/dist/journal.d.mts +132 -0
- package/dist/journal.d.mts.map +1 -0
- package/dist/journal.mjs +204 -0
- package/dist/journal.mjs.map +1 -0
- package/dist/sync-CP5UGs4r.d.mts +547 -0
- package/dist/sync-CP5UGs4r.d.mts.map +1 -0
- package/dist/transport-hlEQpHIv.mjs +359 -0
- package/dist/transport-hlEQpHIv.mjs.map +1 -0
- package/package.json +21 -4
|
@@ -0,0 +1,132 @@
|
|
|
1
|
+
import { b as SocketLike, f as Sync, m as TransportClient, o as Operation } from "./sync-CP5UGs4r.mjs";
|
|
2
|
+
import { Effect, Option, Schema } from "effect";
|
|
3
|
+
import { Journal } from "foldkit-durable/core";
|
|
4
|
+
//#region src/journal.d.ts
|
|
5
|
+
export interface JournalExchangeOptions<Message, Shared, Principal> {
|
|
6
|
+
/** The document's contract: its codecs, and the snapshot a checkpoint encodes. */
|
|
7
|
+
readonly sync: Sync<Message, Shared>;
|
|
8
|
+
/**
|
|
9
|
+
* The journal made from `sync.journalContract()`, which orders and keeps the
|
|
10
|
+
* document. One that takes any input, or only operations, is accepted.
|
|
11
|
+
*/
|
|
12
|
+
readonly journal: Journal<Operation, Shared, Principal, Operation>;
|
|
13
|
+
/**
|
|
14
|
+
* Who is exchanging, as the transport established it. The journal's
|
|
15
|
+
* `authorize` reads it; a refused operation is reported as rejected.
|
|
16
|
+
*/
|
|
17
|
+
readonly principal: Principal;
|
|
18
|
+
/**
|
|
19
|
+
* Runs after each exchange's appends and before the reply is read: apply
|
|
20
|
+
* what committed to another store, through `journal.recover`. It runs on
|
|
21
|
+
* every exchange, so a write that failed is tried again on the next.
|
|
22
|
+
*/
|
|
23
|
+
readonly settle?: Effect.Effect<void, unknown> | undefined;
|
|
24
|
+
/**
|
|
25
|
+
* Refuses an operation before the journal sees it, by what the transport
|
|
26
|
+
* established rather than by the document: a principal that may only read.
|
|
27
|
+
* A refused operation is rejected by its id. The journal's own `authorize`
|
|
28
|
+
* is where a rule about the document goes.
|
|
29
|
+
*/
|
|
30
|
+
readonly refuse?: ((operation: Operation) => boolean) | undefined;
|
|
31
|
+
/** The most committed operations one reply carries; a replica further behind asks again. Default 500. */
|
|
32
|
+
readonly limit?: number | undefined;
|
|
33
|
+
}
|
|
34
|
+
/**
|
|
35
|
+
* One replica's exchanges with the journal, as the replica's transport
|
|
36
|
+
* speaks them (`Sync.transport.fromPromise`, or behind
|
|
37
|
+
* `Sync.transport.serve` on a socket). Each pending operation is appended in
|
|
38
|
+
* order, and acknowledged once committed, or already committed. One is
|
|
39
|
+
* rejected by its id when its message does not decode, it names another
|
|
40
|
+
* document, or the journal refuses it (`authorize`, `validate`); the replica
|
|
41
|
+
* drops it rather than send it again. Only an entry with no id at all, a
|
|
42
|
+
* cursor ahead of the journal's, or the journal failing fails the exchange. The reply carries what committed
|
|
43
|
+
* after the replica's cursor, a checkpoint when that history was compacted,
|
|
44
|
+
* and the journal's epoch, so a replica of a reset journal starts again.
|
|
45
|
+
*/
|
|
46
|
+
export declare const journalExchange: <Message, Shared, Principal>(options: JournalExchangeOptions<Message, Shared, Principal>) => TransportClient;
|
|
47
|
+
/**
|
|
48
|
+
* Calls `listener` each time the document commits, for `Sync.transport.serve`'s
|
|
49
|
+
* `changes`, so a socket wakes its replica to exchange. Returns the unsubscribe.
|
|
50
|
+
*/
|
|
51
|
+
export declare const journalChanges: <Shared, Principal>(journal: Journal<Operation, Shared, Principal, Operation>, documentId: string) => ((listener: () => void) => () => void);
|
|
52
|
+
/**
|
|
53
|
+
* Serves one accepted socket over the journal: each exchange frame answered by
|
|
54
|
+
* `journalExchange` with the connection's principal, and a notice sent after
|
|
55
|
+
* each commit, so the replica hears of others' edits. Returns the stop.
|
|
56
|
+
*/
|
|
57
|
+
export declare const serveJournal: <Message, Shared, Principal>(socket: SocketLike, options: JournalExchangeOptions<Message, Shared, Principal>) => (() => void);
|
|
58
|
+
declare const TableAheadOfJournalError_base: Schema.Class<TableAheadOfJournalError, Schema.TaggedStruct<"SyncTableAheadOfJournalError", {
|
|
59
|
+
readonly table: Schema.Number;
|
|
60
|
+
readonly journal: Schema.Number;
|
|
61
|
+
}>, import("effect/Cause").YieldableError>;
|
|
62
|
+
/**
|
|
63
|
+
* The table holds revisions past every sequence the journal has: it outlived
|
|
64
|
+
* a reset of the journal, or was built from another. New edits commit at
|
|
65
|
+
* sequences the table already passed, so `apply` would skip every one and
|
|
66
|
+
* the replicas count each absorbed: rebuild the table with the journal.
|
|
67
|
+
*/
|
|
68
|
+
export declare class TableAheadOfJournalError extends TableAheadOfJournalError_base {
|
|
69
|
+
get message(): string;
|
|
70
|
+
}
|
|
71
|
+
export interface EditsJournalOptions<Shared, Principal, Change> {
|
|
72
|
+
/** The document whose edits the table reads. */
|
|
73
|
+
readonly documentId: string;
|
|
74
|
+
/** The journal the edits commit to. */
|
|
75
|
+
readonly journal: Journal<Operation, Shared, Principal, Operation>;
|
|
76
|
+
/**
|
|
77
|
+
* The cells an operation edits, with the sequence its stamp wrote in; none
|
|
78
|
+
* for an operation that edits nothing. An edit committed without a sequence
|
|
79
|
+
* is not this journal's: its intents fail rather than write revision 0.
|
|
80
|
+
*/
|
|
81
|
+
readonly editsOf: (operation: Operation) => Option.Option<{
|
|
82
|
+
readonly changes: ReadonlyArray<Change>;
|
|
83
|
+
readonly at: Option.Option<number>;
|
|
84
|
+
}>;
|
|
85
|
+
/**
|
|
86
|
+
* Writes one committed change to the table, with the sequence it committed
|
|
87
|
+
* at. It runs as a recovery intent, so it may run again after a crash: it
|
|
88
|
+
* must never move a row back (`revision <= at`). A failure stops recovery
|
|
89
|
+
* there, and the next settle tries it again.
|
|
90
|
+
*
|
|
91
|
+
* It cannot refuse an edit: the edit has committed. One naming a row the
|
|
92
|
+
* table lacks is refused at commit instead, by the journal's `validate`,
|
|
93
|
+
* so its sender is told; let through, it would change nothing and vanish
|
|
94
|
+
* once absorbed.
|
|
95
|
+
*/
|
|
96
|
+
readonly apply: (change: Change, at: number) => Effect.Effect<void, unknown>;
|
|
97
|
+
/**
|
|
98
|
+
* The highest revision the table holds. Settling refuses to start while it
|
|
99
|
+
* is past the journal's cursor (`TableAheadOfJournalError`), since every
|
|
100
|
+
* edit would then be skipped and counted absorbed; it asks again on each
|
|
101
|
+
* settle until the two agree.
|
|
102
|
+
*/
|
|
103
|
+
readonly tableRevision: Effect.Effect<number, unknown>;
|
|
104
|
+
/** Whether the snapshot still keeps an edit committed through `through`: whether to absorb. */
|
|
105
|
+
readonly holdsThrough: (snapshot: Shared, through: number) => boolean;
|
|
106
|
+
/**
|
|
107
|
+
* The server's operation saying the table holds every edit through
|
|
108
|
+
* `through`, sequenced from `cursor`, the journal's: the replicas drop those
|
|
109
|
+
* edits on hearing it.
|
|
110
|
+
*/
|
|
111
|
+
readonly absorbed: (through: number, cursor: number) => Operation;
|
|
112
|
+
/** Who the server commits `absorbed` as; the contract's `authorize` should let only it. */
|
|
113
|
+
readonly server: Principal;
|
|
114
|
+
}
|
|
115
|
+
/**
|
|
116
|
+
* The table as the journal's read model: `settle` applies each committed
|
|
117
|
+
* edit through `apply`, as a recovery intent, and `absorb` records in the
|
|
118
|
+
* journal what the table holds and compacts the log behind it. For
|
|
119
|
+
* `journalExchange`'s `settle`, and a clock that absorbs.
|
|
120
|
+
*
|
|
121
|
+
* Recovery starts at the journal's floor, where compaction left it, so a
|
|
122
|
+
* server restarted over a journal that outlived it does not ask for history
|
|
123
|
+
* that is gone. Intents are keyed by the journal's epoch as well as the
|
|
124
|
+
* operation, so after a reset an operation sent again is applied again, not
|
|
125
|
+
* taken as already run.
|
|
126
|
+
*/
|
|
127
|
+
export declare const editsJournal: <Shared, Principal, Change>(options: EditsJournalOptions<Shared, Principal, Change>) => {
|
|
128
|
+
readonly settle: Effect.Effect<void, unknown>;
|
|
129
|
+
readonly absorb: Effect.Effect<void, unknown>;
|
|
130
|
+
};
|
|
131
|
+
//#endregion
|
|
132
|
+
//# sourceMappingURL=journal.d.mts.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"journal.d.mts","names":[],"sources":["../src/journal.ts"],"mappings":";;;;iBAsBiB,uBAAuB,SAAS,QAAQ;;WAE9C,MAAM,KAAK,SAAS;;;;;WAKpB,SAAS,QAAQ,WAAW,QAAQ,WAAW;;;;;WAK/C,WAAW;;;;;;WAMX,SAAS,OAAO;;;;;;;WAOhB,WAAW,WAAW;;WAEtB;;;;;;;;;;;;;;qBAsBE,kBAAmB,SAAS,QAAQ,WAC/C,SAAS,uBAAuB,SAAS,QAAQ,eAChD;;;;;qBA6GU,iBACV,QAAQ,WACP,SAAS,QAAQ,WAAW,QAAQ,WAAW,YAC/C,yBACG;;;;;;qBAgBM,eAAgB,SAAS,QAAQ,WAC5C,QAAQ,YACR,SAAS,uBAAuB,SAAS,QAAQ;;;;;;;;;;;qBAetC,iCAAiC;MAI/B;;iBAKE,oBAAoB,QAAQ,WAAW;;WAE7C;;WAEA,SAAS,QAAQ,WAAW,QAAQ,WAAW;;;;;;WAM/C,UAAU,WAAW,cAAc,OAAO;aACxC,SAAS,cAAc;aACvB,IAAI,OAAO;;;;;;;;;;;;;WAab,QAAQ,QAAQ,QAAQ,eAAe,OAAO;;;;;;;WAO9C,eAAe,OAAO;;WAEtB,eAAe,UAAU,QAAQ;;;;;;WAMjC,WAAW,iBAAiB,mBAAmB;;WAE/C,QAAQ;;;;;;;;;;;;;;qBAeN,eAAgB,QAAQ,WAAW,QAC9C,SAAS,oBAAoB,QAAQ,WAAW;WAEvC,QAAQ,OAAO;WACf,QAAQ,OAAO"}
|
package/dist/journal.mjs
ADDED
|
@@ -0,0 +1,204 @@
|
|
|
1
|
+
import { c as serveSocket, y as sequence } from "./transport-hlEQpHIv.mjs";
|
|
2
|
+
import { Effect, Fiber, Match, Option, Schema, Stream } from "effect";
|
|
3
|
+
import { Cursor, DocumentId, Sequence } from "foldkit-durable/core";
|
|
4
|
+
//#region src/journal.ts
|
|
5
|
+
/**
|
|
6
|
+
* `foldkit-sync/journal` — the server's side of an exchange, over a
|
|
7
|
+
* `foldkit-durable` journal. Every Sync server needs the same loop: append
|
|
8
|
+
* what a replica sends, refuse what cannot be taken, and read back what
|
|
9
|
+
* committed since the replica's cursor. Written by hand three times, it
|
|
10
|
+
* failed the same way: an operation that did not decode failed the whole
|
|
11
|
+
* exchange, so the replica sent it again on every one and the edits behind it
|
|
12
|
+
* never went. Here, refused operations are reported by id, and the replica
|
|
13
|
+
* drops them.
|
|
14
|
+
*/
|
|
15
|
+
/** The id an entry names, read without trusting the rest of it. */
|
|
16
|
+
const idOf = (input) => Option.map(Schema.decodeUnknownOption(Schema.Struct({ opId: Schema.String }))(input), ({ opId }) => opId);
|
|
17
|
+
/**
|
|
18
|
+
* One replica's exchanges with the journal, as the replica's transport
|
|
19
|
+
* speaks them (`Sync.transport.fromPromise`, or behind
|
|
20
|
+
* `Sync.transport.serve` on a socket). Each pending operation is appended in
|
|
21
|
+
* order, and acknowledged once committed, or already committed. One is
|
|
22
|
+
* rejected by its id when its message does not decode, it names another
|
|
23
|
+
* document, or the journal refuses it (`authorize`, `validate`); the replica
|
|
24
|
+
* drops it rather than send it again. Only an entry with no id at all, a
|
|
25
|
+
* cursor ahead of the journal's, or the journal failing fails the exchange. The reply carries what committed
|
|
26
|
+
* after the replica's cursor, a checkpoint when that history was compacted,
|
|
27
|
+
* and the journal's epoch, so a replica of a reset journal starts again.
|
|
28
|
+
*/
|
|
29
|
+
const journalExchange = (options) => {
|
|
30
|
+
const { sync, journal, principal } = options;
|
|
31
|
+
const limit = options.limit ?? 500;
|
|
32
|
+
const key = DocumentId.make(sync.documentId);
|
|
33
|
+
const snapshot = sync.journalContract().snapshot;
|
|
34
|
+
const operationOf = Option.liftThrowable((input) => sync.codec.operationFrom(input, sync.documentId));
|
|
35
|
+
const committedOf = (committed) => sync.codec.committedFrom({
|
|
36
|
+
...committed.operation,
|
|
37
|
+
serverSequence: committed.sequence,
|
|
38
|
+
actorId: committed.actorId
|
|
39
|
+
}, sync.documentId);
|
|
40
|
+
const exchange = (cursor, pending, seen) => Effect.gen(function* () {
|
|
41
|
+
const epoch = yield* journal.epoch(key);
|
|
42
|
+
const from = seen !== void 0 && seen !== epoch ? 0 : cursor;
|
|
43
|
+
const at = yield* journal.cursor(key);
|
|
44
|
+
if (from > at) return yield* Effect.fail(/* @__PURE__ */ new Error(`Cursor ${cursor} is ahead of the server's ${at}`));
|
|
45
|
+
const rejected = [];
|
|
46
|
+
const reasons = [];
|
|
47
|
+
const reject = (opId, reason) => {
|
|
48
|
+
rejected.push(opId);
|
|
49
|
+
reasons.push({
|
|
50
|
+
opId,
|
|
51
|
+
reason
|
|
52
|
+
});
|
|
53
|
+
};
|
|
54
|
+
const acknowledged = [];
|
|
55
|
+
for (const input of pending) {
|
|
56
|
+
const decoded = operationOf(input);
|
|
57
|
+
if (Option.isNone(decoded)) {
|
|
58
|
+
const id = idOf(input);
|
|
59
|
+
if (Option.isNone(id)) return yield* Effect.fail(/* @__PURE__ */ new Error("A pending entry names no operation"));
|
|
60
|
+
reject(id.value, "Not an operation this server accepts");
|
|
61
|
+
continue;
|
|
62
|
+
}
|
|
63
|
+
const operation = decoded.value;
|
|
64
|
+
if (options.refuse?.(operation) === true) {
|
|
65
|
+
reject(operation.opId, "This connection may not make changes");
|
|
66
|
+
continue;
|
|
67
|
+
}
|
|
68
|
+
yield* journal.append(key, operation, principal).pipe(Effect.map((appended) => acknowledged.push(Match.valueTags(appended, {
|
|
69
|
+
Committed: ({ committed }) => committed.operation.opId,
|
|
70
|
+
AlreadyCommitted: ({ opId }) => opId
|
|
71
|
+
}))), Effect.catchTags({
|
|
72
|
+
OperationRejectedError: (error) => Effect.sync(() => reject(error.opId, error.reason ?? "Refused by the server")),
|
|
73
|
+
InvalidOperationError: () => Effect.sync(() => reject(operation.opId, "Not a valid operation")),
|
|
74
|
+
IdentityConflictError: () => Effect.sync(() => reject(operation.opId, "Its id was already used for another"))
|
|
75
|
+
}));
|
|
76
|
+
}
|
|
77
|
+
if (options.settle !== void 0) yield* options.settle;
|
|
78
|
+
const read = yield* journal.read(key, Cursor.make(from), { limit }).pipe(Effect.map((rows) => Option.some(rows)), Effect.catchTag("CompactedCursorError", () => Effect.succeed(Option.none())));
|
|
79
|
+
return yield* Option.match(read, {
|
|
80
|
+
onSome: (rows) => Effect.succeed({
|
|
81
|
+
operations: rows.map(committedOf),
|
|
82
|
+
rejected,
|
|
83
|
+
reasons,
|
|
84
|
+
acknowledged,
|
|
85
|
+
more: rows.length === limit,
|
|
86
|
+
epoch
|
|
87
|
+
}),
|
|
88
|
+
onNone: () => Effect.map(journal.load(key), (loaded) => ({
|
|
89
|
+
operations: [],
|
|
90
|
+
rejected,
|
|
91
|
+
reasons,
|
|
92
|
+
acknowledged,
|
|
93
|
+
checkpoint: {
|
|
94
|
+
cursor: loaded.cursor,
|
|
95
|
+
model: snapshot.encode(loaded.snapshot)
|
|
96
|
+
},
|
|
97
|
+
epoch
|
|
98
|
+
}))
|
|
99
|
+
});
|
|
100
|
+
});
|
|
101
|
+
return { exchange: (cursor, pending, seen) => Effect.runPromise(exchange(cursor, pending, seen)) };
|
|
102
|
+
};
|
|
103
|
+
/**
|
|
104
|
+
* Calls `listener` each time the document commits, for `Sync.transport.serve`'s
|
|
105
|
+
* `changes`, so a socket wakes its replica to exchange. Returns the unsubscribe.
|
|
106
|
+
*/
|
|
107
|
+
const journalChanges = (journal, documentId) => (listener) => {
|
|
108
|
+
const fiber = Effect.runFork(Stream.runForEach(Stream.filter(journal.subscribe, (key) => key === documentId), () => Effect.sync(listener)));
|
|
109
|
+
return () => Effect.runSync(Fiber.interrupt(fiber));
|
|
110
|
+
};
|
|
111
|
+
/**
|
|
112
|
+
* Serves one accepted socket over the journal: each exchange frame answered by
|
|
113
|
+
* `journalExchange` with the connection's principal, and a notice sent after
|
|
114
|
+
* each commit, so the replica hears of others' edits. Returns the stop.
|
|
115
|
+
*/
|
|
116
|
+
const serveJournal = (socket, options) => {
|
|
117
|
+
const client = journalExchange(options);
|
|
118
|
+
return serveSocket(socket, {
|
|
119
|
+
exchange: (cursor, pending, epoch) => client.exchange(sequence(cursor), pending, epoch),
|
|
120
|
+
changes: journalChanges(options.journal, options.sync.documentId)
|
|
121
|
+
});
|
|
122
|
+
};
|
|
123
|
+
/**
|
|
124
|
+
* The table holds revisions past every sequence the journal has: it outlived
|
|
125
|
+
* a reset of the journal, or was built from another. New edits commit at
|
|
126
|
+
* sequences the table already passed, so `apply` would skip every one and
|
|
127
|
+
* the replicas count each absorbed: rebuild the table with the journal.
|
|
128
|
+
*/
|
|
129
|
+
var TableAheadOfJournalError = class extends Schema.TaggedError()("SyncTableAheadOfJournalError", {
|
|
130
|
+
table: Schema.Number,
|
|
131
|
+
journal: Schema.Number
|
|
132
|
+
}) {
|
|
133
|
+
get message() {
|
|
134
|
+
return `The table holds revision ${this.table}, past the journal's ${this.journal}: rebuild the table with the journal`;
|
|
135
|
+
}
|
|
136
|
+
};
|
|
137
|
+
/**
|
|
138
|
+
* The table as the journal's read model: `settle` applies each committed
|
|
139
|
+
* edit through `apply`, as a recovery intent, and `absorb` records in the
|
|
140
|
+
* journal what the table holds and compacts the log behind it. For
|
|
141
|
+
* `journalExchange`'s `settle`, and a clock that absorbs.
|
|
142
|
+
*
|
|
143
|
+
* Recovery starts at the journal's floor, where compaction left it, so a
|
|
144
|
+
* server restarted over a journal that outlived it does not ask for history
|
|
145
|
+
* that is gone. Intents are keyed by the journal's epoch as well as the
|
|
146
|
+
* operation, so after a reset an operation sent again is applied again, not
|
|
147
|
+
* taken as already run.
|
|
148
|
+
*/
|
|
149
|
+
const editsJournal = (options) => {
|
|
150
|
+
const { journal } = options;
|
|
151
|
+
const key = DocumentId.make(options.documentId);
|
|
152
|
+
let applied = Option.none();
|
|
153
|
+
const intents = (epoch) => (operation) => Option.match(options.editsOf(operation), {
|
|
154
|
+
onNone: () => [],
|
|
155
|
+
onSome: ({ changes, at }) => changes.map((change, index) => ({
|
|
156
|
+
key: `${epoch}:${operation.opId}:${index}`,
|
|
157
|
+
run: Option.match(at, {
|
|
158
|
+
onNone: () => Effect.fail(/* @__PURE__ */ new Error(`Edit ${operation.opId} committed without its sequence`)),
|
|
159
|
+
onSome: (sequence) => options.apply(change, sequence)
|
|
160
|
+
})
|
|
161
|
+
}))
|
|
162
|
+
});
|
|
163
|
+
const checked = Effect.gen(function* () {
|
|
164
|
+
const table = yield* options.tableRevision;
|
|
165
|
+
const at = yield* journal.cursor(key);
|
|
166
|
+
if (table > at) return yield* new TableAheadOfJournalError({
|
|
167
|
+
table,
|
|
168
|
+
journal: at
|
|
169
|
+
});
|
|
170
|
+
return Cursor.make(yield* journal.floor(key));
|
|
171
|
+
});
|
|
172
|
+
return {
|
|
173
|
+
settle: Effect.gen(function* () {
|
|
174
|
+
const epoch = yield* journal.epoch(key);
|
|
175
|
+
const from = yield* Option.match(Option.filter(applied, (previous) => previous.epoch === epoch), {
|
|
176
|
+
onSome: ({ cursor }) => Effect.succeed(cursor),
|
|
177
|
+
onNone: () => checked
|
|
178
|
+
});
|
|
179
|
+
const cursor = yield* journal.recover({
|
|
180
|
+
key,
|
|
181
|
+
from,
|
|
182
|
+
intents: intents(epoch)
|
|
183
|
+
});
|
|
184
|
+
applied = Option.some({
|
|
185
|
+
cursor,
|
|
186
|
+
epoch
|
|
187
|
+
});
|
|
188
|
+
}),
|
|
189
|
+
absorb: Effect.gen(function* () {
|
|
190
|
+
const epoch = yield* journal.epoch(key);
|
|
191
|
+
const known = Option.filter(applied, (previous) => previous.epoch === epoch);
|
|
192
|
+
if (Option.isNone(known)) return;
|
|
193
|
+
const through = known.value.cursor;
|
|
194
|
+
const { snapshot, cursor } = yield* journal.load(key);
|
|
195
|
+
if (!options.holdsThrough(snapshot, through)) return;
|
|
196
|
+
yield* journal.append(key, options.absorbed(through, cursor), options.server);
|
|
197
|
+
yield* journal.compact(key, Sequence.make(through));
|
|
198
|
+
})
|
|
199
|
+
};
|
|
200
|
+
};
|
|
201
|
+
//#endregion
|
|
202
|
+
export { TableAheadOfJournalError, editsJournal, journalChanges, journalExchange, serveJournal };
|
|
203
|
+
|
|
204
|
+
//# sourceMappingURL=journal.mjs.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"journal.mjs","names":["JournalDocumentId"],"sources":["../src/journal.ts"],"sourcesContent":["/**\n * `foldkit-sync/journal` — the server's side of an exchange, over a\n * `foldkit-durable` journal. Every Sync server needs the same loop: append\n * what a replica sends, refuse what cannot be taken, and read back what\n * committed since the replica's cursor. Written by hand three times, it\n * failed the same way: an operation that did not decode failed the whole\n * exchange, so the replica sent it again on every one and the edits behind it\n * never went. Here, refused operations are reported by id, and the replica\n * drops them.\n */\nimport { Effect, Fiber, Match, Option, Schema, Stream } from 'effect'\nimport {\n Cursor,\n DocumentId as JournalDocumentId,\n Sequence,\n type Committed,\n type Journal,\n} from 'foldkit-durable/core'\nimport { sequence } from './ids.js'\nimport type { Operation, Sync, TransportClient } from './sync.js'\nimport { serveSocket, type SocketLike } from './transport.js'\n\nexport interface JournalExchangeOptions<Message, Shared, Principal> {\n /** The document's contract: its codecs, and the snapshot a checkpoint encodes. */\n readonly sync: Sync<Message, Shared>\n /**\n * The journal made from `sync.journalContract()`, which orders and keeps the\n * document. One that takes any input, or only operations, is accepted.\n */\n readonly journal: Journal<Operation, Shared, Principal, Operation>\n /**\n * Who is exchanging, as the transport established it. The journal's\n * `authorize` reads it; a refused operation is reported as rejected.\n */\n readonly principal: Principal\n /**\n * Runs after each exchange's appends and before the reply is read: apply\n * what committed to another store, through `journal.recover`. It runs on\n * every exchange, so a write that failed is tried again on the next.\n */\n readonly settle?: Effect.Effect<void, unknown> | undefined\n /**\n * Refuses an operation before the journal sees it, by what the transport\n * established rather than by the document: a principal that may only read.\n * A refused operation is rejected by its id. The journal's own `authorize`\n * is where a rule about the document goes.\n */\n readonly refuse?: ((operation: Operation) => boolean) | undefined\n /** The most committed operations one reply carries; a replica further behind asks again. Default 500. */\n readonly limit?: number | undefined\n}\n\n/** The id an entry names, read without trusting the rest of it. */\nconst idOf = (input: unknown): Option.Option<string> =>\n Option.map(\n Schema.decodeUnknownOption(Schema.Struct({ opId: Schema.String }))(input),\n ({ opId }) => opId,\n )\n\n/**\n * One replica's exchanges with the journal, as the replica's transport\n * speaks them (`Sync.transport.fromPromise`, or behind\n * `Sync.transport.serve` on a socket). Each pending operation is appended in\n * order, and acknowledged once committed, or already committed. One is\n * rejected by its id when its message does not decode, it names another\n * document, or the journal refuses it (`authorize`, `validate`); the replica\n * drops it rather than send it again. Only an entry with no id at all, a\n * cursor ahead of the journal's, or the journal failing fails the exchange. The reply carries what committed\n * after the replica's cursor, a checkpoint when that history was compacted,\n * and the journal's epoch, so a replica of a reset journal starts again.\n */\nexport const journalExchange = <Message, Shared, Principal>(\n options: JournalExchangeOptions<Message, Shared, Principal>,\n): TransportClient => {\n const { sync, journal, principal } = options\n const limit = options.limit ?? 500\n const key = JournalDocumentId.make(sync.documentId)\n const snapshot = sync.journalContract().snapshot\n const operationOf = Option.liftThrowable((input: unknown) =>\n sync.codec.operationFrom(input, sync.documentId),\n )\n const committedOf = (committed: Committed<Operation>) =>\n sync.codec.committedFrom(\n { ...committed.operation, serverSequence: committed.sequence, actorId: committed.actorId },\n sync.documentId,\n )\n\n const exchange = (cursor: number, pending: ReadonlyArray<unknown>, seen?: string) =>\n Effect.gen(function* () {\n // A replica that saw another epoch holds a cursor into history this journal\n // lacks (it was reset): it is answered from the start. Otherwise a cursor\n // past the journal's is refused before anything is appended, or the\n // operations would commit and their acknowledgements be lost.\n const epoch = yield* journal.epoch(key)\n const from = seen !== undefined && seen !== epoch ? 0 : cursor\n const at = yield* journal.cursor(key)\n if (from > at) {\n return yield* Effect.fail(new Error(`Cursor ${cursor} is ahead of the server's ${at}`))\n }\n const rejected: Array<string> = []\n const reasons: Array<{ readonly opId: string; readonly reason: string }> = []\n // Each reason is words for the person whose edit came back: a policy's own,\n // or a fixed sentence, never an error's message, which may carry internals.\n const reject = (opId: string, reason: string) => {\n rejected.push(opId)\n reasons.push({ opId, reason })\n }\n const acknowledged: Array<string> = []\n for (const input of pending) {\n const decoded = operationOf(input)\n if (Option.isNone(decoded)) {\n const id = idOf(input)\n if (Option.isNone(id))\n return yield* Effect.fail(new Error('A pending entry names no operation'))\n reject(id.value, 'Not an operation this server accepts')\n continue\n }\n const operation = decoded.value\n if (options.refuse?.(operation) === true) {\n reject(operation.opId, 'This connection may not make changes')\n continue\n }\n yield* journal.append(key, operation, principal).pipe(\n Effect.map(appended =>\n acknowledged.push(\n Match.valueTags(appended, {\n Committed: ({ committed }): string => committed.operation.opId,\n AlreadyCommitted: ({ opId }): string => opId,\n }),\n ),\n ),\n // A refusal, an operation the journal cannot apply, and an id reused for\n // other content fail the same way on every retry, so they are rejected; a\n // `JournalError` may not, so it still fails the exchange.\n Effect.catchTags({\n OperationRejectedError: error =>\n Effect.sync(() => reject(error.opId, error.reason ?? 'Refused by the server')),\n InvalidOperationError: () =>\n Effect.sync(() => reject(operation.opId, 'Not a valid operation')),\n IdentityConflictError: () =>\n Effect.sync(() => reject(operation.opId, 'Its id was already used for another')),\n }),\n )\n }\n if (options.settle !== undefined) yield* options.settle\n // A cursor below the compacted floor is answered with the snapshot; the\n // read decides that itself, so a compaction cannot slip in between.\n const read = yield* journal.read(key, Cursor.make(from), { limit }).pipe(\n Effect.map(rows => Option.some(rows)),\n Effect.catchTag('CompactedCursorError', () => Effect.succeed(Option.none())),\n )\n return yield* Option.match(read, {\n onSome: rows =>\n Effect.succeed({\n operations: rows.map(committedOf),\n rejected,\n reasons,\n acknowledged,\n more: rows.length === limit,\n epoch,\n }),\n onNone: () =>\n Effect.map(journal.load(key), loaded => ({\n operations: [],\n rejected,\n reasons,\n acknowledged,\n checkpoint: { cursor: loaded.cursor, model: snapshot.encode(loaded.snapshot) },\n epoch,\n })),\n })\n })\n\n return {\n exchange: (cursor, pending, seen) => Effect.runPromise(exchange(cursor, pending, seen)),\n }\n}\n\n/**\n * Calls `listener` each time the document commits, for `Sync.transport.serve`'s\n * `changes`, so a socket wakes its replica to exchange. Returns the unsubscribe.\n */\nexport const journalChanges =\n <Shared, Principal>(\n journal: Journal<Operation, Shared, Principal, Operation>,\n documentId: string,\n ): ((listener: () => void) => () => void) =>\n listener => {\n const fiber = Effect.runFork(\n Stream.runForEach(\n Stream.filter(journal.subscribe, key => key === documentId),\n () => Effect.sync(listener),\n ),\n )\n return () => Effect.runSync(Fiber.interrupt(fiber))\n }\n\n/**\n * Serves one accepted socket over the journal: each exchange frame answered by\n * `journalExchange` with the connection's principal, and a notice sent after\n * each commit, so the replica hears of others' edits. Returns the stop.\n */\nexport const serveJournal = <Message, Shared, Principal>(\n socket: SocketLike,\n options: JournalExchangeOptions<Message, Shared, Principal>,\n): (() => void) => {\n const client = journalExchange(options)\n return serveSocket(socket, {\n exchange: (cursor, pending, epoch) => client.exchange(sequence(cursor), pending, epoch),\n changes: journalChanges(options.journal, options.sync.documentId),\n })\n}\n\n/**\n * The table holds revisions past every sequence the journal has: it outlived\n * a reset of the journal, or was built from another. New edits commit at\n * sequences the table already passed, so `apply` would skip every one and\n * the replicas count each absorbed: rebuild the table with the journal.\n */\nexport class TableAheadOfJournalError extends Schema.TaggedError<TableAheadOfJournalError>()(\n 'SyncTableAheadOfJournalError',\n { table: Schema.Number, journal: Schema.Number },\n) {\n override get message(): string {\n return `The table holds revision ${this.table}, past the journal's ${this.journal}: rebuild the table with the journal`\n }\n}\n\nexport interface EditsJournalOptions<Shared, Principal, Change> {\n /** The document whose edits the table reads. */\n readonly documentId: string\n /** The journal the edits commit to. */\n readonly journal: Journal<Operation, Shared, Principal, Operation>\n /**\n * The cells an operation edits, with the sequence its stamp wrote in; none\n * for an operation that edits nothing. An edit committed without a sequence\n * is not this journal's: its intents fail rather than write revision 0.\n */\n readonly editsOf: (operation: Operation) => Option.Option<{\n readonly changes: ReadonlyArray<Change>\n readonly at: Option.Option<number>\n }>\n /**\n * Writes one committed change to the table, with the sequence it committed\n * at. It runs as a recovery intent, so it may run again after a crash: it\n * must never move a row back (`revision <= at`). A failure stops recovery\n * there, and the next settle tries it again.\n *\n * It cannot refuse an edit: the edit has committed. One naming a row the\n * table lacks is refused at commit instead, by the journal's `validate`,\n * so its sender is told; let through, it would change nothing and vanish\n * once absorbed.\n */\n readonly apply: (change: Change, at: number) => Effect.Effect<void, unknown>\n /**\n * The highest revision the table holds. Settling refuses to start while it\n * is past the journal's cursor (`TableAheadOfJournalError`), since every\n * edit would then be skipped and counted absorbed; it asks again on each\n * settle until the two agree.\n */\n readonly tableRevision: Effect.Effect<number, unknown>\n /** Whether the snapshot still keeps an edit committed through `through`: whether to absorb. */\n readonly holdsThrough: (snapshot: Shared, through: number) => boolean\n /**\n * The server's operation saying the table holds every edit through\n * `through`, sequenced from `cursor`, the journal's: the replicas drop those\n * edits on hearing it.\n */\n readonly absorbed: (through: number, cursor: number) => Operation\n /** Who the server commits `absorbed` as; the contract's `authorize` should let only it. */\n readonly server: Principal\n}\n\n/**\n * The table as the journal's read model: `settle` applies each committed\n * edit through `apply`, as a recovery intent, and `absorb` records in the\n * journal what the table holds and compacts the log behind it. For\n * `journalExchange`'s `settle`, and a clock that absorbs.\n *\n * Recovery starts at the journal's floor, where compaction left it, so a\n * server restarted over a journal that outlived it does not ask for history\n * that is gone. Intents are keyed by the journal's epoch as well as the\n * operation, so after a reset an operation sent again is applied again, not\n * taken as already run.\n */\nexport const editsJournal = <Shared, Principal, Change>(\n options: EditsJournalOptions<Shared, Principal, Change>,\n): {\n readonly settle: Effect.Effect<void, unknown>\n readonly absorb: Effect.Effect<void, unknown>\n} => {\n const { journal } = options\n const key = JournalDocumentId.make(options.documentId)\n // Operations at or before `applied.cursor` have every change in the table,\n // in `applied.epoch`: none until a settle has run in this process.\n let applied: Option.Option<{ readonly cursor: Cursor; readonly epoch: string }> = Option.none()\n const intents = (epoch: string) => (operation: Operation) =>\n Option.match(options.editsOf(operation), {\n onNone: () => [],\n onSome: ({ changes, at }) =>\n changes.map((change, index) => ({\n key: `${epoch}:${operation.opId}:${index}`,\n run: Option.match(at, {\n onNone: () =>\n Effect.fail(new Error(`Edit ${operation.opId} committed without its sequence`)),\n onSome: sequence => options.apply(change, sequence),\n }),\n })),\n })\n // Before the first recovery of an epoch: the table must not be past it.\n const checked = Effect.gen(function* () {\n const table = yield* options.tableRevision\n const at = yield* journal.cursor(key)\n if (table > at) return yield* new TableAheadOfJournalError({ table, journal: at })\n return Cursor.make(yield* journal.floor(key))\n })\n const settle = Effect.gen(function* () {\n const epoch = yield* journal.epoch(key)\n // A new epoch is a new history: recovery starts over at its floor.\n const from = yield* Option.match(\n Option.filter(applied, previous => previous.epoch === epoch),\n {\n onSome: ({ cursor }) => Effect.succeed(cursor),\n onNone: () => checked,\n },\n )\n const cursor = yield* journal.recover({ key, from, intents: intents(epoch) })\n applied = Option.some({ cursor, epoch })\n })\n // Two absorbs at once need no lock: both name the record by the journal's\n // cursor, so the second is the first's retry, answered from history.\n const absorb = Effect.gen(function* () {\n const epoch = yield* journal.epoch(key)\n const known = Option.filter(applied, previous => previous.epoch === epoch)\n if (Option.isNone(known)) return\n const through = known.value.cursor\n const { snapshot, cursor } = yield* journal.load(key)\n if (!options.holdsThrough(snapshot, through)) return\n yield* journal.append(key, options.absorbed(through, cursor), options.server)\n // What the log holds through `through` is in the table and gone from\n // the snapshot; a replica behind it is sent the snapshot instead.\n yield* journal.compact(key, Sequence.make(through))\n })\n return { settle, absorb }\n}\n"],"mappings":"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"}
|