@syncular/server 0.57.0 → 0.59.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 (91) hide show
  1. package/README.md +31 -22
  2. package/dist/admin.js +8 -4
  3. package/dist/blob-handlers.d.ts +25 -31
  4. package/dist/blob-handlers.js +63 -41
  5. package/dist/blob-store.d.ts +42 -24
  6. package/dist/blob-store.js +0 -0
  7. package/dist/bucket-blob-store.d.ts +12 -8
  8. package/dist/bucket-blob-store.js +54 -45
  9. package/dist/bucket-segment-store.js +18 -16
  10. package/dist/content-encoding.d.ts +5 -2
  11. package/dist/content-encoding.js +42 -13
  12. package/dist/context.d.ts +16 -0
  13. package/dist/context.js +21 -1
  14. package/dist/d1-storage.d.ts +14 -98
  15. package/dist/d1-storage.js +223 -1111
  16. package/dist/errors.js +8 -0
  17. package/dist/events.d.ts +1 -1
  18. package/dist/handler.js +135 -103
  19. package/dist/local-authority.d.ts +2 -0
  20. package/dist/local-authority.js +17 -3
  21. package/dist/object-bucket.d.ts +2 -0
  22. package/dist/operations-realtime.js +69 -50
  23. package/dist/pg-executor-pglite.d.ts +5 -6
  24. package/dist/pg-executor-pglite.js +22 -14
  25. package/dist/pg-executor.d.ts +4 -1
  26. package/dist/postgres-storage.d.ts +1 -1
  27. package/dist/postgres-storage.js +182 -105
  28. package/dist/pull.d.ts +28 -20
  29. package/dist/pull.js +85 -87
  30. package/dist/push.js +272 -147
  31. package/dist/realtime.d.ts +68 -28
  32. package/dist/realtime.js +297 -136
  33. package/dist/relational-rows.d.ts +27 -15
  34. package/dist/relational-rows.js +38 -22
  35. package/dist/s3-blob-store.d.ts +11 -12
  36. package/dist/s3-blob-store.js +20 -13
  37. package/dist/s3-object-bucket.d.ts +8 -1
  38. package/dist/s3-object-bucket.js +16 -3
  39. package/dist/schema.d.ts +14 -0
  40. package/dist/schema.js +23 -0
  41. package/dist/scopes.d.ts +6 -2
  42. package/dist/scopes.js +22 -4
  43. package/dist/seed.js +1 -2
  44. package/dist/segment-download.js +18 -4
  45. package/dist/signed-url.d.ts +2 -2
  46. package/dist/signed-url.js +9 -2
  47. package/dist/sigv4.d.ts +8 -2
  48. package/dist/sigv4.js +8 -4
  49. package/dist/sqlite-blob-store.d.ts +1 -1
  50. package/dist/sqlite-blob-store.js +23 -22
  51. package/dist/sqlite-dialect.d.ts +150 -47
  52. package/dist/sqlite-dialect.js +987 -88
  53. package/dist/sqlite-lease-store.js +13 -18
  54. package/dist/sqlite-storage.d.ts +9 -62
  55. package/dist/sqlite-storage.js +293 -1117
  56. package/dist/storage.d.ts +32 -12
  57. package/package.json +2 -2
  58. package/src/admin.ts +16 -2
  59. package/src/blob-handlers.ts +91 -72
  60. package/src/blob-store.ts +0 -0
  61. package/src/bucket-blob-store.ts +75 -48
  62. package/src/bucket-segment-store.ts +20 -15
  63. package/src/content-encoding.ts +48 -16
  64. package/src/context.ts +32 -1
  65. package/src/d1-storage.ts +326 -1692
  66. package/src/errors.ts +8 -0
  67. package/src/events.ts +1 -1
  68. package/src/handler.ts +178 -127
  69. package/src/local-authority.ts +17 -3
  70. package/src/object-bucket.ts +2 -0
  71. package/src/operations-realtime.ts +85 -61
  72. package/src/pg-executor-pglite.ts +27 -23
  73. package/src/pg-executor.ts +5 -1
  74. package/src/postgres-storage.ts +231 -138
  75. package/src/pull.ts +133 -147
  76. package/src/push.ts +356 -205
  77. package/src/realtime.ts +380 -179
  78. package/src/relational-rows.ts +54 -27
  79. package/src/s3-blob-store.ts +23 -13
  80. package/src/s3-object-bucket.ts +20 -2
  81. package/src/schema.ts +31 -0
  82. package/src/scopes.ts +23 -3
  83. package/src/seed.ts +1 -2
  84. package/src/segment-download.ts +25 -4
  85. package/src/signed-url.ts +10 -4
  86. package/src/sigv4.ts +17 -4
  87. package/src/sqlite-blob-store.ts +27 -26
  88. package/src/sqlite-dialect.ts +1607 -114
  89. package/src/sqlite-lease-store.ts +12 -23
  90. package/src/sqlite-storage.ts +360 -1811
  91. package/src/storage.ts +33 -12
