@syncular/server 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.
Files changed (103) hide show
  1. package/README.md +49 -36
  2. package/dist/admin.d.ts +32 -20
  3. package/dist/admin.js +46 -40
  4. package/dist/blob-handlers.d.ts +25 -31
  5. package/dist/blob-handlers.js +63 -41
  6. package/dist/blob-store.d.ts +42 -24
  7. package/dist/blob-store.js +0 -0
  8. package/dist/bucket-blob-store.d.ts +12 -8
  9. package/dist/bucket-blob-store.js +54 -45
  10. package/dist/bucket-segment-store.js +18 -16
  11. package/dist/content-encoding.d.ts +5 -2
  12. package/dist/content-encoding.js +42 -13
  13. package/dist/context.d.ts +19 -5
  14. package/dist/context.js +19 -1
  15. package/dist/d1-storage.d.ts +14 -98
  16. package/dist/d1-storage.js +249 -1119
  17. package/dist/errors.js +16 -0
  18. package/dist/events.d.ts +36 -18
  19. package/dist/frame-bytes.js +24 -6
  20. package/dist/handler.js +503 -208
  21. package/dist/local-authority.d.ts +2 -0
  22. package/dist/local-authority.js +24 -12
  23. package/dist/object-bucket.d.ts +2 -0
  24. package/dist/operations-realtime.js +69 -50
  25. package/dist/operations.d.ts +5 -2
  26. package/dist/operations.js +20 -29
  27. package/dist/pg-executor-pglite.d.ts +5 -6
  28. package/dist/pg-executor-pglite.js +22 -14
  29. package/dist/pg-executor.d.ts +4 -1
  30. package/dist/postgres-storage.d.ts +24 -19
  31. package/dist/postgres-storage.js +420 -262
  32. package/dist/pull.d.ts +70 -47
  33. package/dist/pull.js +270 -301
  34. package/dist/push.d.ts +12 -3
  35. package/dist/push.js +361 -173
  36. package/dist/realtime.d.ts +85 -39
  37. package/dist/realtime.js +355 -219
  38. package/dist/relational-rows.d.ts +21 -66
  39. package/dist/relational-rows.js +28 -109
  40. package/dist/s3-blob-store.d.ts +11 -12
  41. package/dist/s3-blob-store.js +20 -13
  42. package/dist/s3-object-bucket.d.ts +8 -1
  43. package/dist/s3-object-bucket.js +16 -3
  44. package/dist/schema.d.ts +14 -0
  45. package/dist/schema.js +23 -0
  46. package/dist/scopes.d.ts +6 -2
  47. package/dist/scopes.js +22 -4
  48. package/dist/seed.js +10 -16
  49. package/dist/segment-download.d.ts +4 -1
  50. package/dist/segment-download.js +22 -6
  51. package/dist/signed-url.d.ts +2 -2
  52. package/dist/signed-url.js +9 -2
  53. package/dist/sigv4.d.ts +8 -2
  54. package/dist/sigv4.js +8 -4
  55. package/dist/sqlite-blob-store.d.ts +1 -1
  56. package/dist/sqlite-blob-store.js +23 -22
  57. package/dist/sqlite-dialect.d.ts +164 -84
  58. package/dist/sqlite-dialect.js +1145 -150
  59. package/dist/sqlite-lease-store.js +13 -18
  60. package/dist/sqlite-storage.d.ts +9 -62
  61. package/dist/sqlite-storage.js +303 -1123
  62. package/dist/storage-query.d.ts +30 -1
  63. package/dist/storage-query.js +68 -0
  64. package/dist/storage.d.ts +185 -63
  65. package/dist/storage.js +15 -0
  66. package/package.json +2 -2
  67. package/src/admin.ts +99 -57
  68. package/src/blob-handlers.ts +91 -72
  69. package/src/blob-store.ts +0 -0
  70. package/src/bucket-blob-store.ts +75 -48
  71. package/src/bucket-segment-store.ts +20 -15
  72. package/src/content-encoding.ts +48 -16
  73. package/src/context.ts +33 -6
  74. package/src/d1-storage.ts +350 -1700
  75. package/src/errors.ts +16 -0
  76. package/src/events.ts +37 -18
  77. package/src/frame-bytes.ts +26 -6
  78. package/src/handler.ts +654 -261
  79. package/src/local-authority.ts +27 -14
  80. package/src/object-bucket.ts +2 -0
  81. package/src/operations-realtime.ts +85 -61
  82. package/src/operations.ts +44 -42
  83. package/src/pg-executor-pglite.ts +27 -23
  84. package/src/pg-executor.ts +5 -1
  85. package/src/postgres-storage.ts +557 -354
  86. package/src/pull.ts +406 -440
  87. package/src/push.ts +466 -220
  88. package/src/realtime.ts +447 -290
  89. package/src/relational-rows.ts +43 -121
  90. package/src/s3-blob-store.ts +23 -13
  91. package/src/s3-object-bucket.ts +20 -2
  92. package/src/schema.ts +31 -0
  93. package/src/scopes.ts +23 -3
  94. package/src/seed.ts +13 -20
  95. package/src/segment-download.ts +33 -7
  96. package/src/signed-url.ts +10 -4
  97. package/src/sigv4.ts +17 -4
  98. package/src/sqlite-blob-store.ts +27 -26
  99. package/src/sqlite-dialect.ts +1851 -199
  100. package/src/sqlite-lease-store.ts +12 -23
  101. package/src/sqlite-storage.ts +390 -1821
  102. package/src/storage-query.ts +102 -0
  103. package/src/storage.ts +215 -67
