@syncular/server 0.59.0 → 0.60.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (54) hide show
  1. package/README.md +20 -16
  2. package/dist/admin.d.ts +32 -20
  3. package/dist/admin.js +42 -40
  4. package/dist/context.d.ts +6 -8
  5. package/dist/context.js +1 -3
  6. package/dist/d1-storage.js +42 -24
  7. package/dist/errors.js +8 -0
  8. package/dist/events.d.ts +35 -17
  9. package/dist/frame-bytes.js +24 -6
  10. package/dist/handler.js +486 -223
  11. package/dist/local-authority.js +7 -9
  12. package/dist/operations.d.ts +5 -2
  13. package/dist/operations.js +20 -29
  14. package/dist/postgres-storage.d.ts +24 -19
  15. package/dist/postgres-storage.js +249 -168
  16. package/dist/pull.d.ts +68 -53
  17. package/dist/pull.js +258 -287
  18. package/dist/push.d.ts +12 -3
  19. package/dist/push.js +95 -32
  20. package/dist/realtime.d.ts +17 -11
  21. package/dist/realtime.js +65 -90
  22. package/dist/relational-rows.d.ts +0 -57
  23. package/dist/relational-rows.js +4 -100
  24. package/dist/seed.js +10 -15
  25. package/dist/segment-download.d.ts +4 -1
  26. package/dist/segment-download.js +4 -2
  27. package/dist/sqlite-dialect.d.ts +36 -59
  28. package/dist/sqlite-dialect.js +255 -159
  29. package/dist/sqlite-storage.js +24 -20
  30. package/dist/storage-query.d.ts +30 -1
  31. package/dist/storage-query.js +68 -0
  32. package/dist/storage.d.ts +156 -54
  33. package/dist/storage.js +15 -0
  34. package/package.json +2 -2
  35. package/src/admin.ts +87 -59
  36. package/src/context.ts +7 -11
  37. package/src/d1-storage.ts +49 -33
  38. package/src/errors.ts +8 -0
  39. package/src/events.ts +36 -17
  40. package/src/frame-bytes.ts +26 -6
  41. package/src/handler.ts +628 -286
  42. package/src/local-authority.ts +10 -11
  43. package/src/operations.ts +44 -42
  44. package/src/postgres-storage.ts +336 -226
  45. package/src/pull.ts +394 -414
  46. package/src/push.ts +116 -21
  47. package/src/realtime.ts +85 -129
  48. package/src/relational-rows.ts +4 -107
  49. package/src/seed.ts +13 -19
  50. package/src/segment-download.ts +8 -3
  51. package/src/sqlite-dialect.ts +363 -204
  52. package/src/sqlite-storage.ts +45 -25
  53. package/src/storage-query.ts +102 -0
  54. package/src/storage.ts +185 -58
package/dist/pull.d.ts CHANGED
@@ -1,11 +1,11 @@
1
1
  /**
2
- * Pull: incremental commit delivery, cursors, bootstrap segments
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 SubscriptionFrame } from '@syncular/core';
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 (the v1 values). */
22
+ /** §4.2 defaults and silent clamps. */
23
23
  export declare function clampPullLimits(header: PullHeaderFrame): PullLimits;
24
- export interface SubscriptionPlan {
25
- readonly frame: SubscriptionFrame;
26
- readonly table: CompiledTable;
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
- readonly effective: ScopeMap;
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
- * One subscription's section decision (§4.5–§4.7) with the storage reads it
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
- * The first snapshot page (`limitSnapshotRows + 1` rows from
64
- * `startCursor`), which is also the §5.3 image eligibility probe.
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
- /** §5.3 stored image under the reuse key, read only for an eligible probe. */
68
- readonly image: SegmentRecord | undefined;
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
- * Decide the section of every plan and run its pre-frame storage reads. The
72
- * reads of all plans start before any is awaited, so a storage that batches
73
- * concurrent page reads (PostgreSQL, D1) answers the first pages of every
74
- * plan in one statement per table, and the horizon re-check runs once.
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 prepareSections(ctx: SyncRequestContext, schema: CompiledSchema, limits: PullLimits, plans: readonly SubscriptionPlan[], maxSeq: number, horizonSeq: number, logEpoch: string): Promise<PreparedSection[]>;
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
- * Produce the `SUB_START … SUB_END` section for one subscription (§1.6),
79
- * returning the cursor recorded for the retention watermark (§4.5).
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 subscriptionSection(ctx: SyncRequestContext, schema: CompiledSchema, limits: PullLimits, plan: SubscriptionPlan, maxSeq: number, horizonSeq: number, trace?: PullSectionTrace, logEpoch?: string): AsyncGenerator<ResponseFrame, SubscriptionResult>;
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 effective scopes the subscribing clients hold for `table` (§3.2):
91
- * the reuse key carries their digest, so publish once per distinct scope
92
- * set that clients subscribe with.
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 scopes: ScopeMap;
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 for (`table`, `scopes`) looks
108
- * up, from a host with a SQLite engine (a Bun process with the production
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 {};