@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
@@ -7,8 +7,8 @@
7
7
  * queues the ack's cursor write without awaiting it, so `drain()` is the
8
8
  * awaitable boundary a host uses before closing its storage or ending a
9
9
  * hibernatable event (§8.2). Initial
10
- * subscription registration comes from the client's most recent pull
11
- * (§8.1, loaded from the client record); a sync round completed on the
10
+ * registration comes from the live units of the client record (§8.1); a sync
11
+ * round completed on the
12
12
  * connection replaces it at round end (§8.7). Deltas are complete SSP2
13
13
  * response messages pushed as `0x00`-tagged binary (§8.2/§8.7); sync
14
14
  * rounds ride the same socket as `0x01`-tagged byte-stream chunks driven
@@ -17,11 +17,11 @@
17
17
  * the `sync` wake-up (§8.3).
18
18
  */
19
19
  import { type PresenceKind, type ScopeMap, type WakeReason } from '@syncular/core';
20
- import type { SyncRequestContext, SyncServerConfig } from './context.js';
20
+ import type { ServerLimits, SyncRequestContext, SyncServerConfig } from './context.js';
21
21
  import { type SyncularErrorHandler, type SyncularErrorMapper } from './errors.js';
22
22
  import { type SyncularServerEvents } from './events.js';
23
- import { type CompiledTable } from './schema.js';
24
- import type { ServerStorage, StoredCommit } from './storage.js';
23
+ import { type CompiledSchema } from './schema.js';
24
+ import type { ClientRecord, ServerStorage, StoredCommit } from './storage.js';
25
25
  /**
26
26
  * Realtime adds fanout/presence tuning to the canonical sync-server config;
27
27
  * socket rounds must never have a narrower push/pull capability set than HTTP.
@@ -30,9 +30,19 @@ export interface RealtimeHubConfig extends Omit<SyncServerConfig, 'realtime'> {
30
30
  /** Deltas larger than this become `delta-too-large` wake-ups (§8.2). */
31
31
  readonly maxDeltaBytes?: number;
32
32
  /**
33
- * §8.6 presence: cap on the serialized size (bytes) of a published
34
- * presence document. An over-cap publish is rejected loudly to the
35
- * publisher with `presence.too_large` and fans out nothing. Default 16 KiB.
33
+ * §8.2 flow control: sent deltas a session may leave unacknowledged before
34
+ * the server stops sending it deltas and answers with a `catchup-required`
35
+ * wake-up. Default 256.
36
+ */
37
+ readonly maxUnackedDeltas?: number;
38
+ /** §8.2 flow control: bytes of unacknowledged deltas per session. Default
39
+ * 4 MiB. */
40
+ readonly maxUnackedDeltaBytes?: number;
41
+ /**
42
+ * §8.6.2 presence cap per connection: the UTF-8 bytes of each held scope
43
+ * key plus its serialized document, summed over the connection's keys. A
44
+ * publish that would exceed it is answered with `presence.too_large` and
45
+ * changes nothing. Default 8,192.
36
46
  */
37
47
  readonly maxPresenceBytes?: number;
38
48
  /**
@@ -61,9 +71,19 @@ export interface RealtimeConnectOptions {
61
71
  * `session.close()` from its socket-close handler as usual.
62
72
  */
63
73
  readonly closeSocket?: () => void;
74
+ /**
75
+ * §8.6.1: called after every change to this connection's own presence
76
+ * documents with all of them, scope key → serialized document, so a host
77
+ * whose memory can be evicted keeps them with the connection and hands
78
+ * them back to `restore`. Not called once the connection closed.
79
+ */
80
+ readonly onPresence?: (presence: ReadonlyMap<string, string>) => void;
64
81
  }
