@syncular/server 0.58.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.
- package/README.md +31 -22
- package/dist/admin.js +8 -4
- 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 +16 -0
- package/dist/context.js +21 -1
- package/dist/d1-storage.d.ts +14 -98
- package/dist/d1-storage.js +223 -1111
- package/dist/errors.js +8 -0
- package/dist/events.d.ts +1 -1
- package/dist/handler.js +135 -103
- package/dist/local-authority.d.ts +2 -0
- package/dist/local-authority.js +17 -3
- package/dist/object-bucket.d.ts +2 -0
- package/dist/operations-realtime.js +69 -50
- 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 +1 -1
- package/dist/postgres-storage.js +182 -105
- package/dist/pull.d.ts +28 -20
- package/dist/pull.js +85 -87
- package/dist/push.js +272 -147
- package/dist/realtime.d.ts +68 -28
- package/dist/realtime.js +297 -136
- package/dist/relational-rows.d.ts +27 -15
- package/dist/relational-rows.js +38 -22
- 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 +1 -2
- package/dist/segment-download.js +18 -4
- 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 +150 -47
- package/dist/sqlite-dialect.js +987 -88
- package/dist/sqlite-lease-store.js +13 -18
- package/dist/sqlite-storage.d.ts +9 -62
- package/dist/sqlite-storage.js +293 -1117
- package/dist/storage.d.ts +32 -12
- package/package.json +2 -2
- package/src/admin.ts +16 -2
- 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 +32 -1
- package/src/d1-storage.ts +326 -1692
- package/src/errors.ts +8 -0
- package/src/events.ts +1 -1
- package/src/handler.ts +178 -127
- package/src/local-authority.ts +17 -3
- package/src/object-bucket.ts +2 -0
- package/src/operations-realtime.ts +85 -61
- package/src/pg-executor-pglite.ts +27 -23
- package/src/pg-executor.ts +5 -1
- package/src/postgres-storage.ts +231 -138
- package/src/pull.ts +133 -147
- package/src/push.ts +356 -205
- package/src/realtime.ts +380 -179
- package/src/relational-rows.ts +54 -27
- 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 +1 -2
- package/src/segment-download.ts +25 -4
- 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 +1607 -114
- package/src/sqlite-lease-store.ts +12 -23
- package/src/sqlite-storage.ts +360 -1811
- package/src/storage.ts +33 -12
package/dist/realtime.d.ts
CHANGED
|
@@ -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.
|
|
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,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
|
|
75
|
-
*
|
|
76
|
-
*
|
|
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
|
-
|
|
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). */
|
|
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 {};
|