@syncular/server 0.74.0 → 0.76.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 (47) hide show
  1. package/dist/admin.d.ts +6 -3
  2. package/dist/admin.js +10 -7
  3. package/dist/blob-handlers.js +2 -0
  4. package/dist/bucket-segment-store.d.ts +4 -3
  5. package/dist/bucket-segment-store.js +4 -2
  6. package/dist/context.d.ts +29 -1
  7. package/dist/context.js +23 -2
  8. package/dist/handler.js +7 -2
  9. package/dist/index.d.ts +1 -1
  10. package/dist/lease-store.d.ts +10 -3
  11. package/dist/lease-store.js +0 -0
  12. package/dist/operations.js +2 -0
  13. package/dist/pull.d.ts +9 -4
  14. package/dist/pull.js +129 -76
  15. package/dist/realtime.d.ts +14 -1
  16. package/dist/realtime.js +14 -3
  17. package/dist/segment-download.js +1 -0
  18. package/dist/segment-store.d.ts +6 -4
  19. package/dist/segment-store.js +4 -2
  20. package/dist/signed-url.d.ts +15 -0
  21. package/dist/signed-url.js +7 -2
  22. package/dist/sqlite-bun.js +2 -2
  23. package/dist/sqlite-image.d.ts +18 -3
  24. package/dist/sqlite-image.js +27 -5
  25. package/dist/sqlite-lease-store.d.ts +1 -1
  26. package/dist/sqlite-lease-store.js +19 -6
  27. package/dist/sqlite-node.js +3 -2
  28. package/dist/sqlite-segment-store.js +7 -7
  29. package/package.json +2 -2
  30. package/src/admin.ts +11 -5
  31. package/src/blob-handlers.ts +2 -0
  32. package/src/bucket-segment-store.ts +8 -5
  33. package/src/context.ts +38 -2
  34. package/src/handler.ts +9 -1
  35. package/src/index.ts +1 -0
  36. package/src/lease-store.ts +0 -0
  37. package/src/operations.ts +2 -0
  38. package/src/pull.ts +200 -94
  39. package/src/realtime.ts +26 -12
  40. package/src/segment-download.ts +1 -0
  41. package/src/segment-store.ts +10 -6
  42. package/src/signed-url.ts +22 -2
  43. package/src/sqlite-bun.ts +2 -2
  44. package/src/sqlite-image.ts +42 -7
  45. package/src/sqlite-lease-store.ts +22 -4
  46. package/src/sqlite-node.ts +3 -2
  47. package/src/sqlite-segment-store.ts +29 -7
