@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.
- package/README.md +49 -36
- package/dist/admin.d.ts +32 -20
- package/dist/admin.js +46 -40
- package/dist/blob-handlers.d.ts +25 -31
- package/dist/blob-handlers.js +63 -41
- package/dist/blob-store.d.ts +42 -24
- package/dist/blob-store.js +0 -0
- package/dist/bucket-blob-store.d.ts +12 -8
- package/dist/bucket-blob-store.js +54 -45
- package/dist/bucket-segment-store.js +18 -16
- package/dist/content-encoding.d.ts +5 -2
- package/dist/content-encoding.js +42 -13
- package/dist/context.d.ts +19 -5
- package/dist/context.js +19 -1
- package/dist/d1-storage.d.ts +14 -98
- package/dist/d1-storage.js +249 -1119
- package/dist/errors.js +16 -0
- package/dist/events.d.ts +36 -18
- package/dist/frame-bytes.js +24 -6
- package/dist/handler.js +503 -208
- package/dist/local-authority.d.ts +2 -0
- package/dist/local-authority.js +24 -12
- package/dist/object-bucket.d.ts +2 -0
- package/dist/operations-realtime.js +69 -50
- package/dist/operations.d.ts +5 -2
- package/dist/operations.js +20 -29
- package/dist/pg-executor-pglite.d.ts +5 -6
- package/dist/pg-executor-pglite.js +22 -14
- package/dist/pg-executor.d.ts +4 -1
- package/dist/postgres-storage.d.ts +24 -19
- package/dist/postgres-storage.js +420 -262
- package/dist/pull.d.ts +70 -47
- package/dist/pull.js +270 -301
- package/dist/push.d.ts +12 -3
- package/dist/push.js +361 -173
- package/dist/realtime.d.ts +85 -39
- package/dist/realtime.js +355 -219
- package/dist/relational-rows.d.ts +21 -66
- package/dist/relational-rows.js +28 -109
- package/dist/s3-blob-store.d.ts +11 -12
- package/dist/s3-blob-store.js +20 -13
- package/dist/s3-object-bucket.d.ts +8 -1
- package/dist/s3-object-bucket.js +16 -3
- package/dist/schema.d.ts +14 -0
- package/dist/schema.js +23 -0
- package/dist/scopes.d.ts +6 -2
- package/dist/scopes.js +22 -4
- package/dist/seed.js +10 -16
- package/dist/segment-download.d.ts +4 -1
- package/dist/segment-download.js +22 -6
- package/dist/signed-url.d.ts +2 -2
- package/dist/signed-url.js +9 -2
- package/dist/sigv4.d.ts +8 -2
- package/dist/sigv4.js +8 -4
- package/dist/sqlite-blob-store.d.ts +1 -1
- package/dist/sqlite-blob-store.js +23 -22
- package/dist/sqlite-dialect.d.ts +164 -84
- package/dist/sqlite-dialect.js +1145 -150
- package/dist/sqlite-lease-store.js +13 -18
- package/dist/sqlite-storage.d.ts +9 -62
- package/dist/sqlite-storage.js +303 -1123
- package/dist/storage-query.d.ts +30 -1
- package/dist/storage-query.js +68 -0
- package/dist/storage.d.ts +185 -63
- package/dist/storage.js +15 -0
- package/package.json +2 -2
- package/src/admin.ts +99 -57
- package/src/blob-handlers.ts +91 -72
- package/src/blob-store.ts +0 -0
- package/src/bucket-blob-store.ts +75 -48
- package/src/bucket-segment-store.ts +20 -15
- package/src/content-encoding.ts +48 -16
- package/src/context.ts +33 -6
- package/src/d1-storage.ts +350 -1700
- package/src/errors.ts +16 -0
- package/src/events.ts +37 -18
- package/src/frame-bytes.ts +26 -6
- package/src/handler.ts +654 -261
- package/src/local-authority.ts +27 -14
- package/src/object-bucket.ts +2 -0
- package/src/operations-realtime.ts +85 -61
- package/src/operations.ts +44 -42
- package/src/pg-executor-pglite.ts +27 -23
- package/src/pg-executor.ts +5 -1
- package/src/postgres-storage.ts +557 -354
- package/src/pull.ts +406 -440
- package/src/push.ts +466 -220
- package/src/realtime.ts +447 -290
- package/src/relational-rows.ts +43 -121
- package/src/s3-blob-store.ts +23 -13
- package/src/s3-object-bucket.ts +20 -2
- package/src/schema.ts +31 -0
- package/src/scopes.ts +23 -3
- package/src/seed.ts +13 -20
- package/src/segment-download.ts +33 -7
- package/src/signed-url.ts +10 -4
- package/src/sigv4.ts +17 -4
- package/src/sqlite-blob-store.ts +27 -26
- package/src/sqlite-dialect.ts +1851 -199
- package/src/sqlite-lease-store.ts +12 -23
- package/src/sqlite-storage.ts +390 -1821
- package/src/storage-query.ts +102 -0
- package/src/storage.ts +215 -67
package/dist/realtime.d.ts
CHANGED
|
@@ -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
|
-
*
|
|
11
|
-
*
|
|
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
|
|
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.
|
|
34
|
-
*
|
|
35
|
-
*
|
|
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
|
-
|
|
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
|
|
75
|
-
*
|
|
76
|
-
*
|
|
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
|
-
|
|
83
|
-
|
|
84
|
-
|
|
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
|
|
168
|
-
* round in flight on the connection reloads
|
|
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
|
-
|
|
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
|
|
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
|
|
233
|
-
*
|
|
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
|
|
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 {};
|