@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/src/errors.ts CHANGED
@@ -176,6 +176,14 @@ export const ERROR_CATALOG: Readonly<Record<string, ErrorCatalogEntry>> = {
176
176
  recommendedAction: 'retryLater',
177
177
  httpStatus: 500,
178
178
  },
179
+ // §6.3.2: below the outbox watermark with no retained result. A push
180
+ // operation-result error record only, never persisted.
181
+ 'sync.commit_expired': {
182
+ category: 'invalid-request',
183
+ retryable: false,
184
+ recommendedAction: 'resetClientId',
185
+ httpStatus: 400,
186
+ },
179
187
  // §2.4 on a non-D1 backend: the server refuses while a declared backfill
180
188
  // checkpoint is incomplete or the database is newer than the running build.
181
189
  // Formerly host-only; promoted to the §10.2 catalogue so an in-flight
@@ -212,6 +220,14 @@ export const ERROR_CATALOG: Readonly<Record<string, ErrorCatalogEntry>> = {
212
220
  recommendedAction: 'splitBatch',
213
221
  httpStatus: 400,
214
222
  },
223
+ // §1.7 / D3: a request or watch session past a configured `ServerLimits`
224
+ // cap; `details.limit` names the cap.
225
+ 'sync.limit_exceeded': {
226
+ category: 'invalid-request',
227
+ retryable: false,
228
+ recommendedAction: 'fixRequest',
229
+ httpStatus: 413,
230
+ },
215
231
  'sync.not_found': {
216
232
  category: 'not-found',
217
233
  retryable: false,
package/src/events.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
 
18
18
  /** One `POST /sync` request, emitted once per request after the response
19
19
  * bytes are fully produced (or the request was rejected up front). */
@@ -48,7 +48,8 @@ export interface RequestHandledEvent {
48
48
  readonly errorCode?: string;
49
49
  readonly pushCommits: number;
50
50
  readonly pulled: boolean;
51
- readonly subscriptions: number;
51
+ /** Units of the request's effective list (§4.1); 0 without one. */
52
+ readonly units: number;
52
53
  }
53
54
 
54
55
  interface PushEventBase {
@@ -154,7 +155,7 @@ export interface ReactionPruneCompletedEvent {
154
155
  readonly mayHaveMore: boolean;
155
156
  }
156
157
 
157
- /** One emitted segment within a pull subscription section. */
158
+ /** One emitted segment within a unit section. */
158
159
  export interface PullSegmentSummary {
159
160
  readonly mediaType: 'rows' | 'sqlite';
160
161
  readonly delivery: 'inline' | 'ref';
@@ -164,25 +165,40 @@ export interface PullSegmentSummary {
164
165
  readonly rows: number;
165
166
  }
166
167
 
167
- /** One subscription section of a served pull (§1.6). */
168
- export interface PullSubscriptionSummary {
168
+ /** One unit of a served pull's effective list (§4.1). */
169
+ export interface PullUnitSummary {
169
170
  readonly id: string;
170
- readonly table: string;
171
+ readonly scopes: UnitScopes;
171
172
  readonly status: 'active' | 'revoked' | 'reset';
172
- /** `none` for revoked/reset sections (no data half was produced). */
173
- readonly mode: 'bootstrap' | 'incremental' | 'none';
174
- readonly requestedScopes: ScopeMap;
175
- readonly effectiveScopes: ScopeMap;
176
- readonly firstCommitSeq?: number;
177
- readonly lastCommitSeq?: number;
173
+ /**
174
+ * `live` and `catching-up` (a post-bootstrap unit) units take part in the
175
+ * live section; `bootstrap` sections carry segments; `none` for revoked and
176
+ * reset units.
177
+ */
178
+ readonly mode: 'live' | 'catching-up' | 'bootstrap' | 'none';
179
+ /** Whether the response carried a unit section for it (§4.4). */
180
+ readonly section: boolean;
181
+ /** The unit's echo (§4.4). */
182
+ readonly fenced: readonly FencedRecord[];
183
+ /** The cursor the request held for the unit: its `PROGRESS` cursor or R. */
178
184
  readonly fromCursor: number;
179
- readonly nextCursor: number;
185
+ readonly segments: readonly PullSegmentSummary[];
186
+ }
187
+
188
+ /** The live section of a served pull (§4.5). */
189
+ export interface PullLiveSummary {
190
+ readonly status: 'active' | 'reset' | 'unregistered';
191
+ /** The request's replica cursor R. */
192
+ readonly fromCursor: number;
193
+ /** `LIVE_END.throughSeq`. */
194
+ readonly throughSeq: number;
180
195
  readonly commits: number;
181
196
  readonly changes: number;
182
- readonly segments: readonly PullSegmentSummary[];
197
+ readonly firstCommitSeq?: number;
198
+ readonly lastCommitSeq?: number;
183
199
  }
184
200
 
185
- /** The pull half of a request, emitted once after all sections streamed. */
201
+ /** The pull half of a request, emitted once after every section streamed. */
186
202
  export interface PullServedEvent {
187
203
  readonly type: 'pull.served';
188
204
  readonly atMs: number;
@@ -191,7 +207,10 @@ export interface PullServedEvent {
191
207
  readonly clientId: string;
192
208
  readonly acceptedThrough: number;
193
209
  readonly storageMaxCommitSeq: number;
194
- readonly subscriptions: readonly PullSubscriptionSummary[];
210
+ /** The request carried its registration list (§4.1). */
211
+ readonly registrationTraveled: boolean;
212
+ readonly units: readonly PullUnitSummary[];
213
+ readonly live: PullLiveSummary;
195
214
  }
196
215
 
197
216
  /** A direct segment download (§5.5), success or failure. */
@@ -238,7 +257,7 @@ export interface BlobSweptEvent {
238
257
  readonly partition: string;
239
258
  /** Blobs deleted this pass (unreferenced and older than the grace period). */
240
259
  readonly swept: number;
241
- /** Size of the live keep-set consulted (§5.9.4 reference index). */
260
+ /** Old candidates a live row still references (§5.9.4 reference index). */
242
261
  readonly referenced: number;
243
262
  /** The grace period applied (ms) — the upload→push race protection. */
244
263
  readonly graceMs: number;
@@ -292,7 +311,7 @@ export interface PruneCompletedEvent {
292
311
  }
293
312
 
294
313
  /** The host `resolveScopes` callback threw — the §3.2/§3.4 fail-loud
295
- * path (subscriptions revoke, writes reject, downloads deny). */
314
+ * path (units revoke, writes reject, downloads deny). */
296
315
  export interface ScopesResolveFailedEvent {
297
316
  readonly type: 'scopes.resolve_failed';
298
317
  readonly atMs: number;
@@ -9,10 +9,12 @@
9
9
  * bytes; the reference codec remains the single source of wire bytes.
10
10
  */
11
11
  import {
12
- encodeMessage,
12
+ encodeResponse,
13
13
  PROTOCOL_WIRE_VERSION,
14
14
  type PushResultFrame,
15
15
  type RespHeaderFrame,
16
+ type LiveEndFrame,
17
+ type LiveStartFrame,
16
18
  type ResponseFrame,
17
19
  type SubEndFrame,
18
20
  type SubStartFrame,
@@ -25,15 +27,25 @@ const stubHeader = (): RespHeaderFrame => ({
25
27
  });
26
28
  const STUB_SUB_START: SubStartFrame = {
27
29
  type: 'SUB_START',
28
- id: '',
30
+ id: '0'.repeat(32),
29
31
  status: 'active',
30
32
  reasonCode: '',
31
- effectiveScopes: {},
32
33
  bootstrap: false,
34
+ fenced: [],
33
35
  };
34
36
  const STUB_SUB_END: SubEndFrame = { type: 'SUB_END', nextCursor: 0 };
37
+ const STUB_LIVE_START: LiveStartFrame = {
38
+ type: 'LIVE_START',
39
+ status: 'active',
40
+ reasonCode: '',
41
+ };
42
+ const STUB_LIVE_END: LiveEndFrame = {
43
+ type: 'LIVE_END',
44
+ throughSeq: 0,
45
+ echoDigest: new Uint8Array(),
46
+ };
35
47
 
36
- const probe = encodeMessage({
48
+ const probe = encodeResponse({
37
49
  wireVersion: PROTOCOL_WIRE_VERSION,
38
50
  msgKind: 'response',
39
51
  frames: [stubHeader()],
@@ -41,7 +53,7 @@ const probe = encodeMessage({
41
53
 
42
54
  /** The 8-byte SSP2 response envelope header (§1.2). */
43
55
  export function responseEnvelopeHeader(wireVersion: number): Uint8Array {
44
- const encoded = encodeMessage({
56
+ const encoded = encodeResponse({
45
57
  wireVersion,
46
58
  msgKind: 'response',
47
59
  frames: [stubHeader()],
@@ -91,7 +103,15 @@ function wrapperFor(frame: ResponseFrame): {
91
103
  frames: [stubHeader(), STUB_SUB_START, frame],
92
104
  index: 2,
93
105
  };
106
+ case 'LIVE_START':
107
+ return { frames: [stubHeader(), frame, STUB_LIVE_END], index: 1 };
108
+ case 'LIVE_END':
109
+ return { frames: [stubHeader(), STUB_LIVE_START, frame], index: 2 };
94
110
  case 'COMMIT':
111
+ return {
112
+ frames: [stubHeader(), STUB_LIVE_START, frame, STUB_LIVE_END],
113
+ index: 2,
114
+ };
95
115
  case 'SEGMENT_REF':
96
116
  case 'SEGMENT_INLINE':
97
117
  return {
@@ -110,7 +130,7 @@ export function encodeResponseFrame(
110
130
  wireVersion = PROTOCOL_WIRE_VERSION,
111
131
  ): Uint8Array {
112
132
  const { frames, index } = wrapperFor(frame);
113
- const encoded = encodeMessage({
133
+ const encoded = encodeResponse({
114
134
  wireVersion,
115
135
  msgKind: 'response',
116
136
  frames,