@syncular/server 0.90.0 → 0.92.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/dist/context.d.ts +12 -2
- package/dist/d1-storage.d.ts +1 -0
- package/dist/d1-storage.js +2 -0
- package/dist/handler.js +6 -1
- package/dist/postgres-storage.d.ts +2 -2
- package/dist/postgres-storage.js +8 -2
- package/dist/segment-download.js +9 -6
- package/dist/sqlite-dialect.d.ts +8 -2
- package/dist/sqlite-dialect.js +7 -3
- package/dist/sqlite-storage.d.ts +1 -0
- package/dist/sqlite-storage.js +1 -0
- package/dist/storage.d.ts +10 -1
- package/package.json +2 -2
- package/src/context.ts +12 -2
- package/src/d1-storage.ts +2 -0
- package/src/handler.ts +9 -1
- package/src/postgres-storage.ts +11 -3
- package/src/segment-download.ts +10 -13
- package/src/sqlite-dialect.ts +20 -5
- package/src/sqlite-storage.ts +2 -0
- package/src/storage.ts +11 -1
package/dist/context.d.ts
CHANGED
|
@@ -15,7 +15,7 @@ import type { ServerSchema, CompiledSchema } from './schema.js';
|
|
|
15
15
|
import type { SegmentStore } from './segment-store.js';
|
|
16
16
|
import type { BlobPresignConfig, BlobUploadPresignConfig, SegmentUrlConfig } from './signed-url.js';
|
|
17
17
|
import type { SqliteImageBuilder } from './sqlite-image.js';
|
|
18
|
-
import type { CheckpointDeclaration,
|
|
18
|
+
import type { CheckpointDeclaration, PartitionTouch, ServerStorage, StoredCommit } from './storage.js';
|
|
19
19
|
import type { CommitValidator, ValidatorRegistry } from './validate.js';
|
|
20
20
|
/** SSP2 body content type (§1.1). */
|
|
21
21
|
export declare const SSP2_CONTENT_TYPE = "application/vnd.syncular.sync.v2";
|
|
@@ -36,6 +36,16 @@ export interface ResolveScopesArgs {
|
|
|
36
36
|
* Absent when the host returned none.
|
|
37
37
|
*/
|
|
38
38
|
readonly context?: string;
|
|
39
|
+
/** Present on a direct segment download (§5.5) only. */
|
|
40
|
+
readonly phase?: 'segment-download';
|
|
41
|
+
/**
|
|
42
|
+
* The download's `X-Syncular-Scopes` map, present with `phase`. The
|
|
43
|
+
* resolver MAY answer for these values only (§3.2 step 3): `'*'` for a
|
|
44
|
+
* requested variable exactly when the full answer holds it, otherwise the
|
|
45
|
+
* requested values the actor holds; an answer that grants `'*'` carries
|
|
46
|
+
* every other variable in full.
|
|
47
|
+
*/
|
|
48
|
+
readonly requested?: ScopeMap;
|
|
39
49
|
}
|
|
40
50
|
/**
|
|
41
51
|
* Sentinel a resolver returns to signal a **live-authorization outage**
|
|
@@ -253,4 +263,4 @@ export declare function limitsOf(ctx: SyncServerConfig): ServerLimits;
|
|
|
253
263
|
* Every authenticated entry point runs this first, so it also refuses an
|
|
254
264
|
* oversized authentication context (§1.1) before any resolver sees it.
|
|
255
265
|
*/
|
|
256
|
-
export declare function touchAuthenticatedPartition(ctx: SyncRequestContext): Promise<
|
|
266
|
+
export declare function touchAuthenticatedPartition(ctx: SyncRequestContext): Promise<PartitionTouch>;
|
package/dist/d1-storage.d.ts
CHANGED
|
@@ -37,6 +37,7 @@ export declare class D1ServerStorage extends SqliteFamilyStorage implements Serv
|
|
|
37
37
|
* binds one per app column plus the five `_sync_*` meta columns.
|
|
38
38
|
*/
|
|
39
39
|
protected readonly maxBindParams = 100;
|
|
40
|
+
protected readonly checkpointSchemaVersionSql = "NULL";
|
|
40
41
|
constructor(db: D1Database, options?: D1ServerStorageOptions);
|
|
41
42
|
protected all<T>(sql: string, params: readonly SqliteValue[]): Promise<T[]>;
|
|
42
43
|
/** Queue one read into the current turn's `db.batch` (see `#pendingReads`). */
|
package/dist/d1-storage.js
CHANGED
|
@@ -554,6 +554,8 @@ export class D1ServerStorage extends SqliteFamilyStorage {
|
|
|
554
554
|
* binds one per app column plus the five `_sync_*` meta columns.
|
|
555
555
|
*/
|
|
556
556
|
maxBindParams = 100;
|
|
557
|
+
// D1 declares no backfill checkpoints (see `readCheckpoints`).
|
|
558
|
+
checkpointSchemaVersionSql = 'NULL';
|
|
557
559
|
/**
|
|
558
560
|
* Page reads waiting for the end of the current microtask turn. A pull
|
|
559
561
|
* starts the first snapshot page and scope pin of every bootstrapping unit
|
package/dist/handler.js
CHANGED
|
@@ -136,7 +136,12 @@ async function planRequest(request, ctx, schema, registry) {
|
|
|
136
136
|
if (header.logEpoch === undefined && pushes.length > 0) {
|
|
137
137
|
throw syncError('sync.invalid_request', 'epoch acquisition requests must not carry push commits (§2.1)');
|
|
138
138
|
}
|
|
139
|
-
const
|
|
139
|
+
const adopt = request.frames.some((frame) => frame.type === 'ADOPT_EPOCH');
|
|
140
|
+
if (adopt && header.logEpoch !== undefined) {
|
|
141
|
+
throw syncError('sync.invalid_request', 'epoch adoption requests must not carry logEpoch (§2.1)');
|
|
142
|
+
}
|
|
143
|
+
// §2.1: adoption serves the request under the current epoch.
|
|
144
|
+
const epochReset = !adopt && header.logEpoch !== registry.logEpoch;
|
|
140
145
|
const unserved = {
|
|
141
146
|
wireVersion: request.wireVersion,
|
|
142
147
|
logEpoch: registry.logEpoch,
|
|
@@ -39,7 +39,7 @@ import type { CommitPruneQuery, CommitPruneResult } from './storage.js';
|
|
|
39
39
|
import { type UnitScopes } from '@syncular/core';
|
|
40
40
|
import { type PgExecutor } from './pg-executor.js';
|
|
41
41
|
import type { CompiledSchema, CompiledTable } from './schema.js';
|
|
42
|
-
import type { AuthoritativeQueryRequest, AuthoritativeQueryResult, CheckpointDeclaration, ClientCursorInfo, ClientPushResult, ClientRecord, ClientRecordWriteOptions, CommitDetail, CommitMetadata, CommitMetadataQuery, IndexRowScanQuery, LiveWindow, LiveWindowQuery, PartitionRegistryEntry, PrunedReactionCounts, PushWatermark, ReactionClaimQuery, ReactionFailureUpdate, ReactionListQuery, ReactionPruneQuery, RowChangeRecord, RowChangesQuery, RowListQuery, RowScanQuery, ScopeActivityQuery, ScopeCommitActivity, ScopeValueHistoryQuery, ScopeValueQuery, ServerStorage, ServeGate, StorageTransaction, StoredCheckpoint, StoredPushResult, StoredReaction, StoredRow } from './storage.js';
|
|
42
|
+
import type { AuthoritativeQueryRequest, AuthoritativeQueryResult, CheckpointDeclaration, ClientCursorInfo, ClientPushResult, ClientRecord, ClientRecordWriteOptions, CommitDetail, CommitMetadata, CommitMetadataQuery, IndexRowScanQuery, LiveWindow, LiveWindowQuery, PartitionRegistryEntry, PartitionTouch, PrunedReactionCounts, PushWatermark, ReactionClaimQuery, ReactionFailureUpdate, ReactionListQuery, ReactionPruneQuery, RowChangeRecord, RowChangesQuery, RowListQuery, RowScanQuery, ScopeActivityQuery, ScopeCommitActivity, ScopeValueHistoryQuery, ScopeValueQuery, ServerStorage, ServeGate, StorageTransaction, StoredCheckpoint, StoredPushResult, StoredReaction, StoredRow } from './storage.js';
|
|
43
43
|
/**
|
|
44
44
|
* Schema DDL. Applied by `PostgresServerStorage.migrate()` (idempotent).
|
|
45
45
|
*
|
|
@@ -89,7 +89,7 @@ export declare class PostgresServerStorage implements ServerStorage {
|
|
|
89
89
|
/** Resolve a table's compiled schema; row operations require `ensureSchema`. */
|
|
90
90
|
table(name: string): CompiledTable;
|
|
91
91
|
ensureSchema(schema: CompiledSchema, checkpoints?: readonly CheckpointDeclaration[]): Promise<void>;
|
|
92
|
-
touchPartition(partition: string, authenticatedAtMs: number, initialLogEpoch: string): Promise<
|
|
92
|
+
touchPartition(partition: string, authenticatedAtMs: number, initialLogEpoch: string): Promise<PartitionTouch>;
|
|
93
93
|
rotatePartitionLogEpoch(partition: string, logEpoch: string, authenticatedAtMs: number): Promise<PartitionRegistryEntry>;
|
|
94
94
|
listPartitionRegistry(): Promise<PartitionRegistryEntry[]>;
|
|
95
95
|
/**
|
package/dist/postgres-storage.js
CHANGED
|
@@ -1786,7 +1786,11 @@ FOR EACH ROW EXECUTE FUNCTION syncular_writer_fence()`,
|
|
|
1786
1786
|
if (initialLogEpoch.length === 0) {
|
|
1787
1787
|
throw new Error('initial log epoch must be non-empty');
|
|
1788
1788
|
}
|
|
1789
|
-
|
|
1789
|
+
const checkpointVersion = `(SELECT max(schema_version)
|
|
1790
|
+
FROM sync_backfill_checkpoints WHERE partition=$1)
|
|
1791
|
+
AS checkpoint_schema_version`;
|
|
1792
|
+
let row = (await this.#exec.query(`SELECT log_epoch, epoch_required, last_authenticated_at_ms,
|
|
1793
|
+
${checkpointVersion}
|
|
1790
1794
|
FROM sync_partition_registry WHERE partition=$1`, [partition])).rows[0];
|
|
1791
1795
|
if (row === undefined ||
|
|
1792
1796
|
authenticatedAtMs - asNumber(row.last_authenticated_at_ms) >=
|
|
@@ -1796,7 +1800,8 @@ FOR EACH ROW EXECUTE FUNCTION syncular_writer_fence()`,
|
|
|
1796
1800
|
) VALUES ($1,$2,$3)
|
|
1797
1801
|
ON CONFLICT(partition) DO UPDATE SET
|
|
1798
1802
|
last_authenticated_at_ms=EXCLUDED.last_authenticated_at_ms
|
|
1799
|
-
RETURNING log_epoch, epoch_required, last_authenticated_at_ms
|
|
1803
|
+
RETURNING log_epoch, epoch_required, last_authenticated_at_ms,
|
|
1804
|
+
${checkpointVersion}`, [partition, initialLogEpoch, authenticatedAtMs])).rows[0];
|
|
1800
1805
|
}
|
|
1801
1806
|
if (row === undefined)
|
|
1802
1807
|
throw new Error('partition registry write did not persist');
|
|
@@ -1805,6 +1810,7 @@ FOR EACH ROW EXECUTE FUNCTION syncular_writer_fence()`,
|
|
|
1805
1810
|
logEpoch: row.log_epoch,
|
|
1806
1811
|
epochRequired: row.epoch_required,
|
|
1807
1812
|
lastAuthenticatedAtMs: asNumber(row.last_authenticated_at_ms),
|
|
1813
|
+
checkpointSchemaVersion: row.checkpoint_schema_version ?? undefined,
|
|
1808
1814
|
};
|
|
1809
1815
|
}
|
|
1810
1816
|
async rotatePartitionLogEpoch(partition, logEpoch, authenticatedAtMs) {
|
package/dist/segment-download.js
CHANGED
|
@@ -83,7 +83,7 @@ async function downloadSegment(ctx, request) {
|
|
|
83
83
|
if (entry === undefined) {
|
|
84
84
|
throw syncError('sync.not_found', 'unknown segment (§5.5)');
|
|
85
85
|
}
|
|
86
|
-
const record = await authorizePublication(ctx, request, registry
|
|
86
|
+
const record = await authorizePublication(ctx, request, registry, entry.record);
|
|
87
87
|
return { record, bytes: entry.bytes, headers: segmentHeaders(record) };
|
|
88
88
|
}
|
|
89
89
|
async function openSegment(ctx, request) {
|
|
@@ -102,7 +102,7 @@ async function openSegment(ctx, request) {
|
|
|
102
102
|
}
|
|
103
103
|
let record;
|
|
104
104
|
try {
|
|
105
|
-
record = await authorizePublication(ctx, request, registry
|
|
105
|
+
record = await authorizePublication(ctx, request, registry, opened.record);
|
|
106
106
|
}
|
|
107
107
|
catch (error) {
|
|
108
108
|
await opened.body.cancel();
|
|
@@ -128,7 +128,7 @@ function segmentHeaders(record) {
|
|
|
128
128
|
* Select and authorize the caller's publication of a stored segment
|
|
129
129
|
* (§5.5), projected onto that publication.
|
|
130
130
|
*/
|
|
131
|
-
async function authorizePublication(ctx, request, logEpoch, stored) {
|
|
131
|
+
async function authorizePublication(ctx, request, { logEpoch, checkpointSchemaVersion }, stored) {
|
|
132
132
|
// Select the caller's own publication context. A publication under a
|
|
133
133
|
// different partition or a stale log epoch is not this caller's grant, and
|
|
134
134
|
// the entry's existence must not leak across that boundary (§5.5).
|
|
@@ -144,6 +144,8 @@ async function authorizePublication(ctx, request, logEpoch, stored) {
|
|
|
144
144
|
partition: ctx.partition,
|
|
145
145
|
actorId: ctx.actorId,
|
|
146
146
|
...(ctx.context !== undefined ? { context: ctx.context } : {}),
|
|
147
|
+
phase: 'segment-download',
|
|
148
|
+
requested,
|
|
147
149
|
});
|
|
148
150
|
// §7.3.3: leases authorize sync rounds, never downloads — an outage
|
|
149
151
|
// signal here denies (re-authorization needs live scopes, §5.5).
|
|
@@ -218,9 +220,10 @@ async function authorizePublication(ctx, request, logEpoch, stored) {
|
|
|
218
220
|
// RFC 0007: a descriptor minted before this partition declared a backfill
|
|
219
221
|
// checkpoint is not a complete window once the projection becomes
|
|
220
222
|
// checkpointed. SPEC §9 mints segments per schema version, so refuse and
|
|
221
|
-
// let the client re-pull for a fresh descriptor.
|
|
222
|
-
|
|
223
|
-
if (
|
|
223
|
+
// let the client re-pull for a fresh descriptor. `touchPartition` read the
|
|
224
|
+
// highest checkpoint version in its registry statement.
|
|
225
|
+
if (checkpointSchemaVersion !== undefined &&
|
|
226
|
+
checkpointSchemaVersion > publication.schemaVersion) {
|
|
224
227
|
throw syncError('sync.segment_expired', 'segment predates the partition backfill checkpoint — re-pull (§5.1)');
|
|
225
228
|
}
|
|
226
229
|
// The returned record is projected onto the selected publication, so its
|
package/dist/sqlite-dialect.d.ts
CHANGED
|
@@ -18,7 +18,7 @@ import type { UnitScopes } from '@syncular/core';
|
|
|
18
18
|
import { type BoundAuthoritativeQuery } from './authoritative-query.js';
|
|
19
19
|
import type { CompiledTable } from './schema.js';
|
|
20
20
|
import type { SqliteValue } from './sqlite-driver.js';
|
|
21
|
-
import type { AuthoritativeQueryRequest, ClientCursorInfo, ClientPushResult, ClientRecord, ClientRecordWriteOptions, CommitDetail, CommitMetadata, CommitMetadataQuery, CommitPruneQuery, CommitPruneResult, IndexRowScanQuery, LiveWindow, LiveWindowQuery, NewCommit, OutboxSequence, OutboxSettlement, NewReaction, PartitionRegistryEntry, PrunedReactionCounts, PushWatermark, ReactionClaimQuery, ReactionFailureUpdate, ReactionListQuery, ReactionPruneQuery, RowChangeRecord, RowChangesQuery, RowListQuery, RowScanQuery, ScopeActivityQuery, ScopeCommitActivity, ScopeValueHistoryQuery, ScopeValueQuery, StoredPushResult, StoredReaction, StoredRow, Tombstone } from './storage.js';
|
|
21
|
+
import type { AuthoritativeQueryRequest, ClientCursorInfo, ClientPushResult, ClientRecord, ClientRecordWriteOptions, CommitDetail, CommitMetadata, CommitMetadataQuery, CommitPruneQuery, CommitPruneResult, IndexRowScanQuery, LiveWindow, LiveWindowQuery, NewCommit, OutboxSequence, OutboxSettlement, NewReaction, PartitionRegistryEntry, PartitionTouch, PrunedReactionCounts, PushWatermark, ReactionClaimQuery, ReactionFailureUpdate, ReactionListQuery, ReactionPruneQuery, RowChangeRecord, RowChangesQuery, RowListQuery, RowScanQuery, ScopeActivityQuery, ScopeCommitActivity, ScopeValueHistoryQuery, ScopeValueQuery, StoredPushResult, StoredReaction, StoredRow, Tombstone } from './storage.js';
|
|
22
22
|
/**
|
|
23
23
|
* Schema DDL, one statement per `;`-delimited chunk. Native SQLite applies
|
|
24
24
|
* the whole string via `db.exec(SQLITE_DDL)`; D1 applies each statement
|
|
@@ -98,6 +98,12 @@ export declare abstract class SqliteFamilyStorage {
|
|
|
98
98
|
protected schemaVersion: number | undefined;
|
|
99
99
|
/** Bound parameters one statement accepts. */
|
|
100
100
|
protected abstract readonly maxBindParams: number;
|
|
101
|
+
/**
|
|
102
|
+
* `touchPartition`'s SQL for the partition's highest declared backfill
|
|
103
|
+
* checkpoint version, reading the partition as `?1`, or `NULL` on a storage
|
|
104
|
+
* that declares no checkpoints.
|
|
105
|
+
*/
|
|
106
|
+
protected abstract readonly checkpointSchemaVersionSql: string;
|
|
101
107
|
/** `chooseScanVariable` picks, shared with this storage's transactions. */
|
|
102
108
|
protected readonly scanVariables: Map<string, string>;
|
|
103
109
|
/** Run one statement and return its rows. */
|
|
@@ -113,7 +119,7 @@ export declare abstract class SqliteFamilyStorage {
|
|
|
113
119
|
/** Resolve a table's compiled schema; row operations require `ensureSchema`. */
|
|
114
120
|
table(name: string): CompiledTable;
|
|
115
121
|
protected prepareAuthoritativeQuery(partition: string, query: AuthoritativeQueryRequest): BoundAuthoritativeQuery;
|
|
116
|
-
touchPartition(partition: string, authenticatedAtMs: number, initialLogEpoch: string): Promise<
|
|
122
|
+
touchPartition(partition: string, authenticatedAtMs: number, initialLogEpoch: string): Promise<PartitionTouch>;
|
|
117
123
|
rotatePartitionLogEpoch(partition: string, logEpoch: string, authenticatedAtMs: number): Promise<PartitionRegistryEntry>;
|
|
118
124
|
listPartitionRegistry(): Promise<PartitionRegistryEntry[]>;
|
|
119
125
|
getMaxCommitSeq(partition: string): Promise<number>;
|
package/dist/sqlite-dialect.js
CHANGED
|
@@ -302,15 +302,19 @@ export class SqliteFamilyStorage {
|
|
|
302
302
|
],
|
|
303
303
|
},
|
|
304
304
|
{
|
|
305
|
-
sql: `SELECT partition, log_epoch, epoch_required, last_authenticated_at_ms
|
|
306
|
-
|
|
305
|
+
sql: `SELECT partition, log_epoch, epoch_required, last_authenticated_at_ms,
|
|
306
|
+
${this.checkpointSchemaVersionSql} AS checkpoint_schema_version
|
|
307
|
+
FROM sync_partition_registry WHERE partition=?1`,
|
|
307
308
|
params: [partition],
|
|
308
309
|
},
|
|
309
310
|
]);
|
|
310
311
|
const row = rows?.[0];
|
|
311
312
|
if (row === undefined)
|
|
312
313
|
throw new Error('partition registry write did not persist');
|
|
313
|
-
return
|
|
314
|
+
return {
|
|
315
|
+
...toPartitionRegistryEntry(row),
|
|
316
|
+
checkpointSchemaVersion: row.checkpoint_schema_version ?? undefined,
|
|
317
|
+
};
|
|
314
318
|
}
|
|
315
319
|
async rotatePartitionLogEpoch(partition, logEpoch, authenticatedAtMs) {
|
|
316
320
|
if (logEpoch.length === 0)
|
package/dist/sqlite-storage.d.ts
CHANGED
|
@@ -6,6 +6,7 @@ export declare class SqliteServerStorage extends SqliteFamilyStorage implements
|
|
|
6
6
|
#private;
|
|
7
7
|
readonly db: SqliteDatabase;
|
|
8
8
|
protected readonly maxBindParams: number;
|
|
9
|
+
protected readonly checkpointSchemaVersionSql = "(SELECT max(schema_version) FROM sync_backfill_checkpoints WHERE partition=?1)";
|
|
9
10
|
constructor(db?: SqliteDatabase | string);
|
|
10
11
|
protected all<T>(sql: string, params: readonly SqliteValue[]): Promise<T[]>;
|
|
11
12
|
protected guardedAll<T>(sql: string, params: readonly SqliteValue[]): Promise<T[]>;
|
package/dist/sqlite-storage.js
CHANGED
|
@@ -191,6 +191,7 @@ class SqliteTransaction extends SqliteFamilyTransaction {
|
|
|
191
191
|
export class SqliteServerStorage extends SqliteFamilyStorage {
|
|
192
192
|
db;
|
|
193
193
|
maxBindParams = Number.POSITIVE_INFINITY;
|
|
194
|
+
checkpointSchemaVersionSql = '(SELECT max(schema_version) FROM sync_backfill_checkpoints WHERE partition=?1)';
|
|
194
195
|
/**
|
|
195
196
|
* §6.4: one SQLite connection serves one caller at a time. A transaction
|
|
196
197
|
* holds it from `begin` until commit or rollback; every other call waits
|
package/dist/storage.d.ts
CHANGED
|
@@ -529,6 +529,15 @@ export interface PartitionRegistryEntry {
|
|
|
529
529
|
readonly epochRequired: boolean;
|
|
530
530
|
readonly lastAuthenticatedAtMs: number;
|
|
531
531
|
}
|
|
532
|
+
/** `touchPartition`: the registry entry, read in the same statement as the checkpoints. */
|
|
533
|
+
export interface PartitionTouch extends PartitionRegistryEntry {
|
|
534
|
+
/**
|
|
535
|
+
* RFC 0007: the highest `schemaVersion` among the partition's declared
|
|
536
|
+
* backfill checkpoints, `undefined` when it declares none. A segment
|
|
537
|
+
* download refuses a publication older than it (§5.5).
|
|
538
|
+
*/
|
|
539
|
+
readonly checkpointSchemaVersion: number | undefined;
|
|
540
|
+
}
|
|
532
541
|
/**
|
|
533
542
|
* Commit-log metadata (no change payloads) for the admin/console read
|
|
534
543
|
* surface. `changeCount` is the number of changes the commit carries;
|
|
@@ -831,7 +840,7 @@ export interface ServerStorage {
|
|
|
831
840
|
* {@link PARTITION_TOUCH_INTERVAL_MS} behind `authenticatedAtMs` is read
|
|
832
841
|
* back without a write, so a request that only reads takes no write lock.
|
|
833
842
|
*/
|
|
834
|
-
touchPartition(partition: string, authenticatedAtMs: number, initialLogEpoch: string): Promise<
|
|
843
|
+
touchPartition(partition: string, authenticatedAtMs: number, initialLogEpoch: string): Promise<PartitionTouch>;
|
|
835
844
|
/**
|
|
836
845
|
* Rotate log continuity after restore and delete the partition's client
|
|
837
846
|
* records. Watermark rows stay (§6.3.2).
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@syncular/server",
|
|
3
|
-
"version": "0.
|
|
3
|
+
"version": "0.92.0",
|
|
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.92.0"
|
|
72
72
|
},
|
|
73
73
|
"devDependencies": {
|
|
74
74
|
"@electric-sql/pglite": "^0.5.4"
|
package/src/context.ts
CHANGED
|
@@ -21,7 +21,7 @@ import type {
|
|
|
21
21
|
import type { SqliteImageBuilder } from './sqlite-image';
|
|
22
22
|
import type {
|
|
23
23
|
CheckpointDeclaration,
|
|
24
|
-
|
|
24
|
+
PartitionTouch,
|
|
25
25
|
ServerStorage,
|
|
26
26
|
StoredCommit,
|
|
27
27
|
} from './storage';
|
|
@@ -48,6 +48,16 @@ export interface ResolveScopesArgs {
|
|
|
48
48
|
* Absent when the host returned none.
|
|
49
49
|
*/
|
|
50
50
|
readonly context?: string;
|
|
51
|
+
/** Present on a direct segment download (§5.5) only. */
|
|
52
|
+
readonly phase?: 'segment-download';
|
|
53
|
+
/**
|
|
54
|
+
* The download's `X-Syncular-Scopes` map, present with `phase`. The
|
|
55
|
+
* resolver MAY answer for these values only (§3.2 step 3): `'*'` for a
|
|
56
|
+
* requested variable exactly when the full answer holds it, otherwise the
|
|
57
|
+
* requested values the actor holds; an answer that grants `'*'` carries
|
|
58
|
+
* every other variable in full.
|
|
59
|
+
*/
|
|
60
|
+
readonly requested?: ScopeMap;
|
|
51
61
|
}
|
|
52
62
|
|
|
53
63
|
/**
|
|
@@ -310,7 +320,7 @@ export function limitsOf(ctx: SyncServerConfig): ServerLimits {
|
|
|
310
320
|
*/
|
|
311
321
|
export async function touchAuthenticatedPartition(
|
|
312
322
|
ctx: SyncRequestContext,
|
|
313
|
-
): Promise<
|
|
323
|
+
): Promise<PartitionTouch> {
|
|
314
324
|
if (ctx.context !== undefined) {
|
|
315
325
|
const byteLength = new TextEncoder().encode(ctx.context).length;
|
|
316
326
|
if (byteLength > 256) throw new AuthContextTooLargeError(byteLength);
|
package/src/d1-storage.ts
CHANGED
|
@@ -906,6 +906,8 @@ export class D1ServerStorage
|
|
|
906
906
|
* binds one per app column plus the five `_sync_*` meta columns.
|
|
907
907
|
*/
|
|
908
908
|
protected readonly maxBindParams = 100;
|
|
909
|
+
// D1 declares no backfill checkpoints (see `readCheckpoints`).
|
|
910
|
+
protected readonly checkpointSchemaVersionSql = 'NULL';
|
|
909
911
|
/**
|
|
910
912
|
* Page reads waiting for the end of the current microtask turn. A pull
|
|
911
913
|
* starts the first snapshot page and scope pin of every bootstrapping unit
|
package/src/handler.ts
CHANGED
|
@@ -280,7 +280,15 @@ async function planRequest(
|
|
|
280
280
|
'epoch acquisition requests must not carry push commits (§2.1)',
|
|
281
281
|
);
|
|
282
282
|
}
|
|
283
|
-
const
|
|
283
|
+
const adopt = request.frames.some((frame) => frame.type === 'ADOPT_EPOCH');
|
|
284
|
+
if (adopt && header.logEpoch !== undefined) {
|
|
285
|
+
throw syncError(
|
|
286
|
+
'sync.invalid_request',
|
|
287
|
+
'epoch adoption requests must not carry logEpoch (§2.1)',
|
|
288
|
+
);
|
|
289
|
+
}
|
|
290
|
+
// §2.1: adoption serves the request under the current epoch.
|
|
291
|
+
const epochReset = !adopt && header.logEpoch !== registry.logEpoch;
|
|
284
292
|
const unserved = {
|
|
285
293
|
wireVersion: request.wireVersion,
|
|
286
294
|
logEpoch: registry.logEpoch,
|
package/src/postgres-storage.ts
CHANGED
|
@@ -137,6 +137,7 @@ import type {
|
|
|
137
137
|
OutboxSequence,
|
|
138
138
|
OutboxSettlement,
|
|
139
139
|
PartitionRegistryEntry,
|
|
140
|
+
PartitionTouch,
|
|
140
141
|
PreparedPushApply,
|
|
141
142
|
PushApplyOptions,
|
|
142
143
|
PrunedReactionCounts,
|
|
@@ -2567,7 +2568,7 @@ FOR EACH ROW EXECUTE FUNCTION syncular_writer_fence()`,
|
|
|
2567
2568
|
partition: string,
|
|
2568
2569
|
authenticatedAtMs: number,
|
|
2569
2570
|
initialLogEpoch: string,
|
|
2570
|
-
): Promise<
|
|
2571
|
+
): Promise<PartitionTouch> {
|
|
2571
2572
|
if (initialLogEpoch.length === 0) {
|
|
2572
2573
|
throw new Error('initial log epoch must be non-empty');
|
|
2573
2574
|
}
|
|
@@ -2575,10 +2576,15 @@ FOR EACH ROW EXECUTE FUNCTION syncular_writer_fence()`,
|
|
|
2575
2576
|
log_epoch: string;
|
|
2576
2577
|
epoch_required: boolean;
|
|
2577
2578
|
last_authenticated_at_ms: unknown;
|
|
2579
|
+
checkpoint_schema_version: number | null;
|
|
2578
2580
|
};
|
|
2581
|
+
const checkpointVersion = `(SELECT max(schema_version)
|
|
2582
|
+
FROM sync_backfill_checkpoints WHERE partition=$1)
|
|
2583
|
+
AS checkpoint_schema_version`;
|
|
2579
2584
|
let row = (
|
|
2580
2585
|
await this.#exec.query<Registry>(
|
|
2581
|
-
`SELECT log_epoch, epoch_required, last_authenticated_at_ms
|
|
2586
|
+
`SELECT log_epoch, epoch_required, last_authenticated_at_ms,
|
|
2587
|
+
${checkpointVersion}
|
|
2582
2588
|
FROM sync_partition_registry WHERE partition=$1`,
|
|
2583
2589
|
[partition],
|
|
2584
2590
|
)
|
|
@@ -2595,7 +2601,8 @@ FOR EACH ROW EXECUTE FUNCTION syncular_writer_fence()`,
|
|
|
2595
2601
|
) VALUES ($1,$2,$3)
|
|
2596
2602
|
ON CONFLICT(partition) DO UPDATE SET
|
|
2597
2603
|
last_authenticated_at_ms=EXCLUDED.last_authenticated_at_ms
|
|
2598
|
-
RETURNING log_epoch, epoch_required, last_authenticated_at_ms
|
|
2604
|
+
RETURNING log_epoch, epoch_required, last_authenticated_at_ms,
|
|
2605
|
+
${checkpointVersion}`,
|
|
2599
2606
|
[partition, initialLogEpoch, authenticatedAtMs],
|
|
2600
2607
|
)
|
|
2601
2608
|
).rows[0];
|
|
@@ -2607,6 +2614,7 @@ FOR EACH ROW EXECUTE FUNCTION syncular_writer_fence()`,
|
|
|
2607
2614
|
logEpoch: row.log_epoch,
|
|
2608
2615
|
epochRequired: row.epoch_required,
|
|
2609
2616
|
lastAuthenticatedAtMs: asNumber(row.last_authenticated_at_ms),
|
|
2617
|
+
checkpointSchemaVersion: row.checkpoint_schema_version ?? undefined,
|
|
2610
2618
|
};
|
|
2611
2619
|
}
|
|
2612
2620
|
|
package/src/segment-download.ts
CHANGED
|
@@ -25,6 +25,7 @@ import {
|
|
|
25
25
|
publicationRecord,
|
|
26
26
|
type SegmentRecord,
|
|
27
27
|
} from './segment-store';
|
|
28
|
+
import type { PartitionTouch } from './storage';
|
|
28
29
|
|
|
29
30
|
export interface SegmentDownloadRequest {
|
|
30
31
|
readonly segmentId: string;
|
|
@@ -164,7 +165,7 @@ async function downloadSegment(
|
|
|
164
165
|
const record = await authorizePublication(
|
|
165
166
|
ctx,
|
|
166
167
|
request,
|
|
167
|
-
registry
|
|
168
|
+
registry,
|
|
168
169
|
entry.record,
|
|
169
170
|
);
|
|
170
171
|
return { record, bytes: entry.bytes, headers: segmentHeaders(record) };
|
|
@@ -192,12 +193,7 @@ async function openSegment(
|
|
|
192
193
|
}
|
|
193
194
|
let record: SegmentRecord;
|
|
194
195
|
try {
|
|
195
|
-
record = await authorizePublication(
|
|
196
|
-
ctx,
|
|
197
|
-
request,
|
|
198
|
-
registry.logEpoch,
|
|
199
|
-
opened.record,
|
|
200
|
-
);
|
|
196
|
+
record = await authorizePublication(ctx, request, registry, opened.record);
|
|
201
197
|
} catch (error) {
|
|
202
198
|
await opened.body.cancel();
|
|
203
199
|
throw error;
|
|
@@ -227,7 +223,7 @@ function segmentHeaders(record: SegmentRecord): Record<string, string> {
|
|
|
227
223
|
async function authorizePublication(
|
|
228
224
|
ctx: SyncRequestContext,
|
|
229
225
|
request: SegmentDownloadRequest,
|
|
230
|
-
logEpoch:
|
|
226
|
+
{ logEpoch, checkpointSchemaVersion }: PartitionTouch,
|
|
231
227
|
stored: SegmentRecord,
|
|
232
228
|
): Promise<SegmentRecord> {
|
|
233
229
|
// Select the caller's own publication context. A publication under a
|
|
@@ -250,6 +246,8 @@ async function authorizePublication(
|
|
|
250
246
|
partition: ctx.partition,
|
|
251
247
|
actorId: ctx.actorId,
|
|
252
248
|
...(ctx.context !== undefined ? { context: ctx.context } : {}),
|
|
249
|
+
phase: 'segment-download',
|
|
250
|
+
requested,
|
|
253
251
|
});
|
|
254
252
|
// §7.3.3: leases authorize sync rounds, never downloads — an outage
|
|
255
253
|
// signal here denies (re-authorization needs live scopes, §5.5).
|
|
@@ -348,12 +346,11 @@ async function authorizePublication(
|
|
|
348
346
|
// RFC 0007: a descriptor minted before this partition declared a backfill
|
|
349
347
|
// checkpoint is not a complete window once the projection becomes
|
|
350
348
|
// checkpointed. SPEC §9 mints segments per schema version, so refuse and
|
|
351
|
-
// let the client re-pull for a fresh descriptor.
|
|
352
|
-
|
|
349
|
+
// let the client re-pull for a fresh descriptor. `touchPartition` read the
|
|
350
|
+
// highest checkpoint version in its registry statement.
|
|
353
351
|
if (
|
|
354
|
-
|
|
355
|
-
|
|
356
|
-
)
|
|
352
|
+
checkpointSchemaVersion !== undefined &&
|
|
353
|
+
checkpointSchemaVersion > publication.schemaVersion
|
|
357
354
|
) {
|
|
358
355
|
throw syncError(
|
|
359
356
|
'sync.segment_expired',
|
package/src/sqlite-dialect.ts
CHANGED
|
@@ -79,6 +79,7 @@ import type {
|
|
|
79
79
|
OutboxSettlement,
|
|
80
80
|
NewReaction,
|
|
81
81
|
PartitionRegistryEntry,
|
|
82
|
+
PartitionTouch,
|
|
82
83
|
PrunedReactionCounts,
|
|
83
84
|
PushWatermark,
|
|
84
85
|
ReactionClaimQuery,
|
|
@@ -433,6 +434,12 @@ export abstract class SqliteFamilyStorage {
|
|
|
433
434
|
protected schemaVersion: number | undefined;
|
|
434
435
|
/** Bound parameters one statement accepts. */
|
|
435
436
|
protected abstract readonly maxBindParams: number;
|
|
437
|
+
/**
|
|
438
|
+
* `touchPartition`'s SQL for the partition's highest declared backfill
|
|
439
|
+
* checkpoint version, reading the partition as `?1`, or `NULL` on a storage
|
|
440
|
+
* that declares no checkpoints.
|
|
441
|
+
*/
|
|
442
|
+
protected abstract readonly checkpointSchemaVersionSql: string;
|
|
436
443
|
/** `chooseScanVariable` picks, shared with this storage's transactions. */
|
|
437
444
|
protected readonly scanVariables = new Map<string, string>();
|
|
438
445
|
|
|
@@ -492,7 +499,7 @@ export abstract class SqliteFamilyStorage {
|
|
|
492
499
|
partition: string,
|
|
493
500
|
authenticatedAtMs: number,
|
|
494
501
|
initialLogEpoch: string,
|
|
495
|
-
): Promise<
|
|
502
|
+
): Promise<PartitionTouch> {
|
|
496
503
|
if (initialLogEpoch.length === 0) {
|
|
497
504
|
throw new Error('initial log epoch must be non-empty');
|
|
498
505
|
}
|
|
@@ -515,15 +522,23 @@ export abstract class SqliteFamilyStorage {
|
|
|
515
522
|
],
|
|
516
523
|
},
|
|
517
524
|
{
|
|
518
|
-
sql: `SELECT partition, log_epoch, epoch_required, last_authenticated_at_ms
|
|
519
|
-
|
|
525
|
+
sql: `SELECT partition, log_epoch, epoch_required, last_authenticated_at_ms,
|
|
526
|
+
${this.checkpointSchemaVersionSql} AS checkpoint_schema_version
|
|
527
|
+
FROM sync_partition_registry WHERE partition=?1`,
|
|
520
528
|
params: [partition],
|
|
521
529
|
},
|
|
522
530
|
]);
|
|
523
|
-
const row = rows?.[0] as
|
|
531
|
+
const row = rows?.[0] as
|
|
532
|
+
| (SqlitePartitionRegistryRecord & {
|
|
533
|
+
checkpoint_schema_version: number | null;
|
|
534
|
+
})
|
|
535
|
+
| undefined;
|
|
524
536
|
if (row === undefined)
|
|
525
537
|
throw new Error('partition registry write did not persist');
|
|
526
|
-
return
|
|
538
|
+
return {
|
|
539
|
+
...toPartitionRegistryEntry(row),
|
|
540
|
+
checkpointSchemaVersion: row.checkpoint_schema_version ?? undefined,
|
|
541
|
+
};
|
|
527
542
|
}
|
|
528
543
|
|
|
529
544
|
async rotatePartitionLogEpoch(
|
package/src/sqlite-storage.ts
CHANGED
|
@@ -341,6 +341,8 @@ export class SqliteServerStorage
|
|
|
341
341
|
{
|
|
342
342
|
readonly db: SqliteDatabase;
|
|
343
343
|
protected readonly maxBindParams = Number.POSITIVE_INFINITY;
|
|
344
|
+
protected readonly checkpointSchemaVersionSql =
|
|
345
|
+
'(SELECT max(schema_version) FROM sync_backfill_checkpoints WHERE partition=?1)';
|
|
344
346
|
/**
|
|
345
347
|
* §6.4: one SQLite connection serves one caller at a time. A transaction
|
|
346
348
|
* holds it from `begin` until commit or rollback; every other call waits
|
package/src/storage.ts
CHANGED
|
@@ -889,6 +889,16 @@ export interface PartitionRegistryEntry {
|
|
|
889
889
|
readonly lastAuthenticatedAtMs: number;
|
|
890
890
|
}
|
|
891
891
|
|
|
892
|
+
/** `touchPartition`: the registry entry, read in the same statement as the checkpoints. */
|
|
893
|
+
export interface PartitionTouch extends PartitionRegistryEntry {
|
|
894
|
+
/**
|
|
895
|
+
* RFC 0007: the highest `schemaVersion` among the partition's declared
|
|
896
|
+
* backfill checkpoints, `undefined` when it declares none. A segment
|
|
897
|
+
* download refuses a publication older than it (§5.5).
|
|
898
|
+
*/
|
|
899
|
+
readonly checkpointSchemaVersion: number | undefined;
|
|
900
|
+
}
|
|
901
|
+
|
|
892
902
|
/**
|
|
893
903
|
* Commit-log metadata (no change payloads) for the admin/console read
|
|
894
904
|
* surface. `changeCount` is the number of changes the commit carries;
|
|
@@ -1270,7 +1280,7 @@ export interface ServerStorage {
|
|
|
1270
1280
|
partition: string,
|
|
1271
1281
|
authenticatedAtMs: number,
|
|
1272
1282
|
initialLogEpoch: string,
|
|
1273
|
-
): Promise<
|
|
1283
|
+
): Promise<PartitionTouch>;
|
|
1274
1284
|
/**
|
|
1275
1285
|
* Rotate log continuity after restore and delete the partition's client
|
|
1276
1286
|
* records. Watermark rows stay (§6.3.2).
|