@syncular/client 0.58.0 → 0.60.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 +34 -34
- package/dist/apply.d.ts +24 -14
- package/dist/apply.js +119 -70
- package/dist/authority.js +21 -16
- package/dist/blob.d.ts +17 -9
- package/dist/blob.js +5 -6
- package/dist/bun-database.d.ts +1 -0
- package/dist/bun-database.js +15 -0
- package/dist/client.d.ts +83 -75
- package/dist/client.js +982 -910
- package/dist/database.d.ts +5 -0
- package/dist/devtools.d.ts +2 -2
- package/dist/devtools.js +3 -3
- package/dist/diagnostics.d.ts +17 -28
- package/dist/diagnostics.js +1 -2
- package/dist/encryption.d.ts +2 -2
- package/dist/encryption.js +8 -2
- package/dist/errors.d.ts +3 -1
- package/dist/errors.js +5 -1
- package/dist/failed-overlay.d.ts +0 -1
- package/dist/failed-overlay.js +6 -6
- package/dist/http.d.ts +4 -1
- package/dist/http.js +67 -39
- package/dist/index.d.ts +1 -1
- package/dist/index.js +1 -1
- package/dist/invalidation.d.ts +14 -14
- package/dist/invalidation.js +24 -48
- package/dist/local-purge.js +9 -12
- package/dist/local-rebootstrap.js +2 -2
- package/dist/multi-tab.d.ts +89 -1
- package/dist/multi-tab.js +70 -31
- package/dist/native-bridge.d.ts +226 -0
- package/dist/native-bridge.js +764 -0
- package/dist/node-database.d.ts +1 -0
- package/dist/node-database.js +21 -1
- package/dist/outbox.d.ts +9 -12
- package/dist/outbox.js +20 -36
- package/dist/outcomes.js +3 -3
- package/dist/previous-version.js +96 -114
- package/dist/progress.d.ts +2 -2
- package/dist/query-guard.d.ts +34 -24
- package/dist/query-guard.js +61 -186
- package/dist/reactive-store.js +55 -13
- package/dist/realtime-supervisor.d.ts +9 -2
- package/dist/realtime-supervisor.js +31 -7
- package/dist/remote.js +19 -23
- package/dist/schema.d.ts +3 -2
- package/dist/schema.js +43 -22
- package/dist/state.d.ts +69 -36
- package/dist/state.js +178 -89
- package/dist/sync-scheduler.js +28 -2
- package/dist/transport.d.ts +19 -4
- package/dist/wasm-database.js +58 -21
- package/dist/window.d.ts +30 -52
- package/dist/window.js +33 -77
- package/dist/worker-core.d.ts +5 -0
- package/dist/worker-core.js +83 -75
- package/dist/worker-host.d.ts +19 -13
- package/dist/worker-host.js +75 -18
- package/dist/worker-local-authority.js +2 -2
- package/dist/worker-protocol.d.ts +15 -10
- package/package.json +11 -3
- package/src/apply.ts +176 -86
- package/src/authority.ts +31 -17
- package/src/blob.ts +28 -15
- package/src/bun-database.ts +24 -0
- package/src/client.ts +1282 -1217
- package/src/database.ts +5 -0
- package/src/devtools.ts +5 -5
- package/src/diagnostics.ts +17 -37
- package/src/encryption.ts +10 -5
- package/src/errors.ts +9 -1
- package/src/failed-overlay.ts +8 -7
- package/src/http.ts +95 -79
- package/src/index.ts +1 -1
- package/src/invalidation.ts +26 -61
- package/src/local-purge.ts +11 -13
- package/src/local-rebootstrap.ts +2 -3
- package/src/multi-tab.ts +88 -30
- package/src/native-bridge.ts +1153 -0
- package/src/node-database.ts +32 -1
- package/src/outbox.ts +20 -41
- package/src/outcomes.ts +3 -5
- package/src/previous-version.ts +103 -114
- package/src/progress.ts +2 -2
- package/src/query-guard.ts +77 -177
- package/src/reactive-store.ts +52 -12
- package/src/realtime-supervisor.ts +37 -12
- package/src/remote.ts +23 -31
- package/src/schema.ts +67 -25
- package/src/state.ts +246 -125
- package/src/sync-scheduler.ts +31 -1
- package/src/transport.ts +21 -2
- package/src/wasm-database.ts +76 -27
- package/src/window.ts +55 -134
- package/src/worker-core.ts +97 -77
- package/src/worker-host.ts +76 -32
- package/src/worker-local-authority.ts +2 -5
- package/src/worker-protocol.ts +14 -10
package/dist/state.js
CHANGED
|
@@ -1,72 +1,163 @@
|
|
|
1
1
|
export const META_TABLE = '_syncular_meta';
|
|
2
2
|
import { PENDING_EVICTIONS } from './window.js';
|
|
3
3
|
import { WINDOWS_TABLE } from './window.js';
|
|
4
|
-
export const
|
|
4
|
+
export const UNITS_TABLE = '_syncular_units';
|
|
5
5
|
import { ClientSyncError } from './errors.js';
|
|
6
6
|
export const LOCAL_REVISION_KEY = 'localRevision';
|
|
7
|
+
/** §4.5 replica cursor; absent means `-1`. */
|
|
8
|
+
export const REPLICA_CURSOR_KEY = 'replicaCursor';
|
|
9
|
+
/** Hex of the last pull `LIVE_END.echoDigest` (§4.2); absent means empty. */
|
|
10
|
+
export const ECHO_DIGEST_KEY = 'echoDigest';
|
|
11
|
+
/** Hex of the registration digest of the list the server stores (§4.1). */
|
|
12
|
+
export const REGISTERED_DIGEST_KEY = 'registrationDigest';
|
|
7
13
|
const MAX_U64 = 18446744073709551615n;
|
|
14
|
+
/** §4.1: a catching-up unit holding cursor `-1` or a resume token. */
|
|
15
|
+
export function bootstrapping(unit) {
|
|
16
|
+
return (unit.cursor !== undefined &&
|
|
17
|
+
(unit.cursor < 0 || unit.bootstrapState !== undefined));
|
|
18
|
+
}
|
|
19
|
+
/** §3.3 row ownership: active, live or post-bootstrap, with an echo. */
|
|
20
|
+
export function owning(unit) {
|
|
21
|
+
return (unit.status === 'active' && unit.echo !== undefined && !bootstrapping(unit));
|
|
22
|
+
}
|
|
23
|
+
/** §4.1: the unit covers every table declaring all of its variables. */
|
|
24
|
+
export function covers(table, scopes) {
|
|
25
|
+
return Object.keys(scopes).every((variable) => table.scopeColumnByVariable.has(variable));
|
|
26
|
+
}
|
|
27
|
+
/**
|
|
28
|
+
* §4.4: the effective scopes of the (unit, table) pair under `echo`: the
|
|
29
|
+
* scope map as one-element lists plus the fenced lists. Undefined when the
|
|
30
|
+
* fence revoked the pair.
|
|
31
|
+
*/
|
|
32
|
+
export function pairScopes(scopes, table, echo) {
|
|
33
|
+
const fenced = echo?.find((record) => record.table === table);
|
|
34
|
+
if (fenced?.status === 'revoked')
|
|
35
|
+
return undefined;
|
|
36
|
+
const effective = { ...fenced?.scopes };
|
|
37
|
+
for (const [variable, value] of Object.entries(scopes))
|
|
38
|
+
effective[variable] = [value];
|
|
39
|
+
return effective;
|
|
40
|
+
}
|
|
41
|
+
/** §3.3 row ownership: the pair scopes of every owner of `table` but one.
|
|
42
|
+
* A bootstrapping unit owns the tables its current bootstrap seeded. */
|
|
43
|
+
export function unitOwners(units, table, exceptId) {
|
|
44
|
+
return units.flatMap((unit) => {
|
|
45
|
+
const scopes = unit.id !== exceptId &&
|
|
46
|
+
(owning(unit) ||
|
|
47
|
+
(unit.status === 'active' &&
|
|
48
|
+
unit.echo !== undefined &&
|
|
49
|
+
unit.seeded.includes(table.name))) &&
|
|
50
|
+
covers(table, unit.scopes)
|
|
51
|
+
? pairScopes(unit.scopes, table.name, unit.echo)
|
|
52
|
+
: undefined;
|
|
53
|
+
return scopes === undefined ? [] : [scopes];
|
|
54
|
+
});
|
|
55
|
+
}
|
|
56
|
+
/** A unit row; every persisted field must have its stored type and shape,
|
|
57
|
+
* otherwise the row is `sync.local_corrupt` (§7.5). */
|
|
8
58
|
function rowToRecord(row) {
|
|
9
|
-
|
|
10
|
-
|
|
11
|
-
|
|
12
|
-
|
|
13
|
-
|
|
14
|
-
|
|
15
|
-
|
|
16
|
-
|
|
17
|
-
|
|
18
|
-
|
|
19
|
-
|
|
20
|
-
|
|
21
|
-
|
|
22
|
-
|
|
23
|
-
|
|
24
|
-
|
|
25
|
-
|
|
26
|
-
|
|
59
|
+
const corrupt = () => new ClientSyncError('sync.local_corrupt', 'persisted unit state is invalid');
|
|
60
|
+
const json = (raw) => {
|
|
61
|
+
if (typeof raw !== 'string')
|
|
62
|
+
throw corrupt();
|
|
63
|
+
try {
|
|
64
|
+
return JSON.parse(raw);
|
|
65
|
+
}
|
|
66
|
+
catch {
|
|
67
|
+
throw corrupt();
|
|
68
|
+
}
|
|
69
|
+
};
|
|
70
|
+
const isMap = (value) => typeof value === 'object' && value !== null && !Array.isArray(value);
|
|
71
|
+
const isStrings = (value) => Array.isArray(value) && value.every((item) => typeof item === 'string');
|
|
72
|
+
const optionalText = (value) => {
|
|
73
|
+
if (value !== null && typeof value !== 'string')
|
|
74
|
+
throw corrupt();
|
|
75
|
+
return value ?? undefined;
|
|
76
|
+
};
|
|
77
|
+
const scopes = json(row.scopes);
|
|
78
|
+
const seeded = json(row.seeded);
|
|
79
|
+
const echo = row.echo === null ? undefined : json(row.echo);
|
|
80
|
+
const { id, status, cursor } = row;
|
|
81
|
+
if (typeof id !== 'string' ||
|
|
82
|
+
!isMap(scopes) ||
|
|
83
|
+
!Object.values(scopes).every((value) => typeof value === 'string') ||
|
|
84
|
+
(status !== 'active' && status !== 'revoked' && status !== 'failed') ||
|
|
85
|
+
(cursor !== null && !Number.isInteger(cursor)) ||
|
|
86
|
+
!isStrings(seeded) ||
|
|
87
|
+
(echo !== undefined &&
|
|
88
|
+
!(Array.isArray(echo) &&
|
|
89
|
+
echo.every((record) => isMap(record) &&
|
|
90
|
+
typeof record.table === 'string' &&
|
|
91
|
+
(record.status === 'active' || record.status === 'revoked') &&
|
|
92
|
+
isMap(record.scopes) &&
|
|
93
|
+
Object.values(record.scopes).every(isStrings)))))
|
|
94
|
+
throw corrupt();
|
|
95
|
+
const record = {
|
|
96
|
+
id,
|
|
97
|
+
scopes: scopes,
|
|
98
|
+
explicit: row.explicit === 1,
|
|
99
|
+
status,
|
|
100
|
+
seeded,
|
|
27
101
|
};
|
|
102
|
+
const reasonCode = optionalText(row.reason_code);
|
|
103
|
+
if (reasonCode !== undefined)
|
|
104
|
+
record.reasonCode = reasonCode;
|
|
105
|
+
if (typeof cursor === 'number')
|
|
106
|
+
record.cursor = cursor;
|
|
107
|
+
const bootstrapState = optionalText(row.bootstrap_state);
|
|
108
|
+
if (bootstrapState !== undefined)
|
|
109
|
+
record.bootstrapState = bootstrapState;
|
|
110
|
+
if (echo !== undefined)
|
|
111
|
+
record.echo = echo;
|
|
112
|
+
return record;
|
|
28
113
|
}
|
|
29
|
-
|
|
114
|
+
/** Every unit in registration order (§4.1). */
|
|
115
|
+
export function loadUnits(db) {
|
|
30
116
|
return db
|
|
31
|
-
.query(`SELECT * FROM ${
|
|
117
|
+
.query(`SELECT * FROM ${UNITS_TABLE} ORDER BY rowid ASC`)
|
|
32
118
|
.map(rowToRecord);
|
|
33
119
|
}
|
|
34
|
-
export function
|
|
35
|
-
const row = db.query(`SELECT * FROM ${
|
|
36
|
-
id,
|
|
37
|
-
])[0];
|
|
120
|
+
export function getUnit(db, id) {
|
|
121
|
+
const row = db.query(`SELECT * FROM ${UNITS_TABLE} WHERE id=?`, [id])[0];
|
|
38
122
|
return row === undefined ? undefined : rowToRecord(row);
|
|
39
123
|
}
|
|
40
|
-
|
|
41
|
-
|
|
124
|
+
/** Insert or update in place: an update keeps the registration order. */
|
|
125
|
+
export function saveUnit(db, record) {
|
|
126
|
+
db.exec(`INSERT INTO ${UNITS_TABLE}(id,scopes,explicit,status,reason_code,cursor,bootstrap_state,seeded,echo)VALUES(?,?,?,?,?,?,?,?,?)ON CONFLICT(id)DO UPDATE SET explicit=excluded.explicit,status=excluded.status,reason_code=excluded.reason_code,cursor=excluded.cursor,bootstrap_state=excluded.bootstrap_state,seeded=excluded.seeded,echo=excluded.echo`, [
|
|
42
127
|
record.id,
|
|
43
|
-
record.table,
|
|
44
128
|
JSON.stringify(record.scopes),
|
|
45
|
-
record.
|
|
46
|
-
record.cursor,
|
|
47
|
-
record.bootstrapState ?? null,
|
|
48
|
-
record.effectiveScopes === undefined
|
|
49
|
-
? null
|
|
50
|
-
: JSON.stringify(record.effectiveScopes),
|
|
129
|
+
record.explicit ? 1 : 0,
|
|
51
130
|
record.status,
|
|
52
131
|
record.reasonCode ?? null,
|
|
132
|
+
record.cursor ?? null,
|
|
133
|
+
record.bootstrapState ?? null,
|
|
134
|
+
JSON.stringify(record.seeded),
|
|
135
|
+
record.echo === undefined ? null : JSON.stringify(record.echo),
|
|
53
136
|
]);
|
|
54
137
|
}
|
|
55
|
-
export function
|
|
56
|
-
db.exec(`DELETE FROM ${
|
|
138
|
+
export function deleteUnit(db, id) {
|
|
139
|
+
db.exec(`DELETE FROM ${UNITS_TABLE} WHERE id=?`, [id]);
|
|
57
140
|
}
|
|
58
141
|
/**
|
|
59
|
-
* §7.4.3 reset
|
|
60
|
-
*
|
|
61
|
-
*
|
|
62
|
-
*
|
|
63
|
-
* subscriptions the app still wants. Caller owns the transaction.
|
|
142
|
+
* §7.4.3 reset, §2.1 log reset and local rebootstrap: keep the unit
|
|
143
|
+
* registrations (the app's declared intent) and discard every synced state,
|
|
144
|
+
* so the next round sends the list and fresh-bootstraps every unit. Caller
|
|
145
|
+
* owns the transaction.
|
|
64
146
|
*/
|
|
65
|
-
export function
|
|
66
|
-
db.exec(`UPDATE ${
|
|
147
|
+
export function resetUnits(db) {
|
|
148
|
+
db.exec(`UPDATE ${UNITS_TABLE} SET status='active',reason_code=NULL,cursor=-1,bootstrap_state=NULL,seeded='[]',echo=NULL`);
|
|
149
|
+
db.exec(`DELETE FROM ${META_TABLE} WHERE key IN(?,?,?)`, [
|
|
150
|
+
REPLICA_CURSOR_KEY,
|
|
151
|
+
ECHO_DIGEST_KEY,
|
|
152
|
+
REGISTERED_DIGEST_KEY,
|
|
153
|
+
]);
|
|
154
|
+
}
|
|
155
|
+
/** §4.5: the replica cursor, `-1` while no unit is live. */
|
|
156
|
+
export function replicaCursor(db) {
|
|
157
|
+
return Number(getMeta(db, REPLICA_CURSOR_KEY) ?? -1);
|
|
67
158
|
}
|
|
68
|
-
/**
|
|
69
|
-
export function
|
|
159
|
+
/** §7.4.3 declaration evidence, persisted beside the schema marker. */
|
|
160
|
+
export function saveUnitScopeSchema(db, schema) {
|
|
70
161
|
const declarations = {};
|
|
71
162
|
for (const table of schema.tables.values()) {
|
|
72
163
|
declarations[table.name] = Object.fromEntries([...table.scopeColumnByVariable].map(([variable, column]) => [
|
|
@@ -76,60 +167,58 @@ export function saveSubscriptionScopeSchema(db, schema) {
|
|
|
76
167
|
}
|
|
77
168
|
setMeta(db, 'subscriptionScopeSchema', JSON.stringify(declarations));
|
|
78
169
|
}
|
|
79
|
-
/**
|
|
80
|
-
|
|
170
|
+
/**
|
|
171
|
+
* Drop units that cover no table of the running schema, with their window
|
|
172
|
+
* registry rows and pending evictions; never translate scopes. At a bump
|
|
173
|
+
* (§7.4.3) a unit also needs every variable unchanged in prefix and column on
|
|
174
|
+
* every table it covered before.
|
|
175
|
+
*/
|
|
176
|
+
export function pruneUnknownUnits(db, schema, bump = false) {
|
|
81
177
|
const stored = bump ? getMeta(db, 'subscriptionScopeSchema') : undefined;
|
|
82
178
|
const previous = stored === undefined
|
|
83
179
|
? undefined
|
|
84
180
|
: JSON.parse(stored);
|
|
85
|
-
|
|
86
|
-
|
|
87
|
-
|
|
88
|
-
|
|
89
|
-
const
|
|
90
|
-
|
|
181
|
+
// A table keeps the variables' meaning when each has the same prefix and
|
|
182
|
+
// column as before. An old binary stored no declaration evidence; matching
|
|
183
|
+
// names cannot prove unchanged meaning, so the app registers again.
|
|
184
|
+
const unchanged = (name, variables) => {
|
|
185
|
+
const old = previous?.[name];
|
|
186
|
+
const table = schema.tables.get(name);
|
|
187
|
+
return (old !== undefined &&
|
|
188
|
+
table !== undefined &&
|
|
189
|
+
variables.every((variable) => old[variable]?.[0] === table.scopePrefixByVariable.get(variable) &&
|
|
190
|
+
old[variable]?.[1] === table.scopeColumnByVariable.get(variable)));
|
|
191
|
+
};
|
|
192
|
+
const compatible = (scopes) => {
|
|
193
|
+
const variables = Object.keys(scopes);
|
|
194
|
+
if (![...schema.tables.values()].some((table) => covers(table, scopes)))
|
|
91
195
|
return false;
|
|
92
196
|
if (!bump)
|
|
93
197
|
return true;
|
|
94
|
-
|
|
95
|
-
// at a bump: matching names cannot prove unchanged column/prefix meaning.
|
|
96
|
-
const old = previous?.[record.table];
|
|
97
|
-
if (old === undefined)
|
|
198
|
+
if (previous === undefined)
|
|
98
199
|
return false;
|
|
99
|
-
|
|
100
|
-
|
|
101
|
-
...new Set([
|
|
102
|
-
...Object.keys(old),
|
|
103
|
-
...table.scopeColumnByVariable.keys(),
|
|
104
|
-
]),
|
|
105
|
-
]
|
|
106
|
-
: variables;
|
|
107
|
-
return compared.every((variable) => old[variable]?.[0] === table.scopePrefixByVariable.get(variable) &&
|
|
108
|
-
old[variable]?.[1] === table.scopeColumnByVariable.get(variable));
|
|
200
|
+
return Object.entries(previous).every(([name, old]) => !variables.every((variable) => old[variable] !== undefined) ||
|
|
201
|
+
unchanged(name, variables));
|
|
109
202
|
};
|
|
110
|
-
const
|
|
111
|
-
|
|
112
|
-
.
|
|
113
|
-
|
|
114
|
-
//
|
|
115
|
-
//
|
|
116
|
-
|
|
117
|
-
|
|
118
|
-
|
|
119
|
-
|
|
120
|
-
|
|
121
|
-
|
|
203
|
+
const stale = new Set(loadUnits(db)
|
|
204
|
+
.filter((unit) => !compatible(unit.scopes))
|
|
205
|
+
.map((unit) => unit.id));
|
|
206
|
+
// A shrunk window's deferred eviction outlives its unit row and keeps its
|
|
207
|
+
// per-table scopes. A table the schema no longer has cannot be evicted, and
|
|
208
|
+
// at a bump a table whose scope declarations changed must not be evicted by
|
|
209
|
+
// the outdated rule.
|
|
210
|
+
for (const row of db.query(`SELECT unit_id,tbl,effective_scopes FROM ${PENDING_EVICTIONS}`)) {
|
|
211
|
+
const table = String(row.tbl);
|
|
212
|
+
if (!schema.tables.has(table) ||
|
|
213
|
+
(bump &&
|
|
214
|
+
!unchanged(table, Object.keys(JSON.parse(String(row.effective_scopes))))))
|
|
215
|
+
stale.add(String(row.unit_id));
|
|
216
|
+
}
|
|
217
|
+
for (const id of stale) {
|
|
218
|
+
db.exec(`DELETE FROM ${WINDOWS_TABLE} WHERE sub_id=?`, [id]);
|
|
219
|
+
db.exec(`DELETE FROM ${PENDING_EVICTIONS} WHERE unit_id=?`, [id]);
|
|
220
|
+
deleteUnit(db, id);
|
|
122
221
|
}
|
|
123
|
-
if (staleIds.size === 0)
|
|
124
|
-
return retained;
|
|
125
|
-
db.transaction(() => {
|
|
126
|
-
for (const id of staleIds) {
|
|
127
|
-
db.exec(`DELETE FROM ${WINDOWS_TABLE} WHERE sub_id=?`, [id]);
|
|
128
|
-
db.exec(`DELETE FROM ${PENDING_EVICTIONS} WHERE sub_id=?`, [id]);
|
|
129
|
-
db.exec(`DELETE FROM ${SUBSCRIPTIONS_TABLE} WHERE id=?`, [id]);
|
|
130
|
-
}
|
|
131
|
-
});
|
|
132
|
-
return retained;
|
|
133
222
|
}
|
|
134
223
|
export function getMeta(db, key) {
|
|
135
224
|
const row = db.query(`SELECT value FROM ${META_TABLE} WHERE key=?`, [key])[0];
|
package/dist/sync-scheduler.js
CHANGED
|
@@ -14,6 +14,8 @@ export function installSyncScheduler(client, options = {}) {
|
|
|
14
14
|
let backgroundReady = false;
|
|
15
15
|
let backgroundDue = Number.POSITIVE_INFINITY;
|
|
16
16
|
let cancelBackground;
|
|
17
|
+
// §7.7 backoff for drives that end without a client retry intent.
|
|
18
|
+
let retryDelayMs = 250;
|
|
17
19
|
const report = (error) => {
|
|
18
20
|
if (options.onError !== undefined) {
|
|
19
21
|
options.onError(error);
|
|
@@ -56,6 +58,7 @@ export function installSyncScheduler(client, options = {}) {
|
|
|
56
58
|
void client
|
|
57
59
|
.syncUntilIdle(options.maxRounds)
|
|
58
60
|
.then((result) => {
|
|
61
|
+
retryDelayMs = 250;
|
|
59
62
|
if (result !== null &&
|
|
60
63
|
typeof result === 'object' &&
|
|
61
64
|
'budgetExhausted' in result &&
|
|
@@ -64,8 +67,31 @@ export function installSyncScheduler(client, options = {}) {
|
|
|
64
67
|
}
|
|
65
68
|
})
|
|
66
69
|
.catch((error) => {
|
|
67
|
-
if (
|
|
68
|
-
|
|
70
|
+
if (stopped)
|
|
71
|
+
return;
|
|
72
|
+
report(error);
|
|
73
|
+
// §7.8: a retryable drive rejection owes another drive. A retryable
|
|
74
|
+
// round failure already handed this loop its background intent; the
|
|
75
|
+
// drive deadline did not. An unreachable endpoint waits for the
|
|
76
|
+
// host's connectivity resume (§1.8).
|
|
77
|
+
const details = error instanceof Error && 'details' in error
|
|
78
|
+
? error.details
|
|
79
|
+
: undefined;
|
|
80
|
+
const causeKind = typeof details === 'object' &&
|
|
81
|
+
details !== null &&
|
|
82
|
+
'causeKind' in details
|
|
83
|
+
? details.causeKind
|
|
84
|
+
: undefined;
|
|
85
|
+
if (error instanceof Error &&
|
|
86
|
+
'retryable' in error &&
|
|
87
|
+
error.retryable === true &&
|
|
88
|
+
causeKind !== 'network' &&
|
|
89
|
+
causeKind !== 'connect' &&
|
|
90
|
+
cancelBackground === undefined &&
|
|
91
|
+
!immediatePending) {
|
|
92
|
+
consume({ kind: 'background', delayMs: retryDelayMs });
|
|
93
|
+
retryDelayMs = Math.min(retryDelayMs * 2, 30_000);
|
|
94
|
+
}
|
|
69
95
|
})
|
|
70
96
|
.finally(() => {
|
|
71
97
|
running = false;
|
package/dist/transport.d.ts
CHANGED
|
@@ -4,8 +4,12 @@
|
|
|
4
4
|
* loopback implementations that call the server library directly — the
|
|
5
5
|
* loopback doctrine; HTTP/WebSocket bindings live in `./http`.
|
|
6
6
|
*/
|
|
7
|
-
/**
|
|
8
|
-
|
|
7
|
+
/**
|
|
8
|
+
* One combined push+pull round trip: SSP2 request bytes → response bytes.
|
|
9
|
+
* `signal` aborts when the `syncUntilIdle` deadline elapses (§7.8); a
|
|
10
|
+
* transport that honors it releases the round instead of holding it open.
|
|
11
|
+
*/
|
|
12
|
+
export type SyncTransport = (request: Uint8Array, signal?: AbortSignal) => Promise<Uint8Array>;
|
|
9
13
|
/** One registered authoritative query or command request. */
|
|
10
14
|
export type RemoteOperationTransport = (request: Uint8Array) => Promise<Uint8Array>;
|
|
11
15
|
export interface RemoteOperationRealtimeHandlers {
|
|
@@ -22,7 +26,14 @@ export interface SegmentFetchRequest {
|
|
|
22
26
|
readonly table: string;
|
|
23
27
|
/** Canonical JSON (§11.2) of the requested scope map (§5.5 header). */
|
|
24
28
|
readonly requestedScopesJson: string;
|
|
29
|
+
/**
|
|
30
|
+
* The descriptor's `byteLength` (§5.4): the downloader stops reading once
|
|
31
|
+
* the body exceeds it, and the client core rejects the result.
|
|
32
|
+
*/
|
|
33
|
+
readonly byteLength?: number;
|
|
25
34
|
readonly onProgress?: (bytesReceived: number) => void;
|
|
35
|
+
/** Aborts with the round when the `syncUntilIdle` deadline elapses (§7.8). */
|
|
36
|
+
readonly signal?: AbortSignal;
|
|
26
37
|
}
|
|
27
38
|
/**
|
|
28
39
|
* Fetch segment bytes from the direct endpoint (§5.5). `fetchUrl`, when
|
|
@@ -34,7 +45,9 @@ export interface SegmentFetchRequest {
|
|
|
34
45
|
*/
|
|
35
46
|
export interface SegmentDownloader {
|
|
36
47
|
(request: SegmentFetchRequest): Promise<Uint8Array>;
|
|
37
|
-
readonly fetchUrl?: (url: string, onProgress?: (bytesReceived: number) => void
|
|
48
|
+
readonly fetchUrl?: (url: string, onProgress?: (bytesReceived: number) => void, signal?: AbortSignal,
|
|
49
|
+
/** The descriptor's `byteLength`; reading stops once the body exceeds it. */
|
|
50
|
+
byteLength?: number) => Promise<Uint8Array>;
|
|
38
51
|
}
|
|
39
52
|
export interface RealtimeHandlers {
|
|
40
53
|
/** JSON control frame (§8.1): hello / sync / heartbeat / unknown. */
|
|
@@ -53,4 +66,6 @@ export interface RealtimeSocket {
|
|
|
53
66
|
sendBytes(bytes: Uint8Array): void;
|
|
54
67
|
close(): void;
|
|
55
68
|
}
|
|
56
|
-
export type RealtimeConnector = (handlers: RealtimeHandlers
|
|
69
|
+
export type RealtimeConnector = (handlers: RealtimeHandlers,
|
|
70
|
+
/** The client's id; the client passes it on every connect. */
|
|
71
|
+
clientId?: string) => Promise<RealtimeSocket> | RealtimeSocket;
|
package/dist/wasm-database.js
CHANGED
|
@@ -26,6 +26,9 @@ import { webLocksLeaderLock } from './leader-lock.js';
|
|
|
26
26
|
import sqlite3InitModule from '@sqlite.org/sqlite-wasm';
|
|
27
27
|
import { assertImageAlias, runTransaction, } from './database.js';
|
|
28
28
|
import { ClientSyncError, invalidRequest, STORAGE_BUSY_CODE, STORAGE_FENCED_CODE, STORAGE_UNAVAILABLE_CODE, } from './errors.js';
|
|
29
|
+
import { prepareReadOnly } from './query-guard.js';
|
|
30
|
+
/** Compiled statements one database keeps; a full cache is finalized and cleared. */
|
|
31
|
+
const STATEMENT_CACHE_LIMIT = 128;
|
|
29
32
|
function coerceParams(params) {
|
|
30
33
|
return params.map((value) => {
|
|
31
34
|
if (typeof value === 'boolean')
|
|
@@ -39,6 +42,7 @@ class WasmClientDatabase {
|
|
|
39
42
|
/** RFC 0005: present only for a persistent OPFS database. */
|
|
40
43
|
#sah;
|
|
41
44
|
#fence;
|
|
45
|
+
#statements = new Map();
|
|
42
46
|
#closed = false;
|
|
43
47
|
#tx = { depth: 0 };
|
|
44
48
|
constructor(db, sqlite3, sah, fence) {
|
|
@@ -55,7 +59,6 @@ class WasmClientDatabase {
|
|
|
55
59
|
fence.fenced = true;
|
|
56
60
|
for (const sibling of fence.siblings)
|
|
57
61
|
sibling.close();
|
|
58
|
-
fence.siblings.clear();
|
|
59
62
|
this.close();
|
|
60
63
|
});
|
|
61
64
|
}
|
|
@@ -65,24 +68,56 @@ class WasmClientDatabase {
|
|
|
65
68
|
}
|
|
66
69
|
}
|
|
67
70
|
exec(sql, params = []) {
|
|
68
|
-
this
|
|
69
|
-
this.#db.exec({
|
|
70
|
-
sql,
|
|
71
|
-
...(params.length > 0 ? { bind: coerceParams(params) } : {}),
|
|
72
|
-
rowMode: 'object',
|
|
73
|
-
resultRows: [],
|
|
74
|
-
});
|
|
71
|
+
this.query(sql, params);
|
|
75
72
|
}
|
|
73
|
+
/**
|
|
74
|
+
* Parameterized SQL (one statement per call, the `ClientDatabase` contract)
|
|
75
|
+
* runs through a compiled statement cached by its SQL text. SQL without
|
|
76
|
+
* parameters may hold several statements and compiles through `exec`.
|
|
77
|
+
*/
|
|
76
78
|
query(sql, params = []) {
|
|
77
79
|
this.#assertOwned();
|
|
78
|
-
|
|
79
|
-
|
|
80
|
-
sql,
|
|
81
|
-
|
|
82
|
-
|
|
83
|
-
|
|
80
|
+
if (params.length === 0) {
|
|
81
|
+
const resultRows = [];
|
|
82
|
+
this.#db.exec({ sql, rowMode: 'object', resultRows });
|
|
83
|
+
return resultRows;
|
|
84
|
+
}
|
|
85
|
+
let statement = this.#statements.get(sql);
|
|
86
|
+
if (statement === undefined) {
|
|
87
|
+
statement = this.#db.prepare(sql);
|
|
88
|
+
if (this.#statements.size === STATEMENT_CACHE_LIMIT) {
|
|
89
|
+
this.#statements.forEach((evicted) => evicted.finalize());
|
|
90
|
+
this.#statements.clear();
|
|
91
|
+
}
|
|
92
|
+
this.#statements.set(sql, statement);
|
|
93
|
+
}
|
|
94
|
+
const rows = [];
|
|
95
|
+
try {
|
|
96
|
+
statement.bind(coerceParams(params));
|
|
97
|
+
while (statement.step())
|
|
98
|
+
rows.push(statement.get({}));
|
|
99
|
+
}
|
|
100
|
+
finally {
|
|
101
|
+
statement.reset(true);
|
|
102
|
+
}
|
|
103
|
+
return rows;
|
|
104
|
+
}
|
|
105
|
+
queryReadOnly(sql, params = []) {
|
|
106
|
+
this.#assertOwned();
|
|
107
|
+
prepareReadOnly(sql, () => {
|
|
108
|
+
const statement = this.#db.prepare(sql);
|
|
109
|
+
try {
|
|
110
|
+
return [
|
|
111
|
+
undefined,
|
|
112
|
+
this.#sqlite3.capi.sqlite3_sql(statement.pointer),
|
|
113
|
+
statement.isReadOnly() && statement.columnCount > 0,
|
|
114
|
+
];
|
|
115
|
+
}
|
|
116
|
+
finally {
|
|
117
|
+
statement.finalize();
|
|
118
|
+
}
|
|
84
119
|
});
|
|
85
|
-
return
|
|
120
|
+
return this.query(sql, params);
|
|
86
121
|
}
|
|
87
122
|
transaction(fn) {
|
|
88
123
|
this.#assertOwned();
|
|
@@ -108,13 +143,11 @@ class WasmClientDatabase {
|
|
|
108
143
|
db.close();
|
|
109
144
|
throw error;
|
|
110
145
|
}
|
|
111
|
-
this.#fence
|
|
146
|
+
const database = new WasmClientDatabase(db, this.#sqlite3, undefined, this.#fence);
|
|
147
|
+
this.#fence?.siblings.add(database);
|
|
112
148
|
return {
|
|
113
|
-
database
|
|
114
|
-
close: () =>
|
|
115
|
-
this.#fence?.siblings.delete(db);
|
|
116
|
-
db.close();
|
|
117
|
-
},
|
|
149
|
+
database,
|
|
150
|
+
close: () => database.close(),
|
|
118
151
|
removeFile: () => {
|
|
119
152
|
sah.util.unlink(fileName);
|
|
120
153
|
},
|
|
@@ -158,6 +191,10 @@ class WasmClientDatabase {
|
|
|
158
191
|
close() {
|
|
159
192
|
if (this.#closed)
|
|
160
193
|
return;
|
|
194
|
+
this.#fence?.siblings.delete(this);
|
|
195
|
+
// oo1 DB.close() does not finalize prepared statements, and an open one
|
|
196
|
+
// keeps the database file open, so pauseVfs() below would throw.
|
|
197
|
+
this.#statements.forEach((statement) => statement.finalize());
|
|
161
198
|
this.#db.close();
|
|
162
199
|
// DB.close() leaves the SAH pool live. Close siblings first, then pause the
|
|
163
200
|
// VFS without deleting files, before releasing this worker's physical lock.
|
package/dist/window.d.ts
CHANGED
|
@@ -1,20 +1,18 @@
|
|
|
1
|
-
export declare const PENDING_EVICTIONS = "
|
|
1
|
+
export declare const PENDING_EVICTIONS = "_syncular_pending_evictions";
|
|
2
2
|
export declare const WINDOWS_TABLE = "_syncular_windows";
|
|
3
3
|
/**
|
|
4
|
-
*
|
|
4
|
+
* Windows (SPEC.md §4.8).
|
|
5
5
|
*
|
|
6
6
|
* A window is a partial local replica keyed by scope VALUES: the client
|
|
7
|
-
* holds
|
|
8
|
-
*
|
|
9
|
-
*
|
|
10
|
-
* mutation of one — so it needs zero wire or server changes.
|
|
7
|
+
* holds the units of a chosen set of values of a window BASE (one scope
|
|
8
|
+
* variable plus fixed values). Windowing is a set difference on §4.1 units,
|
|
9
|
+
* never a mutation of one, so it needs no wire or server change.
|
|
11
10
|
*
|
|
12
|
-
* This module owns the registry bookkeeping
|
|
13
|
-
*
|
|
14
|
-
*
|
|
15
|
-
* transaction and the invalidation choke point.
|
|
11
|
+
* This module owns the registry bookkeeping. The eviction that fuses with a
|
|
12
|
+
* shrink (E1–E4) lives on the client, which holds the DB transaction and the
|
|
13
|
+
* invalidation choke point.
|
|
16
14
|
*/
|
|
17
|
-
import { type ScopeMap } from '@syncular/core';
|
|
15
|
+
import { type ScopeMap, type UnitScopes } from '@syncular/core';
|
|
18
16
|
import type { ClientDatabase } from './database.js';
|
|
19
17
|
export type TimeBucketUnit = 'month';
|
|
20
18
|
/** Derive the immutable UTC scope value stored when a row is created. */
|
|
@@ -22,55 +20,35 @@ export declare function creationTimeBucket(createdAtMs: number, unit: TimeBucket
|
|
|
22
20
|
/** Return a rolling UTC month window ordered from oldest to newest. */
|
|
23
21
|
export declare function last(count: number, unit: TimeBucketUnit, nowMs?: number): string[];
|
|
24
22
|
/**
|
|
25
|
-
* A window base:
|
|
26
|
-
*
|
|
27
|
-
*
|
|
28
|
-
* subscription verbatim.
|
|
23
|
+
* A window base (§4.8): the selected scope variable plus the fixed scope
|
|
24
|
+
* values every unit of its family shares. A base names no table: each unit
|
|
25
|
+
* covers every table declaring its variables (§4.1).
|
|
29
26
|
*/
|
|
30
27
|
export interface WindowBase {
|
|
31
|
-
readonly table: string;
|
|
32
28
|
/** The scope variable whose values are the window units. */
|
|
33
29
|
readonly variable: string;
|
|
34
|
-
/**
|
|
35
|
-
readonly fixedScopes?:
|
|
36
|
-
readonly params?: string;
|
|
37
|
-
}
|
|
38
|
-
/** A live unit in the registry: its value and the subscription it drives. */
|
|
39
|
-
export interface WindowUnit {
|
|
40
|
-
readonly unit: string;
|
|
41
|
-
readonly subId: string;
|
|
30
|
+
/** One value per other variable, shared by every unit. */
|
|
31
|
+
readonly fixedScopes?: UnitScopes;
|
|
42
32
|
}
|
|
43
|
-
|
|
44
|
-
readonly baseKey: string;
|
|
45
|
-
}
|
|
46
|
-
/**
|
|
47
|
-
* A stable, server-opaque key for a window base — table + variable +
|
|
48
|
-
* canonical fixed scopes. Two `setWindow` calls with the same base
|
|
49
|
-
* address the same registry rows.
|
|
50
|
-
*/
|
|
33
|
+
/** A stable key for a window base: variable + canonical fixed scopes. */
|
|
51
34
|
export declare function windowBaseKey(base: WindowBase): string;
|
|
52
|
-
/** The
|
|
53
|
-
export declare function
|
|
54
|
-
/**
|
|
55
|
-
|
|
56
|
-
|
|
57
|
-
|
|
58
|
-
|
|
59
|
-
*/
|
|
60
|
-
export declare function
|
|
61
|
-
|
|
62
|
-
|
|
63
|
-
|
|
64
|
-
export declare function getWindowUnitBySubId(db: ClientDatabase, subId: string): RegisteredWindowUnit | undefined;
|
|
65
|
-
export declare function insertWindowUnit(db: ClientDatabase, baseKey: string, unit: string, subId: string): void;
|
|
66
|
-
export declare function deleteWindowUnit(db: ClientDatabase, baseKey: string, unit: string): void;
|
|
67
|
-
/** Is a single scope value windowed-in for this base? (the oracle, I3) */
|
|
68
|
-
export declare function isUnitLive(db: ClientDatabase, baseKey: string, unit: string): boolean;
|
|
35
|
+
/** The unit of one window value: the fixed scopes plus the value. */
|
|
36
|
+
export declare function windowUnitScopes(base: WindowBase, value: string): UnitScopes;
|
|
37
|
+
/** Registry rows for a base, ordered by value: value → unit id. */
|
|
38
|
+
export declare function loadWindowUnits(db: ClientDatabase, baseKey: string): {
|
|
39
|
+
readonly value: string;
|
|
40
|
+
readonly unitId: string;
|
|
41
|
+
}[];
|
|
42
|
+
/** Every window registry row that references a unit (§4.1 references). */
|
|
43
|
+
export declare function windowRefs(db: ClientDatabase, unitId: string): {
|
|
44
|
+
readonly baseKey: string;
|
|
45
|
+
readonly value: string;
|
|
46
|
+
}[];
|
|
69
47
|
export interface PendingEviction {
|
|
70
|
-
readonly
|
|
48
|
+
readonly unitId: string;
|
|
71
49
|
readonly table: string;
|
|
72
50
|
readonly effective: ScopeMap;
|
|
73
51
|
}
|
|
74
|
-
export declare function savePendingEviction(db: ClientDatabase,
|
|
75
|
-
export declare function deletePendingEviction(db: ClientDatabase,
|
|
52
|
+
export declare function savePendingEviction(db: ClientDatabase, entry: PendingEviction): void;
|
|
53
|
+
export declare function deletePendingEviction(db: ClientDatabase, unitId: string, table?: string): void;
|
|
76
54
|
export declare function loadPendingEvictions(db: ClientDatabase): PendingEviction[];
|