package/dist/admin.d.ts CHANGED
@@ -478,18 +478,21 @@ export declare class SyncularAdmin {
478
478
  * Trace whether one client receives one row, combining the row's stored
479
479
  * scopes and newest change with the client's units, cursor, the
480
480
  * actor's allowed scopes, and its retained push failures. See
481
- * `AdminTraceVerdict` for the verdict order.
481
+ * `AdminTraceVerdict` for the verdict order. `context` is the
482
+ * authentication context (§1.1) to resolve the actor's scopes under.
482
483
  */
483
484
  traceRow(partition: string, query: {
484
485
  readonly table: string;
485
486
  readonly rowId: string;
486
487
  readonly clientId: string;
488
+ readonly context?: string;
487
489
  }): Promise<AdminRowTrace>;
488
490
  /**
489
491
  * Who has one row and who does not: the trace verdict for every known
490
- * client in the partition, resolving each actor's allowed scopes once.
492
+ * client in the partition, resolving each actor's allowed scopes once
493
+ * under `context` (§1.1).
491
494
  */
492
- rowDelivery(partition: string, table: string, rowId: string): Promise<AdminRowDelivery>;
495
+ rowDelivery(partition: string, table: string, rowId: string, context?: string): Promise<AdminRowDelivery>;
493
496
  /**
494
497
  * The partition's actors with their devices (clients), open sockets,
495
498
  * worst lag, and failures in the last 5 minutes; most recently seen
package/dist/admin.js CHANGED
@@ -322,10 +322,11 @@ export class SyncularAdmin {
322
322
  * Trace whether one client receives one row, combining the row's stored
323
323
  * scopes and newest change with the client's units, cursor, the
324
324
  * actor's allowed scopes, and its retained push failures. See
325
- * `AdminTraceVerdict` for the verdict order.
325
+ * `AdminTraceVerdict` for the verdict order. `context` is the
326
+ * authentication context (§1.1) to resolve the actor's scopes under.
326
327
  */
327
328
  async traceRow(partition, query) {
328
- const { table, rowId, clientId } = query;
329
+ const { table, rowId, clientId, context } = query;
329
330
  const row = await this.inspectRow(partition, table, rowId, {
330
331
  historyLimit: 1,
331
332
  });
@@ -345,7 +346,7 @@ export class SyncularAdmin {
345
346
  if (record === undefined) {
346
347
  return { ...base, verdict: 'client-unknown', units: [] };
347
348
  }
348
- const allowed = await this.#allowedScopes(partition, record);
349
+ const allowed = await this.#allowedScopes(partition, record, context);
349
350
  return {
350
351
  ...base,
351
352
  client: (await this.#clientView(partition))(record),
@@ -355,9 +356,10 @@ export class SyncularAdmin {
355
356
  }
356
357
  /**
357
358
  * Who has one row and who does not: the trace verdict for every known
358
- * client in the partition, resolving each actor's allowed scopes once.
359
+ * client in the partition, resolving each actor's allowed scopes once
360
+ * under `context` (§1.1).
359
361
  */
360
- async rowDelivery(partition, table, rowId) {
362
+ async rowDelivery(partition, table, rowId, context) {
361
363
  const list = required(this.#storage.listClientRecords?.bind(this.#storage), 'storage');
362
364
  const row = await this.inspectRow(partition, table, rowId, {
363
365
  historyLimit: 1,
@@ -370,7 +372,7 @@ export class SyncularAdmin {
370
372
  const clients = [];
371
373
  for (const record of await list(partition)) {
372
374
  if (!allowedByActor.has(record.actorId)) {
373
- allowedByActor.set(record.actorId, await this.#allowedScopes(partition, record));
375
+ allowedByActor.set(record.actorId, await this.#allowedScopes(partition, record, context));
374
376
  }
375
377
  clients.push({
376
378
  client: view(record),
@@ -945,13 +947,14 @@ export class SyncularAdmin {
945
947
  };
946
948
  }
947
949
  /** The actor's allowed scopes from the host resolver, if one is wired. */
948
- async #allowedScopes(partition, record) {
950
+ async #allowedScopes(partition, record, context) {
949
951
  if (this.#resolveScopes === undefined)
950
952
  return undefined;
951
953
  const resolved = await this.#resolveScopes({
952
954
  partition,
953
955
  actorId: record.actorId,
954
956
  clientId: record.clientId,
957
+ ...(context !== undefined ? { context } : {}),
955
958
  });
956
959
  return resolved === RESOLVER_OUTAGE ? 'outage' : resolved;
957
960
  }
@@ -138,6 +138,7 @@ async function downloadBlob(ctx, blobId) {
138
138
  const allowed = await ctx.resolveScopes({
139
139
  partition: ctx.partition,
140
140
  actorId: ctx.actorId,
141
+ ...(ctx.context !== undefined ? { context: ctx.context } : {}),
141
142
  });
142
143
  // §7.3.3: leases never authorize a blob download — an outage denies.
143
144
  resolved =
@@ -187,6 +188,7 @@ async function downloadBlob(ctx, blobId) {
187
188
  partition: ctx.partition,
188
189
  blobId,
189
190
  nowMs: clockOf(ctx)(),
191
+ ...(ctx.context !== undefined ? { context: ctx.context } : {}),
190
192
  });
191
193
  return {
192
194
  headers: {
@@ -23,10 +23,11 @@
23
23
  * objects.
24
24
  *
25
25
  * {keyPrefix}find/{sha256Hex(canonical reuse key)}.json
26
- * Whole-table reuse pointer (§5.3): written only when
27
- * `rowCursor === null`, body = the record JSON. The reuse key is the
26
+ * Image reuse pointer (§5.3): written for every sqlite image and every
27
+ * first rows page, body = the record JSON. The reuse key is the
28
28
  * canonical JSON array `[partition, logEpoch, table, schemaVersion,
29
- * mediaType, scopeDigest, asOfCommitSeq]`, so `find` is one GET (plus a
29
+ * mediaType, scopeDigest, asOfCommitSeq]` plus the range start when it is
30
+ * not null, so `find` is one GET (plus a
30
31
  * HEAD to confirm the segment object itself still exists — lifecycle GC
31
32
  * may remove objects independently of pointers).
32
33
  *
@@ -214,6 +214,8 @@ export class BucketSegmentStore {
214
214
  key.mediaType,
215
215
  key.scopeDigest,
216
216
  key.asOfCommitSeq,
217
+ // A first range keeps the pointer key it had before range images.
218
+ ...(key.rowCursor === null ? [] : [key.rowCursor]),
217
219
  ]);
218
220
  return `${this.#prefix}find/${await sha256Hex(canonical)}.json`;
219
221
  }
@@ -300,7 +302,7 @@ export class BucketSegmentStore {
300
302
  sqliteSegments: metadata.mediaType === 'sqlite' ? 1 : 0,
301
303
  });
302
304
  }
303
- if (metadata.rowCursor === null) {
305
+ if (metadata.rowCursor === null || metadata.mediaType === 'sqlite') {
304
306
  await this.#bucket.put(await this.#findKeyFor(metadata), {
305
307
  body: new TextEncoder().encode(recordJson),
306
308
  contentType: 'application/json',
@@ -415,7 +417,7 @@ export class BucketSegmentStore {
415
417
  mediaType: key.mediaType,
416
418
  scopeDigest: key.scopeDigest,
417
419
  asOfCommitSeq: key.asOfCommitSeq,
418
- rowCursor: null,
420
+ rowCursor: key.rowCursor,
419
421
  nowMs,
420
422
  });
421
423
  if (publication === undefined)
package/dist/context.d.ts CHANGED
@@ -30,6 +30,12 @@ export interface ResolveScopesArgs {
30
30
  * actor + scopes only (§5.5, §5.9.5) and never consult a lease.
31
31
  */
32
32
  readonly clientId?: string;
33
+ /**
34
+ * The authentication context the host's `authenticate` returned for this
35
+ * request (§1.1), passed unchanged on every path that resolves scopes.
36
+ * Absent when the host returned none.
37
+ */
38
+ readonly context?: string;
33
39
  }
34
40
  /**
35
41
  * Sentinel a resolver returns to signal a **live-authorization outage**
@@ -80,6 +86,12 @@ export interface ServerLimits {
80
86
  * pass it alone resets the units it reaches, which bootstrap instead.
81
87
  */
82
88
  readonly maxLiveSectionBytes: number;
89
+ /**
90
+ * §5.3 bound on one sqlite image's file size: the server cuts a table into
91
+ * range images in row order, each within this bound. A row larger than the
92
+ * bound gets an image of its own.
93
+ */
94
+ readonly maxImageSegmentBytes: number;
83
95
  }
84
96
  export declare const DEFAULT_LIMITS: ServerLimits;
85
97
  /** Receives applied commits for realtime fanout (§8.2). */
@@ -216,6 +228,18 @@ export interface SyncServerConfig {
216
228
  export interface SyncRequestContext extends SyncServerConfig {
217
229
  readonly partition: string;
218
230
  readonly actorId: string;
231
+ /** The host authentication context (§1.1), at most 256 UTF-8 bytes. */
232
+ readonly context?: string;
233
+ }
234
+ /** §1.1: `authenticate` returned a context longer than 256 UTF-8 bytes. */
235
+ export declare class AuthContextTooLargeError extends Error {
236
+ readonly name = "AuthContextTooLargeError";
237
+ readonly code = "sync.auth_context_too_large";
238
+ readonly details: {
239
+ readonly byteLength: number;
240
+ readonly max: 256;
241
+ };
242
+ constructor(byteLength: number);
219
243
  }
220
244
  export declare function clockOf(ctx: SyncServerConfig): () => number;
221
245
  /**
@@ -224,5 +248,9 @@ export declare function clockOf(ctx: SyncServerConfig): () => number;
224
248
  * `inlineSegmentMaxBytes` is a threshold and may be `0` (inline nothing).
225
249
  */
226
250
  export declare function limitsOf(ctx: SyncServerConfig): ServerLimits;
227
- /** Refresh the registry after host authentication and return log continuity. */
251
+ /**
252
+ * Refresh the registry after host authentication and return log continuity.
253
+ * Every authenticated entry point runs this first, so it also refuses an
254
+ * oversized authentication context (§1.1) before any resolver sees it.
255
+ */
228
256
  export declare function touchAuthenticatedPartition(ctx: SyncRequestContext): Promise<PartitionRegistryEntry>;
package/dist/context.js CHANGED
@@ -23,7 +23,19 @@ export const DEFAULT_LIMITS = {
23
23
  maxWatchesPerSession: 100,
24
24
  // The live section is buffered whole before the first unit section.
25
25
  maxLiveSectionBytes: 16 * 1024 * 1024,
26
+ // §5.3 DECISION (2026-11-17): a client holds about three images at once.
27
+ maxImageSegmentBytes: 32 * 1024 * 1024,
26
28
  };
29
+ /** §1.1: `authenticate` returned a context longer than 256 UTF-8 bytes. */
30
+ export class AuthContextTooLargeError extends Error {
31
+ name = 'AuthContextTooLargeError';
32
+ code = 'sync.auth_context_too_large';
33
+ details;
34
+ constructor(byteLength) {
35
+ super('authentication context exceeds 256 UTF-8 bytes');
36
+ this.details = { byteLength, max: 256 };
37
+ }
38
+ }
27
39
  export function clockOf(ctx) {
28
40
  return ctx.clock ?? Date.now;
29
41
  }
@@ -42,7 +54,16 @@ export function limitsOf(ctx) {
42
54
  }
43
55
  return limits;
44
56
  }
45
- /** Refresh the registry after host authentication and return log continuity. */
46
- export function touchAuthenticatedPartition(ctx) {
57
+ /**
58
+ * Refresh the registry after host authentication and return log continuity.
59
+ * Every authenticated entry point runs this first, so it also refuses an
60
+ * oversized authentication context (§1.1) before any resolver sees it.
61
+ */
62
+ export async function touchAuthenticatedPartition(ctx) {
63
+ if (ctx.context !== undefined) {
64
+ const byteLength = new TextEncoder().encode(ctx.context).length;
65
+ if (byteLength > 256)
66
+ throw new AuthContextTooLargeError(byteLength);
67
+ }
47
68
  return ctx.storage.touchPartition(ctx.partition, clockOf(ctx)(), crypto.randomUUID());
48
69
  }
package/dist/handler.js CHANGED
@@ -47,7 +47,11 @@ async function authorizeFromLease(ctx, clientId, schema) {
47
47
  throw syncError('sync.auth_lease_required', 'live authorization is unavailable and auth leases are not configured (§7.3.3)');
48
48
  }
49
49
  const lease = await leases.store.get(ctx.partition, clientId);
50
- if (lease === undefined || lease.actorId !== ctx.actorId) {
50
+ // A lease binds the actor and the authentication context it was issued
51
+ // under (§7.3.1): another session of the same actor is not its holder.
52
+ if (lease === undefined ||
53
+ lease.actorId !== ctx.actorId ||
54
+ lease.context !== ctx.context) {
51
55
  throw syncError('sync.auth_lease_required', 'no valid auth lease for this client during an authorization outage (§7.3.3)');
52
56
  }
53
57
  if (lease.revoked) {
@@ -66,6 +70,7 @@ async function resolveOnce(ctx, clientId, schema) {
66
70
  partition: ctx.partition,
67
71
  actorId: ctx.actorId,
68
72
  clientId,
73
+ ...(ctx.context !== undefined ? { context: ctx.context } : {}),
69
74
  });
70
75
  }
71
76
  catch (error) {
@@ -98,7 +103,7 @@ async function resolveOnce(ctx, clientId, schema) {
98
103
  // (sliding window) and emits a LEASE frame — only when configured.
99
104
  let leaseToEmit;
100
105
  if (ctx.leases !== undefined) {
101
- leaseToEmit = await ctx.leases.store.issue(ctx.partition, clientId, ctx.actorId, allowed, clockOf(ctx)(), ctx.leases.ttlMs);
106
+ leaseToEmit = await ctx.leases.store.issue(ctx.partition, clientId, ctx.actorId, allowed, clockOf(ctx)(), ctx.leases.ttlMs, ctx.context);
102
107
  }
103
108
  return { resolved: { ok: true, allowed }, leaseToEmit };
104
109
  }
package/dist/index.d.ts CHANGED
@@ -50,7 +50,7 @@ export * from './segment-store.js';
50
50
  export * from './signed-url.js';
51
51
  export * from './sqlite-dialect.js';
52
52
  export * from './sqlite-driver.js';
53
- export { IMAGE_METADATA_TABLE, IMAGE_VERSION_COLUMN, type SqliteImageBuilder, type SqliteImageInput, writeSqliteImage, } from './sqlite-image.js';
53
+ export { IMAGE_METADATA_TABLE, IMAGE_VERSION_COLUMN, type SqliteImage, type SqliteImageBuilder, type SqliteImageInput, writeSqliteImage, } from './sqlite-image.js';
54
54
  export * from './sqlite-blob-store.js';
55
55
  export * from './sqlite-lease-store.js';
56
56
  export * from './sqlite-segment-store.js';
@@ -17,6 +17,12 @@ import type { ScopeMap } from '@syncular/core';
17
17
  export interface LeaseRecord {
18
18
  readonly leaseId: string;
19
19
  readonly actorId: string;
20
+ /**
21
+ * The authentication context (§1.1) the issuing round resolved scopes
22
+ * under; absent when it had none. A lease never authorizes a request
23
+ * under another context (§7.3.3).
24
+ */
25
+ readonly context?: string;
20
26
  /** The actor's resolved allowed scopes at issuance (§3.2 step 3). */
21
27
  readonly allowedScopes: ScopeMap;
22
28
  readonly issuedAtMs: number;
@@ -31,9 +37,10 @@ export interface LeaseStore {
31
37
  * refresh slides the SAME `leaseId` — implementations MUST reuse the
32
38
  * stored id for the pair unless it is revoked (a revoked handle never
33
39
  * silently resurrects: a fresh id is minted only once the host clears
34
- * the revocation). Returns the stored record.
40
+ * the revocation). A refresh by another actor or under another
41
+ * `context` mints a fresh id. Returns the stored record.
35
42
  */
36
- issue(partition: string, clientId: string, actorId: string, allowedScopes: ScopeMap, nowMs: number, ttlMs: number): Promise<LeaseRecord>;
43
+ issue(partition: string, clientId: string, actorId: string, allowedScopes: ScopeMap, nowMs: number, ttlMs: number, context?: string): Promise<LeaseRecord>;
37
44
  /** Revoke a lease by `leaseId` (§7.3.4); durable, survives refresh. */
38
45
  revoke(partition: string, leaseId: string): Promise<void>;
39
46
  }
@@ -45,6 +52,6 @@ export declare class MemoryLeaseStore implements LeaseStore {
45
52
  readonly leaseId?: LeaseIdFactory;
46
53
  });
47
54
  get(partition: string, clientId: string): Promise<LeaseRecord | undefined>;
48
- issue(partition: string, clientId: string, actorId: string, allowedScopes: ScopeMap, nowMs: number, ttlMs: number): Promise<LeaseRecord>;
55
+ issue(partition: string, clientId: string, actorId: string, allowedScopes: ScopeMap, nowMs: number, ttlMs: number, context?: string): Promise<LeaseRecord>;
49
56
  revoke(partition: string, leaseId: string): Promise<void>;
50
57
  }
Binary file
@@ -131,6 +131,7 @@ export function registerRemoteQuery(descriptor, options) {
131
131
  partition: ctx.partition,
132
132
  actorId: ctx.actorId,
133
133
  clientId,
134
+ ...(ctx.context !== undefined ? { context: ctx.context } : {}),
134
135
  });
135
136
  if (allowed === RESOLVER_OUTAGE) {
136
137
  throw syncError('operation.forbidden', 'live scope authorization is unavailable for this query');
@@ -345,6 +346,7 @@ export function registerRemoteCommand(descriptor, options) {
345
346
  partition: ctx.partition,
346
347
  actorId: ctx.actorId,
347
348
  clientId,
349
+ ...(ctx.context !== undefined ? { context: ctx.context } : {}),
348
350
  });
349
351
  if (allowed === RESOLVER_OUTAGE) {
350
352
  throw syncError('operation.forbidden', 'live scope authorization is unavailable for this command');
package/dist/pull.d.ts CHANGED
@@ -74,6 +74,8 @@ export interface BootstrapPlan {
74
74
  readonly pin: number;
75
75
  readonly tableIndex: number;
76
76
  readonly rowCursor: string | null;
77
+ /** Whether the position continues the table's range images (§5.3). */
78
+ readonly image: boolean;
77
79
  /** Table index → its start reads. */
78
80
  readonly starts: ReadonlyMap<number, Promise<TableStart>>;
79
81
  }
@@ -108,17 +110,20 @@ export interface PublishSqliteImageInput {
108
110
  readonly allowed?: ScopeMap;
109
111
  }
110
112
  export interface PublishedSqliteImage {
111
- readonly segmentId: string;
112
- /** The §4.7 scope pin the image is stored under. */
113
+ /** The table's range images in row order (§5.3). */
114
+ readonly segmentIds: readonly string[];
115
+ /** The §4.7 scope pin the images are stored under. */
113
116
  readonly asOfCommitSeq: number;
114
117
  readonly scopeDigest: string;
118
+ /** Rows across every range image. */
115
119
  readonly rowCount: number;
120
+ /** Bytes across every range image. */
116
121
  readonly byteLength: number;
117
- /** `reused` when an unexpired image for the same reuse key already existed. */
122
+ /** `reused` when an unexpired image existed for every range's reuse key. */
118
123
  readonly origin: 'built' | 'reused';
119
124
  }
120
125
  /**
121
- * Publish the §5.3 sqlite image that a pull of (`scopes`, `table`) looks up,
126
+ * Publish the §5.3 range images that a pull of (`scopes`, `table`) looks up,
122
127
  * from a host with a SQLite engine (a Bun process with the production
123
128
  * storage). It runs the pull's own bootstrap path (the §4.7 scope pin, the
124
129
  * reuse key, the build), so the stored identity is exactly the one a