@syncular/server 0.78.3 → 0.79.1
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 +6 -0
- package/dist/events.d.ts +14 -1
- package/dist/postgres-storage.js +5 -0
- package/dist/readiness.d.ts +6 -0
- package/dist/readiness.js +22 -4
- package/dist/realtime.d.ts +14 -1
- package/dist/realtime.js +28 -6
- package/dist/sqlite-storage.js +4 -0
- package/dist/storage-errors.d.ts +1 -1
- package/dist/storage-errors.js +1 -0
- package/dist/storage.d.ts +9 -0
- package/package.json +2 -2
- package/src/events.ts +15 -0
- package/src/postgres-storage.ts +8 -0
- package/src/readiness.ts +37 -4
- package/src/realtime.ts +38 -7
- package/src/sqlite-storage.ts +5 -0
- package/src/storage-errors.ts +3 -0
- package/src/storage.ts +9 -0
package/README.md
CHANGED
|
@@ -384,6 +384,12 @@ lock; D1 and custom adapters without `lockPartition()` fail with
|
|
|
384
384
|
`sync.storage.partition_lock_unsupported`. See
|
|
385
385
|
[host-owned authority transactions](https://syncular.dev/guide-remote-operations/#host-owned-authority-transactions).
|
|
386
386
|
|
|
387
|
+
A host that only reads, such as a `resolveScopes` callback that reads its
|
|
388
|
+
grants, calls `prepareReadTransaction(tx, schema.version, checkpoints)`
|
|
389
|
+
instead. It pins the transaction to one snapshot (`REPEATABLE READ READ ONLY`
|
|
390
|
+
on PostgreSQL) without the partition lock, so a pull never waits on a push.
|
|
391
|
+
D1 fails with `sync.storage.snapshot_unsupported` (SPEC §6.8).
|
|
392
|
+
|
|
387
393
|
`scanRows` is a Syncular scope-index scan, never an unscoped administrative
|
|
388
394
|
query. Passing an empty or omitted `scopeFilter` throws the exported
|
|
389
395
|
`StorageQueryError` with `code: 'sync.storage.scan_requires_scope'` on
|
package/dist/events.d.ts
CHANGED
|
@@ -267,6 +267,19 @@ export interface RealtimeWakeEvent extends RealtimeEventBase {
|
|
|
267
267
|
readonly type: 'realtime.wake';
|
|
268
268
|
readonly reason: WakeReason;
|
|
269
269
|
}
|
|
270
|
+
/**
|
|
271
|
+
* §8.9: a bridge gave up delivering a commit, or a client's changed
|
|
272
|
+
* registrations, to the partition's other hosts after its retries. Sessions
|
|
273
|
+
* there learn of the commit from the next one, which arrives non-adjacent.
|
|
274
|
+
*/
|
|
275
|
+
export interface RealtimeRelayFailedEvent {
|
|
276
|
+
readonly type: 'realtime.relay_failed';
|
|
277
|
+
readonly atMs: number;
|
|
278
|
+
readonly partition: string;
|
|
279
|
+
/** The commit the message carried; absent for changed registrations. */
|
|
280
|
+
readonly commitSeq?: number;
|
|
281
|
+
readonly attempts: number;
|
|
282
|
+
}
|
|
270
283
|
/** A §4.6 prune pass finished (whether or not the horizon moved). */
|
|
271
284
|
export interface PruneCompletedEvent {
|
|
272
285
|
readonly type: 'prune.completed';
|
|
@@ -311,7 +324,7 @@ export interface LeaseRevokedEvent {
|
|
|
311
324
|
* `lease.issued`, `reaction.queued`, `scopes.resolve_failed`) and shared by
|
|
312
325
|
* all of them, so a sink can group one request's events.
|
|
313
326
|
*/
|
|
314
|
-
export type SyncularServerEvent = (RequestHandledEvent | PushAppliedEvent | PushRejectedEvent | PushConflictedEvent | ReactionQueuedEvent | ReactionStartedEvent | ReactionRetriedEvent | ReactionCompletedEvent | ReactionDeadLetteredEvent | ReactionPruneCompletedEvent | PullServedEvent | SegmentDownloadedEvent | BlobUploadedEvent | BlobDownloadedEvent | BlobSweptEvent | RealtimeOpenedEvent | RealtimeClosedEvent | RealtimeDeltaEvent | RealtimeWakeEvent | PruneCompletedEvent | ScopesResolveFailedEvent | LeaseIssuedEvent | LeaseRevokedEvent) & {
|
|
327
|
+
export type SyncularServerEvent = (RequestHandledEvent | PushAppliedEvent | PushRejectedEvent | PushConflictedEvent | ReactionQueuedEvent | ReactionStartedEvent | ReactionRetriedEvent | ReactionCompletedEvent | ReactionDeadLetteredEvent | ReactionPruneCompletedEvent | PullServedEvent | SegmentDownloadedEvent | BlobUploadedEvent | BlobDownloadedEvent | BlobSweptEvent | RealtimeOpenedEvent | RealtimeClosedEvent | RealtimeDeltaEvent | RealtimeWakeEvent | RealtimeRelayFailedEvent | PruneCompletedEvent | ScopesResolveFailedEvent | LeaseIssuedEvent | LeaseRevokedEvent) & {
|
|
315
328
|
readonly requestId?: string;
|
|
316
329
|
};
|
|
317
330
|
/**
|
package/dist/postgres-storage.js
CHANGED
|
@@ -1207,6 +1207,11 @@ class PostgresTransaction {
|
|
|
1207
1207
|
this.#assertOpen();
|
|
1208
1208
|
await lockPartitionOn(this.#client, this.#partition);
|
|
1209
1209
|
}
|
|
1210
|
+
async pinSnapshot() {
|
|
1211
|
+
this.#assertOpen();
|
|
1212
|
+
// PostgreSQL refuses this after the transaction's first statement.
|
|
1213
|
+
await this.#client.query('SET TRANSACTION ISOLATION LEVEL REPEATABLE READ READ ONLY');
|
|
1214
|
+
}
|
|
1210
1215
|
async advanceCheckpoint(name, ownerEpoch, watermark, observedRows, nowMs) {
|
|
1211
1216
|
this.#assertOpen();
|
|
1212
1217
|
await this.#ensurePushSavepoint();
|
package/dist/readiness.d.ts
CHANGED
|
@@ -40,3 +40,9 @@ export declare function serveNotReadyError(refusal: ServeGateRefusal): SyncError
|
|
|
40
40
|
* actor authority under the lock and commits or rolls back the transaction.
|
|
41
41
|
*/
|
|
42
42
|
export declare function prepareAuthorityTransaction(tx: StorageTransaction, runningSchemaVersion: number, checkpoints?: readonly CheckpointDeclaration[]): Promise<void>;
|
|
43
|
+
/**
|
|
44
|
+
* Pin a host-owned read transaction to one snapshot without the partition
|
|
45
|
+
* lock, then gate it (§6.8). A scope resolver reads its authority graph here,
|
|
46
|
+
* so a pull never waits on a push. The caller rolls the transaction back.
|
|
47
|
+
*/
|
|
48
|
+
export declare function prepareReadTransaction(tx: StorageTransaction, runningSchemaVersion: number, checkpoints?: readonly CheckpointDeclaration[]): Promise<void>;
|
package/dist/readiness.js
CHANGED
|
@@ -74,14 +74,32 @@ export function serveNotReadyError(refusal) {
|
|
|
74
74
|
* Lock and gate a host-owned non-push transaction (§6.8). The caller checks
|
|
75
75
|
* actor authority under the lock and commits or rolls back the transaction.
|
|
76
76
|
*/
|
|
77
|
-
export
|
|
77
|
+
export function prepareAuthorityTransaction(tx, runningSchemaVersion, checkpoints) {
|
|
78
|
+
return prepareHostTransaction(tx, 'lock', runningSchemaVersion, checkpoints);
|
|
79
|
+
}
|
|
80
|
+
/**
|
|
81
|
+
* Pin a host-owned read transaction to one snapshot without the partition
|
|
82
|
+
* lock, then gate it (§6.8). A scope resolver reads its authority graph here,
|
|
83
|
+
* so a pull never waits on a push. The caller rolls the transaction back.
|
|
84
|
+
*/
|
|
85
|
+
export function prepareReadTransaction(tx, runningSchemaVersion, checkpoints) {
|
|
86
|
+
return prepareHostTransaction(tx, 'snapshot', runningSchemaVersion, checkpoints);
|
|
87
|
+
}
|
|
88
|
+
async function prepareHostTransaction(tx, boundary, runningSchemaVersion, checkpoints) {
|
|
78
89
|
if (!Number.isInteger(runningSchemaVersion) ||
|
|
79
90
|
runningSchemaVersion < 1 ||
|
|
80
91
|
runningSchemaVersion > 0x7fffffff)
|
|
81
92
|
throw syncError('sync.invalid_request', 'schema version must be a positive 32-bit integer');
|
|
82
|
-
if (
|
|
83
|
-
|
|
84
|
-
|
|
93
|
+
if (boundary === 'lock') {
|
|
94
|
+
if (typeof tx.lockPartition !== 'function')
|
|
95
|
+
throw new StorageQueryError('sync.storage.partition_lock_unsupported');
|
|
96
|
+
await tx.lockPartition();
|
|
97
|
+
}
|
|
98
|
+
else {
|
|
99
|
+
if (typeof tx.pinSnapshot !== 'function')
|
|
100
|
+
throw new StorageQueryError('sync.storage.snapshot_unsupported');
|
|
101
|
+
await tx.pinSnapshot();
|
|
102
|
+
}
|
|
85
103
|
const gate = await tx.readServeGate(runningSchemaVersion);
|
|
86
104
|
const refusal = serveGateRefusal(gate, runningSchemaVersion, checkpoints);
|
|
87
105
|
if (refusal !== undefined)
|
package/dist/realtime.d.ts
CHANGED
|
@@ -17,7 +17,7 @@
|
|
|
17
17
|
* the `sync` wake-up (§8.3).
|
|
18
18
|
*/
|
|
19
19
|
import { type PresenceKind, type ScopeMap, type WakeReason } from '@syncular/core';
|
|
20
|
-
import type { ServerLimits, SyncRequestContext, SyncServerConfig } from './context.js';
|
|
20
|
+
import type { RealtimeNotifier, ServerLimits, SyncRequestContext, SyncServerConfig } from './context.js';
|
|
21
21
|
import { type SyncularErrorHandler, type SyncularErrorMapper } from './errors.js';
|
|
22
22
|
import { type SyncularServerEvents } from './events.js';
|
|
23
23
|
import { type CompiledSchema } from './schema.js';
|
|
@@ -53,6 +53,13 @@ export interface RealtimeHubConfig extends Omit<SyncServerConfig, 'realtime'> {
|
|
|
53
53
|
* error, never a stale or lost latest document).
|
|
54
54
|
*/
|
|
55
55
|
readonly presenceMinIntervalMs?: number;
|
|
56
|
+
/**
|
|
57
|
+
* §8.9: the bridge to the hubs of other hosts that hold sockets of the same
|
|
58
|
+
* partition. When set, the commits and registration changes of this hub's
|
|
59
|
+
* own rounds go to `fanout` in place of this hub, and `fanout` delivers
|
|
60
|
+
* them to every hub of the partition, this one included.
|
|
61
|
+
*/
|
|
62
|
+
readonly fanout?: RealtimeNotifier;
|
|
56
63
|
}
|
|
57
64
|
export interface RealtimeConnectOptions {
|
|
58
65
|
readonly partition: string;
|
|
@@ -311,6 +318,12 @@ export declare class RealtimeHub {
|
|
|
311
318
|
wake(partition: string, reason: WakeReason): void;
|
|
312
319
|
/** Wake every session on every partition (fanout listener gap, §8.3). */
|
|
313
320
|
wakeAll(reason: WakeReason): void;
|
|
321
|
+
/**
|
|
322
|
+
* §8.9: a bridge lost commits up to `commitSeq`. Wake every session of the
|
|
323
|
+
* partition that has not observed that sequence with `catchup-required`; a
|
|
324
|
+
* session that observed a later commit was already woken by the gap (§8.2).
|
|
325
|
+
*/
|
|
326
|
+
wakeBehind(partition: string, commitSeq: number): void;
|
|
314
327
|
/**
|
|
315
328
|
* §8.5: send `heartbeat` to every session. The host calls this on its
|
|
316
329
|
* heartbeat interval (suggested 30 s); a client that hears nothing for twice
|
package/dist/realtime.js
CHANGED
|
@@ -624,8 +624,14 @@ export class RealtimeSession {
|
|
|
624
624
|
async refreshRegistrations(failClosed) {
|
|
625
625
|
const generation = ++this.#registrationGeneration;
|
|
626
626
|
let registrations;
|
|
627
|
+
/** The live units of the reloaded record: a unit the client still lists. */
|
|
628
|
+
let listed = new Set();
|
|
627
629
|
try {
|
|
628
|
-
|
|
630
|
+
const record = await this.#storage.getClientRecord(this.partition, this.clientId);
|
|
631
|
+
registrations = await this.#hub.loadRegistrations(this, record);
|
|
632
|
+
listed = new Set((record?.registration?.units ?? [])
|
|
633
|
+
.map((scopes) => unitId(scopes))
|
|
634
|
+
.filter((id) => !record?.catchingUp.some((unit) => unit.id === id)));
|
|
629
635
|
}
|
|
630
636
|
catch {
|
|
631
637
|
if (!failClosed) {
|
|
@@ -650,10 +656,12 @@ export class RealtimeSession {
|
|
|
650
656
|
this.reconcilePresence(previousKeys);
|
|
651
657
|
// §8.7: a host refresh that removes or narrows a registration wakes the
|
|
652
658
|
// session, so its client runs the round whose §3.3 revocation purge
|
|
653
|
-
// drops the rows it lost. A
|
|
654
|
-
//
|
|
655
|
-
|
|
656
|
-
|
|
659
|
+
// drops the rows it lost. A round-end or post-pull reload wakes it when a
|
|
660
|
+
// unit the client still lists lost scopes: the round may have answered
|
|
661
|
+
// the unit active before the grant went. A registration survives when the
|
|
662
|
+
// same unit and table come back with every previous scope value allowed.
|
|
663
|
+
if (previous.some((old) => (failClosed || listed.has(old.id)) &&
|
|
664
|
+
!registrations.some((next) => next.id === old.id &&
|
|
657
665
|
next.table === old.table &&
|
|
658
666
|
Object.entries(next.effective).every(([variable, values]) => old.effective[variable]?.every((value) => values.includes(value)) ?? false))))
|
|
659
667
|
this.sendWake('catchup-required');
|
|
@@ -1005,7 +1013,7 @@ export class RealtimeHub {
|
|
|
1005
1013
|
partition: identity.partition,
|
|
1006
1014
|
actorId: identity.actorId,
|
|
1007
1015
|
...(identity.context !== undefined ? { context: identity.context } : {}),
|
|
1008
|
-
realtime: this,
|
|
1016
|
+
realtime: this.#config.fanout ?? this,
|
|
1009
1017
|
};
|
|
1010
1018
|
}
|
|
1011
1019
|
/** The host's error reporter (`SyncServerConfig.onError`), if any. */
|
|
@@ -1227,6 +1235,20 @@ export class RealtimeHub {
|
|
|
1227
1235
|
for (const session of this.#sessions)
|
|
1228
1236
|
session.sendWake(reason);
|
|
1229
1237
|
}
|
|
1238
|
+
/**
|
|
1239
|
+
* §8.9: a bridge lost commits up to `commitSeq`. Wake every session of the
|
|
1240
|
+
* partition that has not observed that sequence with `catchup-required`; a
|
|
1241
|
+
* session that observed a later commit was already woken by the gap (§8.2).
|
|
1242
|
+
*/
|
|
1243
|
+
wakeBehind(partition, commitSeq) {
|
|
1244
|
+
for (const session of this.#sessions) {
|
|
1245
|
+
if (session.partition !== partition)
|
|
1246
|
+
continue;
|
|
1247
|
+
if (session.lastKnownSeq >= commitSeq)
|
|
1248
|
+
continue;
|
|
1249
|
+
session.sendWake('catchup-required');
|
|
1250
|
+
}
|
|
1251
|
+
}
|
|
1230
1252
|
/**
|
|
1231
1253
|
* §8.5: send `heartbeat` to every session. The host calls this on its
|
|
1232
1254
|
* heartbeat interval (suggested 30 s); a client that hears nothing for twice
|
package/dist/sqlite-storage.js
CHANGED
|
@@ -84,6 +84,10 @@ class SqliteTransaction extends SqliteFamilyTransaction {
|
|
|
84
84
|
this.assertOpen();
|
|
85
85
|
// BEGIN IMMEDIATE in the constructor already owns SQLite's writer lock.
|
|
86
86
|
}
|
|
87
|
+
async pinSnapshot() {
|
|
88
|
+
this.assertOpen();
|
|
89
|
+
// The one connection's BEGIN IMMEDIATE already reads one snapshot.
|
|
90
|
+
}
|
|
87
91
|
async advanceCheckpoint(name, ownerEpoch, watermark, observedRows, nowMs) {
|
|
88
92
|
this.assertOpen();
|
|
89
93
|
const result = this.#storage.db
|
package/dist/storage-errors.d.ts
CHANGED
|
@@ -9,7 +9,7 @@ export declare class StorageConstraintError extends Error {
|
|
|
9
9
|
constructor(cause: unknown, opIndex?: number);
|
|
10
10
|
}
|
|
11
11
|
/** Stable, privacy-safe failures for trusted server storage queries. */
|
|
12
|
-
export type StorageQueryErrorCode = 'sync.storage.schema_migration_pending' | 'sync.storage.schema_migration_conflict' | 'sync.storage.schema_changed' | 'sync.storage.invalid_migration_budget' | 'sync.storage.scan_requires_scope' | 'sync.storage.index_not_found' | 'sync.storage.index_not_materialized' | 'sync.storage.index_value_count_mismatch' | 'sync.storage.invalid_limit' | 'sync.storage.prune_epoch_mismatch' | 'sync.storage.partition_unregistered' | 'sync.storage.invalid_prune_cursor' | 'sync.storage.checkpoint_not_declared' | 'sync.storage.checkpoint_unsupported' | 'sync.storage.checkpoint_fence_missing' | 'sync.storage.checkpoint_incomplete' | 'sync.storage.stored_layout_mismatch' | 'sync.storage.scope_patterns_changed' | 'sync.storage.scope_value_missing' | 'sync.storage.physical_layout_mismatch' | 'sync.storage.transaction_query_unsupported' | 'sync.storage.partition_lock_unsupported' | 'sync.storage.query_over_staged_writes' | 'sync.storage.erase_unsupported' | 'sync.storage.invalid_erase_query';
|
|
12
|
+
export type StorageQueryErrorCode = 'sync.storage.schema_migration_pending' | 'sync.storage.schema_migration_conflict' | 'sync.storage.schema_changed' | 'sync.storage.invalid_migration_budget' | 'sync.storage.scan_requires_scope' | 'sync.storage.index_not_found' | 'sync.storage.index_not_materialized' | 'sync.storage.index_value_count_mismatch' | 'sync.storage.invalid_limit' | 'sync.storage.prune_epoch_mismatch' | 'sync.storage.partition_unregistered' | 'sync.storage.invalid_prune_cursor' | 'sync.storage.checkpoint_not_declared' | 'sync.storage.checkpoint_unsupported' | 'sync.storage.checkpoint_fence_missing' | 'sync.storage.checkpoint_incomplete' | 'sync.storage.stored_layout_mismatch' | 'sync.storage.scope_patterns_changed' | 'sync.storage.scope_value_missing' | 'sync.storage.physical_layout_mismatch' | 'sync.storage.transaction_query_unsupported' | 'sync.storage.partition_lock_unsupported' | 'sync.storage.snapshot_unsupported' | 'sync.storage.query_over_staged_writes' | 'sync.storage.erase_unsupported' | 'sync.storage.invalid_erase_query';
|
|
13
13
|
/**
|
|
14
14
|
* Host-only query error. Messages never include identifiers, values, SQL,
|
|
15
15
|
* paths, or row data; callers branch on `code`, never message text. The
|
package/dist/storage-errors.js
CHANGED
|
@@ -29,6 +29,7 @@ const STORAGE_QUERY_MESSAGES = {
|
|
|
29
29
|
'sync.storage.physical_layout_mismatch': 'a synced table does not match the storage layout the running code reads and writes',
|
|
30
30
|
'sync.storage.transaction_query_unsupported': 'this storage transaction cannot run registered queries',
|
|
31
31
|
'sync.storage.partition_lock_unsupported': 'this storage transaction cannot serialize partition authority',
|
|
32
|
+
'sync.storage.snapshot_unsupported': 'this storage transaction cannot read one snapshot without the partition lock',
|
|
32
33
|
'sync.storage.query_over_staged_writes': 'registered query reads a table this transaction has buffered writes for',
|
|
33
34
|
'sync.storage.scan_requires_scope': 'scope-indexed row scans require at least one scope variable',
|
|
34
35
|
'sync.storage.index_not_found': 'trusted row lookup requires a declared relational index',
|
package/dist/storage.d.ts
CHANGED
|
@@ -629,6 +629,15 @@ export interface StorageTransaction {
|
|
|
629
629
|
* existing custom storage implementations fail closed at that boundary.
|
|
630
630
|
*/
|
|
631
631
|
lockPartition?(): Promise<void>;
|
|
632
|
+
/**
|
|
633
|
+
* Make this transaction read one snapshot of committed state without the
|
|
634
|
+
* push-serialization lock, so a concurrent push neither waits for it nor
|
|
635
|
+
* becomes visible halfway through it (§6.8 host-owned read transactions).
|
|
636
|
+
* Must precede the transaction's first read. PostgreSQL sets
|
|
637
|
+
* `REPEATABLE READ READ ONLY`; SQLite's `BEGIN IMMEDIATE` already reads one
|
|
638
|
+
* snapshot. Host-owned paths call `prepareReadTransaction`.
|
|
639
|
+
*/
|
|
640
|
+
pinSnapshot?(): Promise<void>;
|
|
632
641
|
/**
|
|
633
642
|
* Serialize every push apply for this partition before any operation read,
|
|
634
643
|
* validation, merge, or write, and read the admission token once for the
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@syncular/server",
|
|
3
|
-
"version": "0.
|
|
3
|
+
"version": "0.79.1",
|
|
4
4
|
"description": "Syncular server: handleSyncRequest + storage/auth interfaces for the sync protocol",
|
|
5
5
|
"license": "Apache-2.0",
|
|
6
6
|
"author": "Benjamin Kniffler",
|
|
@@ -68,7 +68,7 @@
|
|
|
68
68
|
"verify:node": "cd ../.. && bun build ./packages/server/test/sqlite-runtime/verify-node.mjs --target=node --conditions=bun --outfile=./packages/server/.verify-node.built.mjs && node ./packages/server/.verify-node.built.mjs"
|
|
69
69
|
},
|
|
70
70
|
"dependencies": {
|
|
71
|
-
"@syncular/core": "0.
|
|
71
|
+
"@syncular/core": "0.79.1"
|
|
72
72
|
},
|
|
73
73
|
"devDependencies": {
|
|
74
74
|
"@electric-sql/pglite": "^0.5.4"
|
package/src/events.ts
CHANGED
|
@@ -299,6 +299,20 @@ export interface RealtimeWakeEvent extends RealtimeEventBase {
|
|
|
299
299
|
readonly reason: WakeReason;
|
|
300
300
|
}
|
|
301
301
|
|
|
302
|
+
/**
|
|
303
|
+
* §8.9: a bridge gave up delivering a commit, or a client's changed
|
|
304
|
+
* registrations, to the partition's other hosts after its retries. Sessions
|
|
305
|
+
* there learn of the commit from the next one, which arrives non-adjacent.
|
|
306
|
+
*/
|
|
307
|
+
export interface RealtimeRelayFailedEvent {
|
|
308
|
+
readonly type: 'realtime.relay_failed';
|
|
309
|
+
readonly atMs: number;
|
|
310
|
+
readonly partition: string;
|
|
311
|
+
/** The commit the message carried; absent for changed registrations. */
|
|
312
|
+
readonly commitSeq?: number;
|
|
313
|
+
readonly attempts: number;
|
|
314
|
+
}
|
|
315
|
+
|
|
302
316
|
/** A §4.6 prune pass finished (whether or not the horizon moved). */
|
|
303
317
|
export interface PruneCompletedEvent {
|
|
304
318
|
readonly type: 'prune.completed';
|
|
@@ -367,6 +381,7 @@ export type SyncularServerEvent = (
|
|
|
367
381
|
| RealtimeClosedEvent
|
|
368
382
|
| RealtimeDeltaEvent
|
|
369
383
|
| RealtimeWakeEvent
|
|
384
|
+
| RealtimeRelayFailedEvent
|
|
370
385
|
| PruneCompletedEvent
|
|
371
386
|
| ScopesResolveFailedEvent
|
|
372
387
|
| LeaseIssuedEvent
|
package/src/postgres-storage.ts
CHANGED
|
@@ -1774,6 +1774,14 @@ class PostgresTransaction implements StorageTransaction {
|
|
|
1774
1774
|
await lockPartitionOn(this.#client, this.#partition);
|
|
1775
1775
|
}
|
|
1776
1776
|
|
|
1777
|
+
async pinSnapshot(): Promise<void> {
|
|
1778
|
+
this.#assertOpen();
|
|
1779
|
+
// PostgreSQL refuses this after the transaction's first statement.
|
|
1780
|
+
await this.#client.query(
|
|
1781
|
+
'SET TRANSACTION ISOLATION LEVEL REPEATABLE READ READ ONLY',
|
|
1782
|
+
);
|
|
1783
|
+
}
|
|
1784
|
+
|
|
1777
1785
|
async advanceCheckpoint(
|
|
1778
1786
|
name: string,
|
|
1779
1787
|
ownerEpoch: number,
|
package/src/readiness.ts
CHANGED
|
@@ -115,10 +115,37 @@ export function serveNotReadyError(refusal: ServeGateRefusal): SyncError {
|
|
|
115
115
|
* Lock and gate a host-owned non-push transaction (§6.8). The caller checks
|
|
116
116
|
* actor authority under the lock and commits or rolls back the transaction.
|
|
117
117
|
*/
|
|
118
|
-
export
|
|
118
|
+
export function prepareAuthorityTransaction(
|
|
119
119
|
tx: StorageTransaction,
|
|
120
120
|
runningSchemaVersion: number,
|
|
121
121
|
checkpoints?: readonly CheckpointDeclaration[],
|
|
122
|
+
): Promise<void> {
|
|
123
|
+
return prepareHostTransaction(tx, 'lock', runningSchemaVersion, checkpoints);
|
|
124
|
+
}
|
|
125
|
+
|
|
126
|
+
/**
|
|
127
|
+
* Pin a host-owned read transaction to one snapshot without the partition
|
|
128
|
+
* lock, then gate it (§6.8). A scope resolver reads its authority graph here,
|
|
129
|
+
* so a pull never waits on a push. The caller rolls the transaction back.
|
|
130
|
+
*/
|
|
131
|
+
export function prepareReadTransaction(
|
|
132
|
+
tx: StorageTransaction,
|
|
133
|
+
runningSchemaVersion: number,
|
|
134
|
+
checkpoints?: readonly CheckpointDeclaration[],
|
|
135
|
+
): Promise<void> {
|
|
136
|
+
return prepareHostTransaction(
|
|
137
|
+
tx,
|
|
138
|
+
'snapshot',
|
|
139
|
+
runningSchemaVersion,
|
|
140
|
+
checkpoints,
|
|
141
|
+
);
|
|
142
|
+
}
|
|
143
|
+
|
|
144
|
+
async function prepareHostTransaction(
|
|
145
|
+
tx: StorageTransaction,
|
|
146
|
+
boundary: 'lock' | 'snapshot',
|
|
147
|
+
runningSchemaVersion: number,
|
|
148
|
+
checkpoints?: readonly CheckpointDeclaration[],
|
|
122
149
|
): Promise<void> {
|
|
123
150
|
if (
|
|
124
151
|
!Number.isInteger(runningSchemaVersion) ||
|
|
@@ -129,9 +156,15 @@ export async function prepareAuthorityTransaction(
|
|
|
129
156
|
'sync.invalid_request',
|
|
130
157
|
'schema version must be a positive 32-bit integer',
|
|
131
158
|
);
|
|
132
|
-
if (
|
|
133
|
-
|
|
134
|
-
|
|
159
|
+
if (boundary === 'lock') {
|
|
160
|
+
if (typeof tx.lockPartition !== 'function')
|
|
161
|
+
throw new StorageQueryError('sync.storage.partition_lock_unsupported');
|
|
162
|
+
await tx.lockPartition();
|
|
163
|
+
} else {
|
|
164
|
+
if (typeof tx.pinSnapshot !== 'function')
|
|
165
|
+
throw new StorageQueryError('sync.storage.snapshot_unsupported');
|
|
166
|
+
await tx.pinSnapshot();
|
|
167
|
+
}
|
|
135
168
|
const gate = await tx.readServeGate(runningSchemaVersion);
|
|
136
169
|
const refusal = serveGateRefusal(gate, runningSchemaVersion, checkpoints);
|
|
137
170
|
if (refusal !== undefined) throw serveNotReadyError(refusal);
|
package/src/realtime.ts
CHANGED
|
@@ -33,6 +33,7 @@ import {
|
|
|
33
33
|
type WakeReason,
|
|
34
34
|
} from '@syncular/core';
|
|
35
35
|
import type {
|
|
36
|
+
RealtimeNotifier,
|
|
36
37
|
ServerLimits,
|
|
37
38
|
SyncRequestContext,
|
|
38
39
|
SyncServerConfig,
|
|
@@ -95,6 +96,13 @@ export interface RealtimeHubConfig extends Omit<SyncServerConfig, 'realtime'> {
|
|
|
95
96
|
* error, never a stale or lost latest document).
|
|
96
97
|
*/
|
|
97
98
|
readonly presenceMinIntervalMs?: number;
|
|
99
|
+
/**
|
|
100
|
+
* §8.9: the bridge to the hubs of other hosts that hold sockets of the same
|
|
101
|
+
* partition. When set, the commits and registration changes of this hub's
|
|
102
|
+
* own rounds go to `fanout` in place of this hub, and `fanout` delivers
|
|
103
|
+
* them to every hub of the partition, this one included.
|
|
104
|
+
*/
|
|
105
|
+
readonly fanout?: RealtimeNotifier;
|
|
98
106
|
}
|
|
99
107
|
|
|
100
108
|
export interface RealtimeConnectOptions {
|
|
@@ -831,10 +839,18 @@ export class RealtimeSession {
|
|
|
831
839
|
async refreshRegistrations(failClosed: boolean): Promise<void> {
|
|
832
840
|
const generation = ++this.#registrationGeneration;
|
|
833
841
|
let registrations: Registration[];
|
|
842
|
+
/** The live units of the reloaded record: a unit the client still lists. */
|
|
843
|
+
let listed = new Set<string>();
|
|
834
844
|
try {
|
|
835
|
-
|
|
836
|
-
this,
|
|
837
|
-
|
|
845
|
+
const record = await this.#storage.getClientRecord(
|
|
846
|
+
this.partition,
|
|
847
|
+
this.clientId,
|
|
848
|
+
);
|
|
849
|
+
registrations = await this.#hub.loadRegistrations(this, record);
|
|
850
|
+
listed = new Set(
|
|
851
|
+
(record?.registration?.units ?? [])
|
|
852
|
+
.map((scopes) => unitId(scopes))
|
|
853
|
+
.filter((id) => !record?.catchingUp.some((unit) => unit.id === id)),
|
|
838
854
|
);
|
|
839
855
|
} catch {
|
|
840
856
|
if (!failClosed) {
|
|
@@ -858,12 +874,14 @@ export class RealtimeSession {
|
|
|
858
874
|
this.reconcilePresence(previousKeys);
|
|
859
875
|
// §8.7: a host refresh that removes or narrows a registration wakes the
|
|
860
876
|
// session, so its client runs the round whose §3.3 revocation purge
|
|
861
|
-
// drops the rows it lost. A
|
|
862
|
-
//
|
|
877
|
+
// drops the rows it lost. A round-end or post-pull reload wakes it when a
|
|
878
|
+
// unit the client still lists lost scopes: the round may have answered
|
|
879
|
+
// the unit active before the grant went. A registration survives when the
|
|
880
|
+
// same unit and table come back with every previous scope value allowed.
|
|
863
881
|
if (
|
|
864
|
-
failClosed &&
|
|
865
882
|
previous.some(
|
|
866
883
|
(old) =>
|
|
884
|
+
(failClosed || listed.has(old.id)) &&
|
|
867
885
|
!registrations.some(
|
|
868
886
|
(next) =>
|
|
869
887
|
next.id === old.id &&
|
|
@@ -1301,7 +1319,7 @@ export class RealtimeHub {
|
|
|
1301
1319
|
partition: identity.partition,
|
|
1302
1320
|
actorId: identity.actorId,
|
|
1303
1321
|
...(identity.context !== undefined ? { context: identity.context } : {}),
|
|
1304
|
-
realtime: this,
|
|
1322
|
+
realtime: this.#config.fanout ?? this,
|
|
1305
1323
|
};
|
|
1306
1324
|
}
|
|
1307
1325
|
|
|
@@ -1573,6 +1591,19 @@ export class RealtimeHub {
|
|
|
1573
1591
|
for (const session of this.#sessions) session.sendWake(reason);
|
|
1574
1592
|
}
|
|
1575
1593
|
|
|
1594
|
+
/**
|
|
1595
|
+
* §8.9: a bridge lost commits up to `commitSeq`. Wake every session of the
|
|
1596
|
+
* partition that has not observed that sequence with `catchup-required`; a
|
|
1597
|
+
* session that observed a later commit was already woken by the gap (§8.2).
|
|
1598
|
+
*/
|
|
1599
|
+
wakeBehind(partition: string, commitSeq: number): void {
|
|
1600
|
+
for (const session of this.#sessions) {
|
|
1601
|
+
if (session.partition !== partition) continue;
|
|
1602
|
+
if (session.lastKnownSeq >= commitSeq) continue;
|
|
1603
|
+
session.sendWake('catchup-required');
|
|
1604
|
+
}
|
|
1605
|
+
}
|
|
1606
|
+
|
|
1576
1607
|
/**
|
|
1577
1608
|
* §8.5: send `heartbeat` to every session. The host calls this on its
|
|
1578
1609
|
* heartbeat interval (suggested 30 s); a client that hears nothing for twice
|
package/src/sqlite-storage.ts
CHANGED
|
@@ -197,6 +197,11 @@ class SqliteTransaction
|
|
|
197
197
|
// BEGIN IMMEDIATE in the constructor already owns SQLite's writer lock.
|
|
198
198
|
}
|
|
199
199
|
|
|
200
|
+
async pinSnapshot(): Promise<void> {
|
|
201
|
+
this.assertOpen();
|
|
202
|
+
// The one connection's BEGIN IMMEDIATE already reads one snapshot.
|
|
203
|
+
}
|
|
204
|
+
|
|
200
205
|
async advanceCheckpoint(
|
|
201
206
|
name: string,
|
|
202
207
|
ownerEpoch: number,
|
package/src/storage-errors.ts
CHANGED
|
@@ -37,6 +37,7 @@ export type StorageQueryErrorCode =
|
|
|
37
37
|
| 'sync.storage.physical_layout_mismatch'
|
|
38
38
|
| 'sync.storage.transaction_query_unsupported'
|
|
39
39
|
| 'sync.storage.partition_lock_unsupported'
|
|
40
|
+
| 'sync.storage.snapshot_unsupported'
|
|
40
41
|
| 'sync.storage.query_over_staged_writes'
|
|
41
42
|
| 'sync.storage.erase_unsupported'
|
|
42
43
|
| 'sync.storage.invalid_erase_query';
|
|
@@ -77,6 +78,8 @@ const STORAGE_QUERY_MESSAGES: Readonly<Record<StorageQueryErrorCode, string>> =
|
|
|
77
78
|
'this storage transaction cannot run registered queries',
|
|
78
79
|
'sync.storage.partition_lock_unsupported':
|
|
79
80
|
'this storage transaction cannot serialize partition authority',
|
|
81
|
+
'sync.storage.snapshot_unsupported':
|
|
82
|
+
'this storage transaction cannot read one snapshot without the partition lock',
|
|
80
83
|
'sync.storage.query_over_staged_writes':
|
|
81
84
|
'registered query reads a table this transaction has buffered writes for',
|
|
82
85
|
'sync.storage.scan_requires_scope':
|
package/src/storage.ts
CHANGED
|
@@ -794,6 +794,15 @@ export interface StorageTransaction {
|
|
|
794
794
|
* existing custom storage implementations fail closed at that boundary.
|
|
795
795
|
*/
|
|
796
796
|
lockPartition?(): Promise<void>;
|
|
797
|
+
/**
|
|
798
|
+
* Make this transaction read one snapshot of committed state without the
|
|
799
|
+
* push-serialization lock, so a concurrent push neither waits for it nor
|
|
800
|
+
* becomes visible halfway through it (§6.8 host-owned read transactions).
|
|
801
|
+
* Must precede the transaction's first read. PostgreSQL sets
|
|
802
|
+
* `REPEATABLE READ READ ONLY`; SQLite's `BEGIN IMMEDIATE` already reads one
|
|
803
|
+
* snapshot. Host-owned paths call `prepareReadTransaction`.
|
|
804
|
+
*/
|
|
805
|
+
pinSnapshot?(): Promise<void>;
|
|
797
806
|
/**
|
|
798
807
|
* Serialize every push apply for this partition before any operation read,
|
|
799
808
|
* validation, merge, or write, and read the admission token once for the
|