@@ -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
23
  import { type CompiledTable } from './schema.js';
24
- import type { ServerStorage, StoredCommit } from './storage.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,6 +71,13 @@ 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
  }
65
82
  interface Registration {
66
83
  readonly codec: CompiledTable;
@@ -71,30 +88,15 @@ interface Registration {
71
88
  }
72
89
  type PresenceDoc = Record<string, unknown>;
73
90
  /**
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).
91
+ * §8.6 presence index: per `(partition, scopeKey)`, the sessions holding a
92
+ * document there. The documents live with their session (§8.6.1). Pure
93
+ * in-memory state that never touches `ServerStorage`.
79
94
  */
80
95
  declare class PresenceRegistry {
81
96
  #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). */
97
+ add(partition: string, scopeKey: string, session: RealtimeSession): void;
98
+ delete(partition: string, scopeKey: string, session: RealtimeSession): void;
99
+ /** Sessions holding a document on a key. */
98
100
  peers(partition: string, scopeKey: string): RealtimeSession[];
99
101
  }
100
102
  export declare class RealtimeSession {
@@ -113,6 +115,8 @@ export declare class RealtimeSession {
113
115
  lastKnownSeq: number;
114
116
  /** Replaced at socket-round completion (§8.7); initial set from §8.1. */
115
117
  registrations: readonly Registration[];
118
+ /** The scope keys `registrations` cover: the presence grant (§8.6.3). */
119
+ scopeKeys: ReadonlySet<string>;
116
120
  /** Epoch-ms (hub clock) at registration, for `realtime.closed`. */
117
121
  readonly openedAtMs: number;
118
122
  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 +130,12 @@ export declare class RealtimeSession {
126
130
  * surfaces here instead of vanishing.
127
131
  */
128
132
  drain(): Promise<void>;
133
+ /** §8.6.1: hold the documents a host kept for this connection across an
134
+ * eviction, without fanout: peers already saw them. */
135
+ seedPresence(presence: ReadonlyMap<string, string>): void;
136
+ /** Clear this session's document for a key without fanout, including a
137
+ * coalesced publish still pending. Returns whether a document existed. */
138
+ forgetPresence(scopeKey: string): boolean;
129
139
  /** Deliver a fanout event to this session (called by the hub for peers,
130
140
  * §8.6.3 receive authorization checked by the caller). */
131
141
  receivePresence(scopeKey: string, kind: PresenceKind, actorId: string, clientId: string, doc: PresenceDoc | null): void;
@@ -184,6 +194,8 @@ export interface RealtimeConnection {
184
194
  }
185
195
  export declare class RealtimeHub {
186
196
  #private;
197
+ /** The validated configured limits (§1.7); a bad value throws here. */
198
+ readonly limits: ServerLimits;
187
199
  /** §8.6 presence registry — ephemeral, in-memory, never persisted. */
188
200
  readonly presence: PresenceRegistry;
189
201
  constructor(config: RealtimeHubConfig);
@@ -199,6 +211,10 @@ export declare class RealtimeHub {
199
211
  connections(partition: string): RealtimeConnection[];
200
212
  /** §8.6.2 published-document size cap (bytes). */
201
213
  get maxPresenceBytes(): number;
214
+ /** §8.2 flow control: unacknowledged deltas per session. */
215
+ get maxUnackedDeltas(): number;
216
+ /** §8.2 flow control: unacknowledged delta bytes per session. */
217
+ get maxUnackedDeltaBytes(): number;
202
218
  /** §8.6.4 presence rate cap (ms); 0 = off (reference default). */
203
219
  get presenceMinIntervalMs(): number;
204
220
  /** §8.6.3: the scope keys a set of registrations covers. */
@@ -208,12 +224,12 @@ export declare class RealtimeHub {
208
224
  * registered on the key (the privacy floor — only current scope-mates).
209
225
  * The publisher does not receive its own fanout.
210
226
  */
211
- fanoutPresence(origin: RealtimeSession, scopeKey: string, kind: PresenceKind, doc: PresenceDoc | null): void;
227
+ fanoutPresence(origin: Pick<RealtimeSession, 'partition' | 'actorId' | 'clientId'>, scopeKey: string, kind: PresenceKind, doc: PresenceDoc | null): void;
212
228
  /**
213
229
  * Resolve the client record's subscription list into per-connection
214
230
  * registrations (§8.1 at upgrade; §8.7 at socket-round end).
215
231
  */
216
- loadRegistrations(partition: string, actorId: string, clientId: string): Promise<Registration[]>;
232
+ loadRegistrations(partition: string, actorId: string, clientId: string, record: ClientRecord | undefined): Promise<Registration[]>;
217
233
  /**
218
234
  * Build the per-round request context for a socket sync round (§8.7):
219
235
  * the same shape the HTTP adapter builds, so the round drives the
@@ -233,6 +249,22 @@ export declare class RealtimeHub {
233
249
  * subscription list, resolve + intersect scopes, send `hello`.
234
250
  */
235
251
  connect(options: RealtimeConnectOptions): Promise<RealtimeSession>;
252
+ /**
253
+ * Rebuild the sessions of sockets that outlived their host's memory, such as
254
+ * a hibernated Durable Object (§8.1). Each client saw `hello` and the
255
+ * presence snapshot at its real upgrade, so neither is sent again. The
256
+ * partition is touched and its latest sequence read once per partition, and
257
+ * each client record once. The caller holds back commits until this
258
+ * resolves, so the shared latest sequence stays current.
259
+ *
260
+ * `presence` is the connection's last `onPresence` report; the session
261
+ * holds it again without fanout (§8.6.1). Once every session is back, a
262
+ * key the reloaded registrations no longer cover leaves, and so does every
263
+ * key of a socket whose session could not be rebuilt.
264
+ */
265
+ restore(sockets: readonly (RealtimeConnectOptions & {
266
+ readonly presence?: ReadonlyMap<string, string>;
267
+ })[]): Promise<PromiseSettledResult<RealtimeSession>[]>;
236
268
  disconnect(session: RealtimeSession): void;
237
269
  /** RealtimeNotifier: fan an applied commit out to matching sessions. */
238
270
  notifyCommit(partition: string, commit: StoredCommit): Promise<void>;
@@ -260,6 +292,14 @@ export declare class RealtimeHub {
260
292
  wake(partition: string, reason: WakeReason): void;
261
293
  /** Wake every session on every partition (fanout listener gap, §8.3). */
262
294
  wakeAll(reason: WakeReason): void;
295
+ /**
296
+ * §8.5: send `heartbeat` to every session. The host calls this on its
297
+ * heartbeat interval (suggested 30 s); a client that hears nothing for twice
298
+ * the interval treats the socket as lost.
299
+ */
300
+ heartbeat(): void;
263
301
  }
302
+ /** The §8.5 `heartbeat` control message. */
303
+ export declare function encodeHeartbeat(timestampMs: number): string;
264
304
  export declare function createRealtimeHub(config: RealtimeHubConfig): RealtimeHub;
265
305
  export {};