package/dist/errors.js CHANGED
@@ -168,6 +168,14 @@ export const ERROR_CATALOG = {
168
168
  recommendedAction: 'retryLater',
169
169
  httpStatus: 500,
170
170
  },
171
+ // §6.3.2: below the outbox watermark with no retained result. A push
172
+ // operation-result error record only, never persisted.
173
+ 'sync.commit_expired': {
174
+ category: 'invalid-request',
175
+ retryable: false,
176
+ recommendedAction: 'resetClientId',
177
+ httpStatus: 400,
178
+ },
171
179
  // §2.4 on a non-D1 backend: the server refuses while a declared backfill
172
180
  // checkpoint is incomplete or the database is newer than the running build.
173
181
  // Formerly host-only; promoted to the §10.2 catalogue so an in-flight
@@ -204,6 +212,14 @@ export const ERROR_CATALOG = {
204
212
  recommendedAction: 'splitBatch',
205
213
  httpStatus: 400,
206
214
  },
215
+ // §1.7 / D3: a request or watch session past a configured `ServerLimits`
216
+ // cap; `details.limit` names the cap.
217
+ 'sync.limit_exceeded': {
218
+ category: 'invalid-request',
219
+ retryable: false,
220
+ recommendedAction: 'fixRequest',
221
+ httpStatus: 413,
222
+ },
207
223
  'sync.not_found': {
208
224
  category: 'not-found',
209
225
  retryable: false,
package/dist/events.d.ts CHANGED
@@ -13,7 +13,7 @@
13
13
  * - Timestamps and durations come from the ctx clock where one exists, so
14
14
  * the conformance virtual-clock discipline stays intact.
15
15
  */
16
- import type { ScopeMap, WakeReason } from '@syncular/core';
16
+ import type { FencedRecord, UnitScopes, WakeReason } from '@syncular/core';
17
17
  /** One `POST /sync` request, emitted once per request after the response
18
18
  * bytes are fully produced (or the request was rejected up front). */
19
19
  export interface RequestHandledEvent {
@@ -41,7 +41,8 @@ export interface RequestHandledEvent {
41
41
  readonly errorCode?: string;
42
42
  readonly pushCommits: number;
43
43
  readonly pulled: boolean;
44
- readonly subscriptions: number;
44
+ /** Units of the request's effective list (§4.1); 0 without one. */
45
+ readonly units: number;
45
46
  }
46
47
  interface PushEventBase {
47
48
  readonly atMs: number;
@@ -135,7 +136,7 @@ export interface ReactionPruneCompletedEvent {
135
136
  readonly removedDeadLetter: number;
136
137
  readonly mayHaveMore: boolean;
137
138
  }
138
- /** One emitted segment within a pull subscription section. */
139
+ /** One emitted segment within a unit section. */
139
140
  export interface PullSegmentSummary {
140
141
  readonly mediaType: 'rows' | 'sqlite';
141
142
  readonly delivery: 'inline' | 'ref';
@@ -144,24 +145,38 @@ export interface PullSegmentSummary {
144
145
  readonly bytes: number;
145
146
  readonly rows: number;
146
147
  }
147
- /** One subscription section of a served pull (§1.6). */
148
- export interface PullSubscriptionSummary {
148
+ /** One unit of a served pull's effective list (§4.1). */
149
+ export interface PullUnitSummary {
149
150
  readonly id: string;
150
- readonly table: string;
151
+ readonly scopes: UnitScopes;
151
152
  readonly status: 'active' | 'revoked' | 'reset';
152
- /** `none` for revoked/reset sections (no data half was produced). */
153
- readonly mode: 'bootstrap' | 'incremental' | 'none';
154
- readonly requestedScopes: ScopeMap;
155
- readonly effectiveScopes: ScopeMap;
156
- readonly firstCommitSeq?: number;
157
- readonly lastCommitSeq?: number;
153
+ /**
154
+ * `live` and `catching-up` (a post-bootstrap unit) units take part in the
155
+ * live section; `bootstrap` sections carry segments; `none` for revoked and
156
+ * reset units.
157
+ */
158
+ readonly mode: 'live' | 'catching-up' | 'bootstrap' | 'none';
159
+ /** Whether the response carried a unit section for it (§4.4). */
160
+ readonly section: boolean;
161
+ /** The unit's echo (§4.4). */
162
+ readonly fenced: readonly FencedRecord[];
163
+ /** The cursor the request held for the unit: its `PROGRESS` cursor or R. */
164
+ readonly fromCursor: number;
165
+ readonly segments: readonly PullSegmentSummary[];
166
+ }
167
+ /** The live section of a served pull (§4.5). */
168
+ export interface PullLiveSummary {
169
+ readonly status: 'active' | 'reset' | 'unregistered';
170
+ /** The request's replica cursor R. */
158
171
  readonly fromCursor: number;
159
- readonly nextCursor: number;
172
+ /** `LIVE_END.throughSeq`. */
173
+ readonly throughSeq: number;
160
174
  readonly commits: number;
161
175
  readonly changes: number;
162
- readonly segments: readonly PullSegmentSummary[];
176
+ readonly firstCommitSeq?: number;
177
+ readonly lastCommitSeq?: number;
163
178
  }
164
- /** The pull half of a request, emitted once after all sections streamed. */
179
+ /** The pull half of a request, emitted once after every section streamed. */
165
180
  export interface PullServedEvent {
166
181
  readonly type: 'pull.served';
167
182
  readonly atMs: number;
@@ -170,7 +185,10 @@ export interface PullServedEvent {
170
185
  readonly clientId: string;
171
186
  readonly acceptedThrough: number;
172
187
  readonly storageMaxCommitSeq: number;
173
- readonly subscriptions: readonly PullSubscriptionSummary[];
188
+ /** The request carried its registration list (§4.1). */
189
+ readonly registrationTraveled: boolean;
190
+ readonly units: readonly PullUnitSummary[];
191
+ readonly live: PullLiveSummary;
174
192
  }
175
193
  /** A direct segment download (§5.5), success or failure. */
176
194
  export interface SegmentDownloadedEvent {
@@ -213,7 +231,7 @@ export interface BlobSweptEvent {
213
231
  readonly partition: string;
214
232
  /** Blobs deleted this pass (unreferenced and older than the grace period). */
215
233
  readonly swept: number;
216
- /** Size of the live keep-set consulted (§5.9.4 reference index). */
234
+ /** Old candidates a live row still references (§5.9.4 reference index). */
217
235
  readonly referenced: number;
218
236
  /** The grace period applied (ms) — the upload→push race protection. */
219
237
  readonly graceMs: number;
@@ -260,7 +278,7 @@ export interface PruneCompletedEvent {
260
278
  readonly removedCommits: number;
261
279
  }
262
280
  /** The host `resolveScopes` callback threw — the §3.2/§3.4 fail-loud
263
- * path (subscriptions revoke, writes reject, downloads deny). */
281
+ * path (units revoke, writes reject, downloads deny). */
264
282
  export interface ScopesResolveFailedEvent {
265
283
  readonly type: 'scopes.resolve_failed';
266
284
  readonly atMs: number;
@@ -8,7 +8,7 @@
8
8
  * are sliced back out by walking the frame headers. Wrapper stubs are a few
9
9
  * bytes; the reference codec remains the single source of wire bytes.
10
10
  */
11
- import { encodeMessage, PROTOCOL_WIRE_VERSION, } from '@syncular/core';
11
+ import { encodeResponse, PROTOCOL_WIRE_VERSION, } from '@syncular/core';
12
12
  const stubHeader = () => ({
13
13
  type: 'RESP_HEADER',
14
14
  logEpoch: 'frame-probe',
@@ -16,21 +16,31 @@ const stubHeader = () => ({
16
16
  });
17
17
  const STUB_SUB_START = {
18
18
  type: 'SUB_START',
19
- id: '',
19
+ id: '0'.repeat(32),
20
20
  status: 'active',
21
21
  reasonCode: '',
22
- effectiveScopes: {},
23
22
  bootstrap: false,
23
+ fenced: [],
24
24
  };
25
25
  const STUB_SUB_END = { type: 'SUB_END', nextCursor: 0 };
26
- const probe = encodeMessage({
26
+ const STUB_LIVE_START = {
27
+ type: 'LIVE_START',
28
+ status: 'active',
29
+ reasonCode: '',
30
+ };
31
+ const STUB_LIVE_END = {
32
+ type: 'LIVE_END',
33
+ throughSeq: 0,
34
+ echoDigest: new Uint8Array(),
35
+ };
36
+ const probe = encodeResponse({
27
37
  wireVersion: PROTOCOL_WIRE_VERSION,
28
38
  msgKind: 'response',
29
39
  frames: [stubHeader()],
30
40
  });
31
41
  /** The 8-byte SSP2 response envelope header (§1.2). */
32
42
  export function responseEnvelopeHeader(wireVersion) {
33
- const encoded = encodeMessage({
43
+ const encoded = encodeResponse({
34
44
  wireVersion,
35
45
  msgKind: 'response',
36
46
  frames: [stubHeader()],
@@ -75,7 +85,15 @@ function wrapperFor(frame) {
75
85
  frames: [stubHeader(), STUB_SUB_START, frame],
76
86
  index: 2,
77
87
  };
88
+ case 'LIVE_START':
89
+ return { frames: [stubHeader(), frame, STUB_LIVE_END], index: 1 };
90
+ case 'LIVE_END':
91
+ return { frames: [stubHeader(), STUB_LIVE_START, frame], index: 2 };
78
92
  case 'COMMIT':
93
+ return {
94
+ frames: [stubHeader(), STUB_LIVE_START, frame, STUB_LIVE_END],
95
+ index: 2,
96
+ };
79
97
  case 'SEGMENT_REF':
80
98
  case 'SEGMENT_INLINE':
81
99
  return {
@@ -90,7 +108,7 @@ function wrapperFor(frame) {
90
108
  */
91
109
  export function encodeResponseFrame(frame, wireVersion = PROTOCOL_WIRE_VERSION) {
92
110
  const { frames, index } = wrapperFor(frame);
93
- const encoded = encodeMessage({
111
+ const encoded = encodeResponse({
94
112
  wireVersion,
95
113
  msgKind: 'response',
96
114
  frames,