@syncular/server 0.51.0 → 0.53.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 +9 -0
- package/dist/postgres-storage.js +5 -1
- package/dist/readiness.d.ts +7 -2
- package/dist/readiness.js +19 -0
- package/dist/sqlite-dialect.d.ts +16 -4
- 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 +12 -5
- package/package.json +2 -2
- package/src/postgres-storage.ts +6 -1
- package/src/readiness.ts +33 -1
- package/src/sqlite-storage.ts +5 -0
- package/src/storage-errors.ts +3 -0
- package/src/storage.ts +12 -5
package/README.md
CHANGED
|
@@ -375,6 +375,15 @@ explicit acknowledgement, and restart-safe recovery UI together.
|
|
|
375
375
|
|
|
376
376
|
## Trusted relational-index lookups for authoritative commands
|
|
377
377
|
|
|
378
|
+
A host-owned non-push transaction can call
|
|
379
|
+
`prepareAuthorityTransaction(tx, schema.version, checkpoints)` before its
|
|
380
|
+
first authority or row read. The helper holds the partition serialization
|
|
381
|
+
lock through commit or rollback and refuses a closed schema/checkpoint gate.
|
|
382
|
+
It requires no client commit identity. SQLite and PostgreSQL implement the
|
|
383
|
+
lock; D1 and custom adapters without `lockPartition()` fail with
|
|
384
|
+
`sync.storage.partition_lock_unsupported`. See
|
|
385
|
+
[host-owned authority transactions](https://syncular.dev/guide-remote-operations/#host-owned-authority-transactions).
|
|
386
|
+
|
|
378
387
|
`scanRows` is a Syncular scope-index scan, never an unscoped administrative
|
|
379
388
|
query. Passing an empty or omitted `scopeFilter` throws the exported
|
|
380
389
|
`StorageQueryError` with `code: 'sync.storage.scan_requires_scope'` on
|
package/dist/postgres-storage.js
CHANGED
|
@@ -964,7 +964,7 @@ class PostgresTransaction {
|
|
|
964
964
|
// commit has released the partition lock to observe it. Folding the lock
|
|
965
965
|
// and the read into one statement would miss a duplicate that committed
|
|
966
966
|
// while this transaction waited.
|
|
967
|
-
await
|
|
967
|
+
await this.lockPartition();
|
|
968
968
|
const tables = [];
|
|
969
969
|
const specs = [];
|
|
970
970
|
for (const target of targets) {
|
|
@@ -980,6 +980,10 @@ class PostgresTransaction {
|
|
|
980
980
|
this.#recordPrefetched(admission.prefetched);
|
|
981
981
|
return { gate: admission.gate, persisted: admission.persisted };
|
|
982
982
|
}
|
|
983
|
+
async lockPartition() {
|
|
984
|
+
this.#assertOpen();
|
|
985
|
+
await lockPartitionOn(this.#client, this.#partition);
|
|
986
|
+
}
|
|
983
987
|
async advanceCheckpoint(name, ownerEpoch, watermark, observedRows, nowMs) {
|
|
984
988
|
this.#assertOpen();
|
|
985
989
|
await this.#ensurePushSavepoint();
|
package/dist/readiness.d.ts
CHANGED
|
@@ -8,8 +8,8 @@
|
|
|
8
8
|
*/
|
|
9
9
|
import type { SyncServerConfig } from './context.js';
|
|
10
10
|
import { type SyncError } from './errors.js';
|
|
11
|
-
import type
|
|
12
|
-
export declare const SYNC_SERVER_READINESS_ERROR_CODE:
|
|
11
|
+
import { type CheckpointDeclaration, type ServeGateRefusal, type StorageTransaction } from './storage.js';
|
|
12
|
+
export declare const SYNC_SERVER_READINESS_ERROR_CODE: 'sync.schema_not_ready';
|
|
13
13
|
export type SyncServerReadinessPhase = 'schema_compile' | 'storage_migration' | 'backfill_checkpoint';
|
|
14
14
|
export declare class SyncServerReadinessError extends Error {
|
|
15
15
|
readonly name = "SyncServerReadinessError";
|
|
@@ -35,3 +35,8 @@ export declare function ensureSyncServerReady(config: Pick<SyncServerConfig, 'sc
|
|
|
35
35
|
* name travels in structured details, never in the message.
|
|
36
36
|
*/
|
|
37
37
|
export declare function serveNotReadyError(refusal: ServeGateRefusal): SyncError;
|
|
38
|
+
/**
|
|
39
|
+
* Lock and gate a host-owned non-push transaction (§6.8). The caller checks
|
|
40
|
+
* actor authority under the lock and commits or rolls back the transaction.
|
|
41
|
+
*/
|
|
42
|
+
export declare function prepareAuthorityTransaction(tx: StorageTransaction, runningSchemaVersion: number, checkpoints?: readonly CheckpointDeclaration[]): Promise<void>;
|
package/dist/readiness.js
CHANGED
|
@@ -1,6 +1,8 @@
|
|
|
1
1
|
import { syncError } from './errors.js';
|
|
2
2
|
import { compileSchema } from './schema.js';
|
|
3
3
|
import { schemaWindowOf } from './schema-window.js';
|
|
4
|
+
import { serveGateRefusal, } from './storage.js';
|
|
5
|
+
import { StorageQueryError } from './storage-errors.js';
|
|
4
6
|
export const SYNC_SERVER_READINESS_ERROR_CODE = 'sync.schema_not_ready';
|
|
5
7
|
export class SyncServerReadinessError extends Error {
|
|
6
8
|
name = 'SyncServerReadinessError';
|
|
@@ -68,3 +70,20 @@ export function serveNotReadyError(refusal) {
|
|
|
68
70
|
runningSchemaVersion: refusal.running,
|
|
69
71
|
}));
|
|
70
72
|
}
|
|
73
|
+
/**
|
|
74
|
+
* Lock and gate a host-owned non-push transaction (§6.8). The caller checks
|
|
75
|
+
* actor authority under the lock and commits or rolls back the transaction.
|
|
76
|
+
*/
|
|
77
|
+
export async function prepareAuthorityTransaction(tx, runningSchemaVersion, checkpoints) {
|
|
78
|
+
if (!Number.isInteger(runningSchemaVersion) ||
|
|
79
|
+
runningSchemaVersion < 1 ||
|
|
80
|
+
runningSchemaVersion > 0x7fffffff)
|
|
81
|
+
throw syncError('sync.invalid_request', 'schema version must be a positive 32-bit integer');
|
|
82
|
+
if (typeof tx.lockPartition !== 'function')
|
|
83
|
+
throw new StorageQueryError('sync.storage.partition_lock_unsupported');
|
|
84
|
+
await tx.lockPartition();
|
|
85
|
+
const gate = await tx.readServeGate(runningSchemaVersion);
|
|
86
|
+
const refusal = serveGateRefusal(gate, runningSchemaVersion, checkpoints);
|
|
87
|
+
if (refusal !== undefined)
|
|
88
|
+
throw serveNotReadyError(refusal);
|
|
89
|
+
}
|
package/dist/sqlite-dialect.d.ts
CHANGED
|
@@ -39,9 +39,9 @@ import type { ScopeValueHistoryQuery, StoredChange, StoredCommit, StoredPushResu
|
|
|
39
39
|
export declare const SQLITE_DDL = "\nCREATE TABLE IF NOT EXISTS sync_partitions(\n partition TEXT PRIMARY KEY,\n max_commit_seq INTEGER NOT NULL DEFAULT 0,\n horizon_seq INTEGER NOT NULL DEFAULT 0\n);\nCREATE TABLE IF NOT EXISTS sync_partition_registry(\n partition TEXT PRIMARY KEY,\n log_epoch TEXT NOT NULL,\n epoch_required INTEGER NOT NULL DEFAULT 0,\n last_authenticated_at_ms INTEGER NOT NULL\n);\nCREATE TABLE IF NOT EXISTS sync_row_scopes(\n partition TEXT NOT NULL, tbl TEXT NOT NULL,\n var TEXT NOT NULL, value TEXT NOT NULL, row_id TEXT NOT NULL,\n PRIMARY KEY(partition, tbl, var, value, row_id)\n);\nCREATE INDEX IF NOT EXISTS sync_row_scopes_by_row\n ON sync_row_scopes(partition, tbl, row_id);\nCREATE TABLE IF NOT EXISTS sync_commits(\n partition TEXT NOT NULL, commit_seq INTEGER NOT NULL,\n client_id TEXT NOT NULL, client_commit_id TEXT NOT NULL,\n actor_id TEXT NOT NULL, created_at_ms INTEGER NOT NULL,\n writer_version INTEGER,\n PRIMARY KEY(partition, commit_seq)\n);\nCREATE INDEX IF NOT EXISTS sync_commits_by_time\n ON sync_commits(partition, created_at_ms);\nCREATE TABLE IF NOT EXISTS sync_changes(\n partition TEXT NOT NULL, commit_seq INTEGER NOT NULL, idx INTEGER NOT NULL,\n tbl TEXT NOT NULL, row_id TEXT NOT NULL, op INTEGER NOT NULL,\n row_version INTEGER, scopes TEXT NOT NULL, payload BLOB,\n PRIMARY KEY(partition, commit_seq, idx)\n);\nCREATE INDEX IF NOT EXISTS sync_changes_by_table\n ON sync_changes(partition, commit_seq, tbl, idx);\nCREATE TABLE IF NOT EXISTS sync_change_scopes(\n partition TEXT NOT NULL, tbl TEXT NOT NULL,\n var TEXT NOT NULL, value TEXT NOT NULL, commit_seq INTEGER NOT NULL,\n PRIMARY KEY(partition, tbl, var, value, commit_seq)\n);\nCREATE TABLE IF NOT EXISTS sync_push_results(\n partition TEXT NOT NULL, client_id TEXT NOT NULL,\n client_commit_id TEXT NOT NULL, result TEXT NOT NULL,\n PRIMARY KEY(partition, client_id, client_commit_id)\n);\nCREATE TABLE IF NOT EXISTS sync_reactions(\n partition TEXT NOT NULL, idempotency_key TEXT NOT NULL,\n type TEXT NOT NULL, version INTEGER NOT NULL, payload TEXT NOT NULL,\n source_client_id TEXT NOT NULL, source_client_commit_id TEXT NOT NULL,\n source_commit_seq INTEGER NOT NULL, created_at_ms INTEGER NOT NULL,\n available_at_ms INTEGER NOT NULL, status TEXT NOT NULL,\n attempts INTEGER NOT NULL, max_attempts INTEGER NOT NULL,\n lease_owner TEXT, lease_expires_at_ms INTEGER, completed_at_ms INTEGER,\n last_failure TEXT,\n PRIMARY KEY(partition, idempotency_key),\n CHECK(status IN ('pending', 'leased', 'completed', 'dead-letter'))\n);\nCREATE INDEX IF NOT EXISTS sync_reactions_due\n ON sync_reactions(partition, status, available_at_ms, created_at_ms, idempotency_key);\nCREATE INDEX IF NOT EXISTS sync_reactions_lease\n ON sync_reactions(partition, status, lease_expires_at_ms);\nCREATE INDEX IF NOT EXISTS sync_reactions_completed\n ON sync_reactions(partition, status, completed_at_ms, idempotency_key);\nCREATE INDEX IF NOT EXISTS sync_reactions_dead_letter\n ON sync_reactions(partition, status, available_at_ms, idempotency_key);\nCREATE TABLE IF NOT EXISTS sync_clients(\n partition TEXT NOT NULL, client_id TEXT NOT NULL, actor_id TEXT NOT NULL,\n wire_version INTEGER NOT NULL DEFAULT 1,\n cursor INTEGER NOT NULL, subscriptions TEXT NOT NULL,\n updated_at_ms INTEGER NOT NULL,\n last_round_at_ms INTEGER, last_error_code TEXT,\n consecutive_failures INTEGER NOT NULL DEFAULT 0,\n PRIMARY KEY(partition, client_id)\n);\nCREATE TABLE IF NOT EXISTS sync_blob_refs(\n partition TEXT NOT NULL, tbl TEXT NOT NULL, row_id TEXT NOT NULL,\n blob_id TEXT NOT NULL,\n PRIMARY KEY(partition, tbl, row_id, blob_id)\n);\nCREATE INDEX IF NOT EXISTS sync_blob_refs_by_blob\n ON sync_blob_refs(partition, blob_id);\nCREATE TABLE IF NOT EXISTS sync_tombstones(\n partition TEXT NOT NULL, tbl TEXT NOT NULL, row_id TEXT NOT NULL,\n commit_seq INTEGER NOT NULL,\n PRIMARY KEY(partition, tbl, row_id)\n);\nCREATE TABLE IF NOT EXISTS sync_backfill_checkpoints(\n partition TEXT NOT NULL, name TEXT NOT NULL,\n schema_version INTEGER NOT NULL,\n state TEXT NOT NULL CHECK(state IN ('declared','backfilling','activated')),\n watermark INTEGER NOT NULL DEFAULT 0,\n owner_epoch INTEGER NOT NULL DEFAULT 0,\n observed_rows INTEGER NOT NULL DEFAULT 0,\n updated_at_ms INTEGER NOT NULL,\n PRIMARY KEY(partition, name)\n);\nCREATE TABLE IF NOT EXISTS sync_writer_fence(\n partition TEXT PRIMARY KEY,\n required_writer_version INTEGER NOT NULL\n);\n";
|
|
40
40
|
/** Columns added to `sync_clients` after its first release, by column name. */
|
|
41
41
|
export declare const SYNC_CLIENT_ROUND_COLUMNS: {
|
|
42
|
-
readonly last_round_at_ms:
|
|
43
|
-
readonly last_error_code:
|
|
44
|
-
readonly consecutive_failures:
|
|
42
|
+
readonly last_round_at_ms: 'INTEGER';
|
|
43
|
+
readonly last_error_code: 'TEXT';
|
|
44
|
+
readonly consecutive_failures: 'INTEGER NOT NULL DEFAULT 0';
|
|
45
45
|
};
|
|
46
46
|
/** Split the DDL into individual statements (D1 applies them one by one). */
|
|
47
47
|
export declare function sqliteDdlStatements(): string[];
|
|
@@ -53,7 +53,19 @@ export declare const LIST_SCOPE_VALUE_ROWS_SQLITE_SQL = "SELECT row_id FROM sync
|
|
|
53
53
|
* no longer holds a change of the binding. Each returns one row per removed
|
|
54
54
|
* record (D1 batch results carry no reliable change count).
|
|
55
55
|
*/
|
|
56
|
-
export declare const ERASE_SCOPE_VALUE_HISTORY_SQLITE_SQL: readonly [
|
|
56
|
+
export declare const ERASE_SCOPE_VALUE_HISTORY_SQLITE_SQL: readonly [`DELETE FROM sync_changes WHERE rowid IN (
|
|
57
|
+
SELECT c.rowid FROM sync_change_scopes s JOIN sync_changes c
|
|
58
|
+
ON c.partition=s.partition AND c.commit_seq=s.commit_seq AND c.tbl=s.tbl
|
|
59
|
+
WHERE s.partition=?1 AND s.tbl=?2 AND s.var=?3 AND s.value=?4
|
|
60
|
+
AND s.commit_seq<=?5 AND c.op=1 AND json_extract(c.scopes, ?6)=s.value
|
|
61
|
+
LIMIT ?7) RETURNING 1 AS removed`, `DELETE FROM sync_change_scopes WHERE rowid IN (
|
|
62
|
+
SELECT s.rowid FROM sync_change_scopes s
|
|
63
|
+
WHERE s.partition=?1 AND s.tbl=?2 AND s.var=?3 AND s.value=?4
|
|
64
|
+
AND s.commit_seq<=?5 AND NOT EXISTS (
|
|
65
|
+
SELECT 1 FROM sync_changes c
|
|
66
|
+
WHERE c.partition=s.partition AND c.commit_seq=s.commit_seq
|
|
67
|
+
AND c.tbl=s.tbl AND json_extract(c.scopes, ?6)=s.value)
|
|
68
|
+
LIMIT ?7) RETURNING 1 AS removed`];
|
|
57
69
|
export declare function eraseScopeValueHistoryParams(partition: string, query: ScopeValueHistoryQuery): [string, string, string, string, number, string, number];
|
|
58
70
|
/** `?,?,…` for an `IN (…)` clause of `count` positional parameters. */
|
|
59
71
|
export declare function placeholders(count: number): string;
|
package/dist/sqlite-storage.js
CHANGED
|
@@ -128,6 +128,10 @@ class SqliteTransaction {
|
|
|
128
128
|
persisted: await this.#storage.getPushResult(this.#partition, clientId, clientCommitId),
|
|
129
129
|
};
|
|
130
130
|
}
|
|
131
|
+
async lockPartition() {
|
|
132
|
+
this.#assertOpen();
|
|
133
|
+
// BEGIN IMMEDIATE in the constructor already owns SQLite's writer lock.
|
|
134
|
+
}
|
|
131
135
|
async advanceCheckpoint(name, ownerEpoch, watermark, observedRows, nowMs) {
|
|
132
136
|
this.#assertOpen();
|
|
133
137
|
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.physical_layout_mismatch' | 'sync.storage.transaction_query_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.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';
|
|
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
|
@@ -26,6 +26,7 @@ const STORAGE_QUERY_MESSAGES = {
|
|
|
26
26
|
'sync.storage.stored_layout_mismatch': 'stored schema layouts disagree with the configured schema at the same version',
|
|
27
27
|
'sync.storage.physical_layout_mismatch': 'a synced table does not match the storage layout the running code reads and writes',
|
|
28
28
|
'sync.storage.transaction_query_unsupported': 'this storage transaction cannot run registered queries',
|
|
29
|
+
'sync.storage.partition_lock_unsupported': 'this storage transaction cannot serialize partition authority',
|
|
29
30
|
'sync.storage.query_over_staged_writes': 'registered query reads a table this transaction has buffered writes for',
|
|
30
31
|
'sync.storage.scan_requires_scope': 'scope-indexed row scans require at least one scope variable',
|
|
31
32
|
'sync.storage.index_not_found': 'trusted row lookup requires a declared relational index',
|
package/dist/storage.d.ts
CHANGED
|
@@ -491,6 +491,13 @@ export interface StorageTransaction {
|
|
|
491
491
|
* table this transaction has written.
|
|
492
492
|
*/
|
|
493
493
|
queryAuthoritative?(query: AuthoritativeQueryRequest): Promise<AuthoritativeQueryResult>;
|
|
494
|
+
/**
|
|
495
|
+
* Acquire the push-serialization lock until commit or rollback. This
|
|
496
|
+
* capability does not evaluate the serve gate; host-owned authority paths
|
|
497
|
+
* use `prepareAuthorityTransaction` before reading or writing. Optional so
|
|
498
|
+
* existing custom storage implementations fail closed at that boundary.
|
|
499
|
+
*/
|
|
500
|
+
lockPartition?(): Promise<void>;
|
|
494
501
|
/**
|
|
495
502
|
* Serialize every push apply for this partition before any operation read,
|
|
496
503
|
* validation, merge, or write, and read the admission token in the same
|
|
@@ -601,11 +608,11 @@ export interface ServerStorage {
|
|
|
601
608
|
* against a concurrent push; PostgreSQL's `BEGIN` takes no row lock, so the
|
|
602
609
|
* same command races a push on Postgres and a SQLite-only test conceals it.
|
|
603
610
|
*
|
|
604
|
-
* A trusted command
|
|
605
|
-
*
|
|
606
|
-
* transaction
|
|
607
|
-
* version, or
|
|
608
|
-
*
|
|
611
|
+
* A trusted command may run through `registerRemoteCommand`, which builds
|
|
612
|
+
* after `preparePushApply` and shares the committed transaction. A
|
|
613
|
+
* host-owned non-push transaction calls `prepareAuthorityTransaction`
|
|
614
|
+
* before its first authority, version, or application-row read. SSP2
|
|
615
|
+
* request handling takes its own push boundary.
|
|
609
616
|
*/
|
|
610
617
|
begin(partition: string): Promise<StorageTransaction>;
|
|
611
618
|
getMaxCommitSeq(partition: string): Promise<number>;
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@syncular/server",
|
|
3
|
-
"version": "0.
|
|
3
|
+
"version": "0.53.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.53.0"
|
|
72
72
|
},
|
|
73
73
|
"devDependencies": {
|
|
74
74
|
"@electric-sql/pglite": "^0.5.4"
|
package/src/postgres-storage.ts
CHANGED
|
@@ -1488,7 +1488,7 @@ class PostgresTransaction implements StorageTransaction {
|
|
|
1488
1488
|
// commit has released the partition lock to observe it. Folding the lock
|
|
1489
1489
|
// and the read into one statement would miss a duplicate that committed
|
|
1490
1490
|
// while this transaction waited.
|
|
1491
|
-
await
|
|
1491
|
+
await this.lockPartition();
|
|
1492
1492
|
const tables: CompiledTable[] = [];
|
|
1493
1493
|
const specs: { tbl: string; ids: string[] }[] = [];
|
|
1494
1494
|
for (const target of targets) {
|
|
@@ -1513,6 +1513,11 @@ class PostgresTransaction implements StorageTransaction {
|
|
|
1513
1513
|
return { gate: admission.gate, persisted: admission.persisted };
|
|
1514
1514
|
}
|
|
1515
1515
|
|
|
1516
|
+
async lockPartition(): Promise<void> {
|
|
1517
|
+
this.#assertOpen();
|
|
1518
|
+
await lockPartitionOn(this.#client, this.#partition);
|
|
1519
|
+
}
|
|
1520
|
+
|
|
1516
1521
|
async advanceCheckpoint(
|
|
1517
1522
|
name: string,
|
|
1518
1523
|
ownerEpoch: number,
|
package/src/readiness.ts
CHANGED
|
@@ -10,7 +10,13 @@ import type { SyncServerConfig } from './context';
|
|
|
10
10
|
import { type SyncError, syncError } from './errors';
|
|
11
11
|
import { type CompiledSchema, compileSchema } from './schema';
|
|
12
12
|
import { schemaWindowOf } from './schema-window';
|
|
13
|
-
import
|
|
13
|
+
import {
|
|
14
|
+
type CheckpointDeclaration,
|
|
15
|
+
type ServeGateRefusal,
|
|
16
|
+
type StorageTransaction,
|
|
17
|
+
serveGateRefusal,
|
|
18
|
+
} from './storage';
|
|
19
|
+
import { StorageQueryError } from './storage-errors';
|
|
14
20
|
|
|
15
21
|
export const SYNC_SERVER_READINESS_ERROR_CODE =
|
|
16
22
|
'sync.schema_not_ready' as const;
|
|
@@ -104,3 +110,29 @@ export function serveNotReadyError(refusal: ServeGateRefusal): SyncError {
|
|
|
104
110
|
}),
|
|
105
111
|
);
|
|
106
112
|
}
|
|
113
|
+
|
|
114
|
+
/**
|
|
115
|
+
* Lock and gate a host-owned non-push transaction (§6.8). The caller checks
|
|
116
|
+
* actor authority under the lock and commits or rolls back the transaction.
|
|
117
|
+
*/
|
|
118
|
+
export async function prepareAuthorityTransaction(
|
|
119
|
+
tx: StorageTransaction,
|
|
120
|
+
runningSchemaVersion: number,
|
|
121
|
+
checkpoints?: readonly CheckpointDeclaration[],
|
|
122
|
+
): Promise<void> {
|
|
123
|
+
if (
|
|
124
|
+
!Number.isInteger(runningSchemaVersion) ||
|
|
125
|
+
runningSchemaVersion < 1 ||
|
|
126
|
+
runningSchemaVersion > 0x7fffffff
|
|
127
|
+
)
|
|
128
|
+
throw syncError(
|
|
129
|
+
'sync.invalid_request',
|
|
130
|
+
'schema version must be a positive 32-bit integer',
|
|
131
|
+
);
|
|
132
|
+
if (typeof tx.lockPartition !== 'function')
|
|
133
|
+
throw new StorageQueryError('sync.storage.partition_lock_unsupported');
|
|
134
|
+
await tx.lockPartition();
|
|
135
|
+
const gate = await tx.readServeGate(runningSchemaVersion);
|
|
136
|
+
const refusal = serveGateRefusal(gate, runningSchemaVersion, checkpoints);
|
|
137
|
+
if (refusal !== undefined) throw serveNotReadyError(refusal);
|
|
138
|
+
}
|
package/src/sqlite-storage.ts
CHANGED
|
@@ -315,6 +315,11 @@ class SqliteTransaction implements StorageTransaction {
|
|
|
315
315
|
};
|
|
316
316
|
}
|
|
317
317
|
|
|
318
|
+
async lockPartition(): Promise<void> {
|
|
319
|
+
this.#assertOpen();
|
|
320
|
+
// BEGIN IMMEDIATE in the constructor already owns SQLite's writer lock.
|
|
321
|
+
}
|
|
322
|
+
|
|
318
323
|
async advanceCheckpoint(
|
|
319
324
|
name: string,
|
|
320
325
|
ownerEpoch: number,
|
package/src/storage-errors.ts
CHANGED
|
@@ -34,6 +34,7 @@ export type StorageQueryErrorCode =
|
|
|
34
34
|
| 'sync.storage.stored_layout_mismatch'
|
|
35
35
|
| 'sync.storage.physical_layout_mismatch'
|
|
36
36
|
| 'sync.storage.transaction_query_unsupported'
|
|
37
|
+
| 'sync.storage.partition_lock_unsupported'
|
|
37
38
|
| 'sync.storage.query_over_staged_writes'
|
|
38
39
|
| 'sync.storage.erase_unsupported'
|
|
39
40
|
| 'sync.storage.invalid_erase_query';
|
|
@@ -68,6 +69,8 @@ const STORAGE_QUERY_MESSAGES: Readonly<Record<StorageQueryErrorCode, string>> =
|
|
|
68
69
|
'a synced table does not match the storage layout the running code reads and writes',
|
|
69
70
|
'sync.storage.transaction_query_unsupported':
|
|
70
71
|
'this storage transaction cannot run registered queries',
|
|
72
|
+
'sync.storage.partition_lock_unsupported':
|
|
73
|
+
'this storage transaction cannot serialize partition authority',
|
|
71
74
|
'sync.storage.query_over_staged_writes':
|
|
72
75
|
'registered query reads a table this transaction has buffered writes for',
|
|
73
76
|
'sync.storage.scan_requires_scope':
|
package/src/storage.ts
CHANGED
|
@@ -630,6 +630,13 @@ export interface StorageTransaction {
|
|
|
630
630
|
queryAuthoritative?(
|
|
631
631
|
query: AuthoritativeQueryRequest,
|
|
632
632
|
): Promise<AuthoritativeQueryResult>;
|
|
633
|
+
/**
|
|
634
|
+
* Acquire the push-serialization lock until commit or rollback. This
|
|
635
|
+
* capability does not evaluate the serve gate; host-owned authority paths
|
|
636
|
+
* use `prepareAuthorityTransaction` before reading or writing. Optional so
|
|
637
|
+
* existing custom storage implementations fail closed at that boundary.
|
|
638
|
+
*/
|
|
639
|
+
lockPartition?(): Promise<void>;
|
|
633
640
|
/**
|
|
634
641
|
* Serialize every push apply for this partition before any operation read,
|
|
635
642
|
* validation, merge, or write, and read the admission token in the same
|
|
@@ -795,11 +802,11 @@ export interface ServerStorage {
|
|
|
795
802
|
* against a concurrent push; PostgreSQL's `BEGIN` takes no row lock, so the
|
|
796
803
|
* same command races a push on Postgres and a SQLite-only test conceals it.
|
|
797
804
|
*
|
|
798
|
-
* A trusted command
|
|
799
|
-
*
|
|
800
|
-
* transaction
|
|
801
|
-
* version, or
|
|
802
|
-
*
|
|
805
|
+
* A trusted command may run through `registerRemoteCommand`, which builds
|
|
806
|
+
* after `preparePushApply` and shares the committed transaction. A
|
|
807
|
+
* host-owned non-push transaction calls `prepareAuthorityTransaction`
|
|
808
|
+
* before its first authority, version, or application-row read. SSP2
|
|
809
|
+
* request handling takes its own push boundary.
|
|
803
810
|
*/
|
|
804
811
|
begin(partition: string): Promise<StorageTransaction>;
|
|
805
812
|
|