@syncular/server 0.59.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 +20 -16
- package/dist/admin.d.ts +32 -20
- package/dist/admin.js +42 -40
- package/dist/context.d.ts +6 -8
- package/dist/context.js +1 -3
- package/dist/d1-storage.js +42 -24
- package/dist/errors.js +8 -0
- package/dist/events.d.ts +35 -17
- package/dist/frame-bytes.js +24 -6
- package/dist/handler.js +486 -223
- package/dist/local-authority.js +7 -9
- package/dist/operations.d.ts +5 -2
- package/dist/operations.js +20 -29
- package/dist/postgres-storage.d.ts +24 -19
- package/dist/postgres-storage.js +249 -168
- package/dist/pull.d.ts +68 -53
- package/dist/pull.js +258 -287
- package/dist/push.d.ts +12 -3
- package/dist/push.js +95 -32
- package/dist/realtime.d.ts +17 -11
- package/dist/realtime.js +65 -90
- package/dist/relational-rows.d.ts +0 -57
- package/dist/relational-rows.js +0 -97
- package/dist/seed.js +10 -15
- package/dist/segment-download.d.ts +4 -1
- package/dist/segment-download.js +4 -2
- package/dist/sqlite-dialect.d.ts +36 -59
- package/dist/sqlite-dialect.js +255 -159
- package/dist/sqlite-storage.js +24 -20
- package/dist/storage-query.d.ts +30 -1
- package/dist/storage-query.js +68 -0
- package/dist/storage.d.ts +156 -54
- package/dist/storage.js +15 -0
- package/package.json +2 -2
- package/src/admin.ts +87 -59
- package/src/context.ts +7 -11
- package/src/d1-storage.ts +49 -33
- package/src/errors.ts +8 -0
- package/src/events.ts +36 -17
- package/src/frame-bytes.ts +26 -6
- package/src/handler.ts +628 -286
- package/src/local-authority.ts +10 -11
- package/src/operations.ts +44 -42
- package/src/postgres-storage.ts +336 -226
- package/src/pull.ts +394 -414
- package/src/push.ts +116 -21
- package/src/realtime.ts +85 -129
- package/src/relational-rows.ts +0 -105
- package/src/seed.ts +13 -19
- package/src/segment-download.ts +8 -3
- package/src/sqlite-dialect.ts +363 -204
- package/src/sqlite-storage.ts +45 -25
- package/src/storage-query.ts +102 -0
- package/src/storage.ts +185 -58
package/dist/pull.d.ts
CHANGED
|
@@ -1,11 +1,11 @@
|
|
|
1
1
|
/**
|
|
2
|
-
* Pull:
|
|
3
|
-
* (SPEC.md §4, §5).
|
|
2
|
+
* Pull: units, the live section, bootstrap segments (SPEC.md §4, §5).
|
|
4
3
|
*/
|
|
5
|
-
import { type PullHeaderFrame, type ResponseFrame, type ScopeMap, type
|
|
4
|
+
import { type CommitFrame, type FencedRecord, type PullHeaderFrame, type ResponseFrame, type ScopeMap, type UnitScopes } from '@syncular/core';
|
|
6
5
|
import type { SyncRequestContext, SyncServerConfig } from './context.js';
|
|
7
6
|
import type { PullSegmentSummary } from './events.js';
|
|
8
7
|
import { type CompiledSchema, type CompiledTable } from './schema.js';
|
|
8
|
+
import { type ResolvedScopes } from './scopes.js';
|
|
9
9
|
import type { SegmentRecord } from './segment-store.js';
|
|
10
10
|
import type { StoredCommit, StoredRow } from './storage.js';
|
|
11
11
|
/** §4.2 accept bitmask. */
|
|
@@ -19,18 +19,33 @@ export interface PullLimits {
|
|
|
19
19
|
readonly maxSnapshotPages: number;
|
|
20
20
|
readonly accept: number;
|
|
21
21
|
}
|
|
22
|
-
/** §4.2 defaults and silent clamps
|
|
22
|
+
/** §4.2 defaults and silent clamps. */
|
|
23
23
|
export declare function clampPullLimits(header: PullHeaderFrame): PullLimits;
|
|
24
|
-
|
|
25
|
-
|
|
26
|
-
readonly
|
|
24
|
+
/** One unit of the effective list, resolved against the request (§3.2, §4.1). */
|
|
25
|
+
export interface UnitPlan {
|
|
26
|
+
readonly id: string;
|
|
27
|
+
readonly scopes: UnitScopes;
|
|
28
|
+
/** Covered tables in bootstrap order (§4.1, §4.7). */
|
|
29
|
+
readonly tables: readonly CompiledTable[];
|
|
30
|
+
/** Active (unit, table) pairs: table → effective scopes (§3.2). */
|
|
31
|
+
readonly pairs: ReadonlyMap<string, ScopeMap>;
|
|
27
32
|
readonly status: 'active' | 'revoked';
|
|
28
|
-
|
|
29
|
-
|
|
30
|
-
export interface SubscriptionResult {
|
|
31
|
-
readonly nextCursor: number;
|
|
32
|
-
readonly active: boolean;
|
|
33
|
+
/** The echo (§4.4): ascending table order, empty when revoked. */
|
|
34
|
+
readonly fenced: readonly FencedRecord[];
|
|
33
35
|
}
|
|
36
|
+
/**
|
|
37
|
+
* §4.1 unit validation against one schema version: the covered tables, or
|
|
38
|
+
* `sync.invalid_subscription` for an empty scope map, a requested `'*'`, a
|
|
39
|
+
* variable no table declares, or no covered table.
|
|
40
|
+
*/
|
|
41
|
+
export declare function coveredTables(schema: CompiledSchema, scopes: UnitScopes): CompiledTable[];
|
|
42
|
+
/** §3.2 per covered table: the unit's active pairs, status and echo. */
|
|
43
|
+
export declare function planUnit(scopes: UnitScopes, tables: readonly CompiledTable[], resolved: ResolvedScopes): UnitPlan;
|
|
44
|
+
/**
|
|
45
|
+
* The `COMMIT` frame of one live-section commit (§4.5): its frame-local
|
|
46
|
+
* table dictionary and every change, projected onto the client's codec.
|
|
47
|
+
*/
|
|
48
|
+
export declare function commitFrame(commit: StoredCommit, current: CompiledSchema, target: CompiledSchema): CommitFrame;
|
|
34
49
|
/**
|
|
35
50
|
* Mutable per-section collector for the `pull.served` event. Only created
|
|
36
51
|
* when an events sink is configured — with `trace` undefined the pull path
|
|
@@ -39,59 +54,58 @@ export interface SubscriptionResult {
|
|
|
39
54
|
export interface PullSectionTrace {
|
|
40
55
|
readonly segments: PullSegmentSummary[];
|
|
41
56
|
}
|
|
42
|
-
/**
|
|
43
|
-
|
|
44
|
-
* needs before its first frame.
|
|
45
|
-
*/
|
|
46
|
-
export type PreparedSection = {
|
|
47
|
-
readonly kind: 'revoked';
|
|
48
|
-
}
|
|
49
|
-
/** §4.6: the cursor is behind the horizon. */
|
|
50
|
-
| {
|
|
51
|
-
readonly kind: 'reset';
|
|
52
|
-
}
|
|
53
|
-
/** §4.5 window read for an in-range cursor. */
|
|
54
|
-
| {
|
|
55
|
-
readonly kind: 'incremental';
|
|
56
|
-
readonly commits: StoredCommit[];
|
|
57
|
-
} | {
|
|
58
|
-
readonly kind: 'bootstrap';
|
|
59
|
-
/** §4.7 pin: a usable resume token's, the sqlite lane's scope pin, or `maxCommitSeq`. */
|
|
60
|
-
readonly asOf: number;
|
|
61
|
-
readonly startCursor: string | null;
|
|
57
|
+
/** The reads a table's bootstrap needs before its first frame (§4.7, §5.3). */
|
|
58
|
+
interface TableStart {
|
|
62
59
|
/**
|
|
63
|
-
*
|
|
64
|
-
*
|
|
60
|
+
* `limitSnapshotRows + 1` rows from the start cursor: the first page and
|
|
61
|
+
* the §5.3 image eligibility probe.
|
|
65
62
|
*/
|
|
66
63
|
readonly firstPage: StoredRow[];
|
|
67
|
-
/**
|
|
68
|
-
readonly image
|
|
69
|
-
|
|
64
|
+
/** On the sqlite lane: the §4.7 scope pin and a stored image under it. */
|
|
65
|
+
readonly image?: {
|
|
66
|
+
readonly scopePin: number;
|
|
67
|
+
readonly stored: SegmentRecord | undefined;
|
|
68
|
+
};
|
|
69
|
+
}
|
|
70
|
+
/** A bootstrapping unit's position and its table starts, read ahead (§4.7). */
|
|
71
|
+
export interface BootstrapPlan {
|
|
72
|
+
readonly unit: UnitPlan;
|
|
73
|
+
/** The unit's pin: a usable resume token's, or `maxCommitSeq`. */
|
|
74
|
+
readonly pin: number;
|
|
75
|
+
readonly tableIndex: number;
|
|
76
|
+
readonly rowCursor: string | null;
|
|
77
|
+
/** Table index → its start reads. */
|
|
78
|
+
readonly starts: ReadonlyMap<number, Promise<TableStart>>;
|
|
79
|
+
}
|
|
70
80
|
/**
|
|
71
|
-
*
|
|
72
|
-
*
|
|
73
|
-
*
|
|
74
|
-
*
|
|
81
|
+
* Plan one unit's bootstrap and start the reads of every table it can reach
|
|
82
|
+
* in this section: each visited table costs at least one page, so at most
|
|
83
|
+
* `maxSnapshotPages` tables. The reads of every planned unit start before any
|
|
84
|
+
* is awaited, so a storage that batches concurrent page reads (PostgreSQL,
|
|
85
|
+
* D1) answers them in one statement per table.
|
|
75
86
|
*/
|
|
76
|
-
export declare function
|
|
87
|
+
export declare function planBootstrap(ctx: SyncRequestContext, schema: CompiledSchema, limits: PullLimits, unit: UnitPlan, bootstrapState: string | undefined, maxSeq: number, horizonSeq: number, logEpoch: string): BootstrapPlan;
|
|
77
88
|
/**
|
|
78
|
-
*
|
|
79
|
-
*
|
|
89
|
+
* The segments of one bootstrap section (§4.7): tables in bootstrap order,
|
|
90
|
+
* each active pair's rows or image, up to `maxSnapshotPages` pages. Returns
|
|
91
|
+
* the resume token, or `undefined` once every table is exhausted. A pair the
|
|
92
|
+
* wildcard fence revoked receives no segment (§3.3).
|
|
80
93
|
*/
|
|
81
|
-
export declare function
|
|
82
|
-
/** The section of one subscription whose reads `prepareSections` ran. */
|
|
83
|
-
export declare function preparedSection(ctx: SyncRequestContext, schema: CompiledSchema, limits: PullLimits, plan: SubscriptionPlan, maxSeq: number, prepared: PreparedSection, trace?: PullSectionTrace, logEpoch?: string): AsyncGenerator<ResponseFrame, SubscriptionResult>;
|
|
94
|
+
export declare function bootstrapSegments(ctx: SyncRequestContext, schema: CompiledSchema, limits: PullLimits, plan: BootstrapPlan, trace: PullSectionTrace | undefined, logEpoch: string): AsyncGenerator<ResponseFrame, string | undefined>;
|
|
84
95
|
export interface PublishSqliteImageInput {
|
|
85
96
|
/** The sync config the serving host runs, plus a `sqliteImageBuilder`. */
|
|
86
97
|
readonly config: SyncServerConfig;
|
|
87
98
|
readonly partition: string;
|
|
88
99
|
readonly table: string;
|
|
100
|
+
/** The unit whose clients bootstrap the table (§4.1). */
|
|
101
|
+
readonly scopes: UnitScopes;
|
|
89
102
|
/**
|
|
90
|
-
* The
|
|
91
|
-
*
|
|
92
|
-
*
|
|
103
|
+
* The allowed scopes of the actors that register the unit (§3.2). The
|
|
104
|
+
* reuse key carries the digest of the pair's effective scopes, so a
|
|
105
|
+
* wildcard fence on the table changes the image. Default: `'*'` for every
|
|
106
|
+
* declared variable, which leaves the unit's own scope map.
|
|
93
107
|
*/
|
|
94
|
-
readonly
|
|
108
|
+
readonly allowed?: ScopeMap;
|
|
95
109
|
}
|
|
96
110
|
export interface PublishedSqliteImage {
|
|
97
111
|
readonly segmentId: string;
|
|
@@ -104,8 +118,8 @@ export interface PublishedSqliteImage {
|
|
|
104
118
|
readonly origin: 'built' | 'reused';
|
|
105
119
|
}
|
|
106
120
|
/**
|
|
107
|
-
* Publish the §5.3 sqlite image that a pull
|
|
108
|
-
*
|
|
121
|
+
* Publish the §5.3 sqlite image that a pull of (`scopes`, `table`) looks up,
|
|
122
|
+
* from a host with a SQLite engine (a Bun process with the production
|
|
109
123
|
* storage). It runs the pull's own bootstrap path (the §4.7 scope pin, the
|
|
110
124
|
* reuse key, the build), so the stored identity is exactly the one a
|
|
111
125
|
* serving host without a builder finds. The image stays current until a
|
|
@@ -113,3 +127,4 @@ export interface PublishedSqliteImage {
|
|
|
113
127
|
* publication.
|
|
114
128
|
*/
|
|
115
129
|
export declare function publishSqliteImage(input: PublishSqliteImageInput): Promise<PublishedSqliteImage>;
|
|
130
|
+
export {};
|