82
+ /** One active (unit, table) pair of a live unit (§8.1). */
65
83
  interface Registration {
66
- readonly codec: CompiledTable;
84
+ /** The schema version of the client's latest round: the delta codec (§9). */
85
+ readonly schema: CompiledSchema;
86
+ /** The unit id (§4.1). */
67
87
  readonly id: string;
68
88
  readonly table: string;
69
89
  readonly schemaVersion: number;
@@ -71,30 +91,15 @@ interface Registration {
71
91
  }
72
92
  type PresenceDoc = Record<string, unknown>;
73
93
  /**
74
- * §8.6 presence registry — pure in-memory ephemeral state, keyed per
75
- * `(partition, scopeKey)` → the set of present sessions and their
76
- * documents. It never touches `ServerStorage`; a server restart loses all
77
- * presence (§8.6.1). Fanout is scoped to registered peers only — the
78
- * privacy floor (§8.6.3).
94
+ * §8.6 presence index: per `(partition, scopeKey)`, the sessions holding a
95
+ * document there. The documents live with their session (§8.6.1). Pure
96
+ * in-memory state that never touches `ServerStorage`.
79
97
  */
80
98
  declare class PresenceRegistry {
81
99
  #private;
82
- /** Current documents on a key, excluding one session (the snapshot,
83
- * §8.6.4). */
84
- snapshot(partition: string, scopeKey: string, exclude: RealtimeSession): Array<{
85
- session: RealtimeSession;
86
- doc: PresenceDoc;
87
- }>;
88
- /** Store/replace a session's document for a key. Returns whether this is
89
- * the session's FIRST document on the key (join) or a replacement
90
- * (update). */
91
- set(partition: string, scopeKey: string, session: RealtimeSession, doc: PresenceDoc): 'join' | 'update';
92
- /** Remove a session's document for a key. Returns true if one existed. */
93
- clear(partition: string, scopeKey: string, session: RealtimeSession): boolean;
94
- /** Every key a session currently holds a document on (for leave-on-drop
95
- * and registration-change re-derivation). */
96
- keysOf(partition: string, session: RealtimeSession): string[];
97
- /** Sessions currently registered as peers on a key (for fanout). */
100
+ add(partition: string, scopeKey: string, session: RealtimeSession): void;
101
+ delete(partition: string, scopeKey: string, session: RealtimeSession): void;
102
+ /** Sessions holding a document on a key. */
98
103
  peers(partition: string, scopeKey: string): RealtimeSession[];
99
104
  }
100
105
  export declare class RealtimeSession {
@@ -113,6 +118,8 @@ export declare class RealtimeSession {
113
118
  lastKnownSeq: number;
114
119
  /** Replaced at socket-round completion (§8.7); initial set from §8.1. */
115
120
  registrations: readonly Registration[];
121
+ /** The scope keys `registrations` cover: the presence grant (§8.6.3). */
122
+ scopeKeys: ReadonlySet<string>;
116
123
  /** Epoch-ms (hub clock) at registration, for `realtime.closed`. */
117
124
  readonly openedAtMs: number;
118
125
  constructor(hub: RealtimeHub, options: RealtimeConnectOptions, registrations: readonly Registration[], cursor: number, latestSeq: number, clock: () => number, maxDeltaBytes: number, storage: ServerStorage, logEpoch: string, wireVersion: number, events: SyncularServerEvents | undefined);
@@ -126,6 +133,12 @@ export declare class RealtimeSession {
126
133
  * surfaces here instead of vanishing.
127
134
  */
128
135
  drain(): Promise<void>;
136
+ /** §8.6.1: hold the documents a host kept for this connection across an
137
+ * eviction, without fanout: peers already saw them. */
138
+ seedPresence(presence: ReadonlyMap<string, string>): void;
139
+ /** Clear this session's document for a key without fanout, including a
140
+ * coalesced publish still pending. Returns whether a document existed. */
141
+ forgetPresence(scopeKey: string): boolean;
129
142
  /** Deliver a fanout event to this session (called by the hub for peers,
130
143
  * §8.6.3 receive authorization checked by the caller). */
131
144
  receivePresence(scopeKey: string, kind: PresenceKind, actorId: string, clientId: string, doc: PresenceDoc | null): void;
@@ -164,8 +177,9 @@ export declare class RealtimeSession {
164
177
  * failed, because that round applied nothing.
165
178
  */
166
179
  /**
167
- * A pull outside this connection changed the client's subscriptions. A
168
- * round in flight on the connection reloads them at its end anyway.
180
+ * A pull outside this connection changed the client's registration list
181
+ * or live set. A round in flight on the connection reloads it at its end
182
+ * anyway.
169
183
  */
170
184
  refreshAfterPull(): Promise<void>;
171
185
  refreshRegistrations(failClosed: boolean): Promise<void>;
@@ -184,10 +198,13 @@ export interface RealtimeConnection {
184
198
  }
185
199
  export declare class RealtimeHub {
186
200
  #private;
201
+ /** The validated configured limits (§1.7); a bad value throws here. */
202
+ readonly limits: ServerLimits;
187
203
  /** §8.6 presence registry — ephemeral, in-memory, never persisted. */
188
204
  readonly presence: PresenceRegistry;
189
205
  constructor(config: RealtimeHubConfig);
190
- projectPayload(registration: Registration, payload: Uint8Array): Uint8Array;
206
+ /** The current compiled schema: the storage codec of fanned-out changes. */
207
+ get schema(): CompiledSchema;
191
208
  /**
192
209
  * Compose `sink` into the hub's `events`, so socket rounds and sessions
193
210
  * opened afterwards report to it as well. `createSyncularHono` uses it to
@@ -199,6 +216,10 @@ export declare class RealtimeHub {
199
216
  connections(partition: string): RealtimeConnection[];
200
217
  /** §8.6.2 published-document size cap (bytes). */
201
218
  get maxPresenceBytes(): number;
219
+ /** §8.2 flow control: unacknowledged deltas per session. */
220
+ get maxUnackedDeltas(): number;
221
+ /** §8.2 flow control: unacknowledged delta bytes per session. */
222
+ get maxUnackedDeltaBytes(): number;
202
223
  /** §8.6.4 presence rate cap (ms); 0 = off (reference default). */
203
224
  get presenceMinIntervalMs(): number;
204
225
  /** §8.6.3: the scope keys a set of registrations covers. */
@@ -208,12 +229,12 @@ export declare class RealtimeHub {
208
229
  * registered on the key (the privacy floor — only current scope-mates).
209
230
  * The publisher does not receive its own fanout.
210
231
  */
211
- fanoutPresence(origin: RealtimeSession, scopeKey: string, kind: PresenceKind, doc: PresenceDoc | null): void;
232
+ fanoutPresence(origin: Pick<RealtimeSession, 'partition' | 'actorId' | 'clientId'>, scopeKey: string, kind: PresenceKind, doc: PresenceDoc | null): void;
212
233
  /**
213
- * Resolve the client record's subscription list into per-connection
234
+ * Resolve the client record's live units into per-connection
214
235
  * registrations (§8.1 at upgrade; §8.7 at socket-round end).
215
236
  */
216
- loadRegistrations(partition: string, actorId: string, clientId: string): Promise<Registration[]>;
237
+ loadRegistrations(partition: string, actorId: string, clientId: string, record: ClientRecord | undefined): Promise<Registration[]>;
217
238
  /**
218
239
  * Build the per-round request context for a socket sync round (§8.7):
219
240
  * the same shape the HTTP adapter builds, so the round drives the
@@ -229,15 +250,32 @@ export declare class RealtimeHub {
229
250
  get mapError(): SyncularErrorMapper | undefined;
230
251
  requestContext(session: RealtimeSession): SyncRequestContext;
231
252
  /**
232
- * Register a connected socket (§8.1): load the client's last pull's
233
- * subscription list, resolve + intersect scopes, send `hello`.
253
+ * Register a connected socket (§8.1): load the client record's live
254
+ * units, resolve their effective scopes, send `hello`.
234
255
  */
235
256
  connect(options: RealtimeConnectOptions): Promise<RealtimeSession>;
257
+ /**
258
+ * Rebuild the sessions of sockets that outlived their host's memory, such as
259
+ * a hibernated Durable Object (§8.1). Each client saw `hello` and the
260
+ * presence snapshot at its real upgrade, so neither is sent again. The
261
+ * partition is touched and its latest sequence read once per partition, and
262
+ * each client record once. The caller holds back commits until this
263
+ * resolves, so the shared latest sequence stays current.
264
+ *
265
+ * `presence` is the connection's last `onPresence` report; the session
266
+ * holds it again without fanout (§8.6.1). Once every session is back, a
267
+ * key the reloaded registrations no longer cover leaves, and so does every
268
+ * key of a socket whose session could not be rebuilt.
269
+ */
270
+ restore(sockets: readonly (RealtimeConnectOptions & {
271
+ readonly presence?: ReadonlyMap<string, string>;
272
+ })[]): Promise<PromiseSettledResult<RealtimeSession>[]>;
236
273
  disconnect(session: RealtimeSession): void;
237
274
  /** RealtimeNotifier: fan an applied commit out to matching sessions. */
238
275
  notifyCommit(partition: string, commit: StoredCommit): Promise<void>;
239
276
  /**
240
- * RealtimeNotifier: a pull changed a client's subscription list (§8.7).
277
+ * RealtimeNotifier: a pull changed a client's registration list or live
278
+ * set (§8.1).
241
279
  * Its sockets reload their registrations with the round-end semantics, so
242
280
  * an unreadable record keeps the previous registrations.
243
281
  */
@@ -260,6 +298,14 @@ export declare class RealtimeHub {
260
298
  wake(partition: string, reason: WakeReason): void;
261
299
  /** Wake every session on every partition (fanout listener gap, §8.3). */
262
300
  wakeAll(reason: WakeReason): void;
301
+ /**
302
+ * §8.5: send `heartbeat` to every session. The host calls this on its
303
+ * heartbeat interval (suggested 30 s); a client that hears nothing for twice
304
+ * the interval treats the socket as lost.
305
+ */
306
+ heartbeat(): void;
263
307
  }
308
+ /** The §8.5 `heartbeat` control message. */
309
+ export declare function encodeHeartbeat(timestampMs: number): string;
264
310
  export declare function createRealtimeHub(config: RealtimeHubConfig): RealtimeHub;
265
311
  export {};