@syncular/server-workers 0.73.0 → 0.75.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/dist/index.d.ts CHANGED
@@ -176,6 +176,7 @@ export declare function createWorkersFetchHandler<Env = unknown>(factoryOrOption
176
176
  export declare function forwardSyncRequest(request: Request, namespace: DurableObjectNamespaceLike, identity: {
177
177
  readonly partition: string;
178
178
  readonly actorId: string;
179
+ readonly context?: string;
179
180
  }, path?: string): Promise<Response>;
180
181
  /**
181
182
  * Forward a `/realtime` upgrade to the partition's DO stub. The identity is
@@ -69,7 +69,9 @@
69
69
  * is re-derived from storage, which is authoritative.
70
70
  *
71
71
  * The attachment is one `Uint8Array`, so its structured-clone size is its
72
- * byte length plus fixed framing: the identity as UTF-8 JSON and a newline,
72
+ * byte length plus fixed framing: the identity as UTF-8 JSON (`[partition,
73
+ * actorId, clientId]`, plus the authentication context as a fourth element
74
+ * when the upgrade had one) and a newline,
73
75
  * then per presence key a varint key length, the key's UTF-8 bytes, the
74
76
  * document's UTF-8 JSON and a newline (a JSON text holds no raw newline).
75
77
  * Each key costs at least 3 counted bytes (a non-empty key and `{}`) and at
@@ -192,6 +194,8 @@ export interface RealtimeUpgradeIdentity {
192
194
  readonly partition: string;
193
195
  readonly actorId: string;
194
196
  readonly clientId: string;
197
+ /** The authentication context (§1.1) the connection resolves scopes under. */
198
+ readonly context?: string;
195
199
  }
196
200
  /** Internal control-request paths on the DO stub (never client-facing). */
197
201
  export declare const REALTIME_DO_WAKE_PATH = "/__syncular_realtime/wake";
@@ -254,6 +258,7 @@ export declare class SyncularRealtimeHost<S extends RealtimeHostStorage = D1Serv
254
258
  serialized<T>(work: (contextFor: (identity: {
255
259
  readonly partition: string;
256
260
  readonly actorId: string;
261
+ readonly context?: string;
257
262
  }) => SyncRequestContext) => Promise<T>): Promise<T>;
258
263
  /** Trusted maintenance shares the partition FIFO with HTTP/socket writes. */
259
264
  pruneCommitLog(options: Omit<PruneOptions, 'storage'>): Promise<number>;
@@ -284,9 +289,15 @@ export declare function adminRequestForDurableObject(request: Request, routePath
284
289
  readonly partition: string;
285
290
  readonly actions: boolean;
286
291
  }): Request;
292
+ /**
293
+ * Write the authenticated identity onto a forwarded request's headers (Worker
294
+ * side). The forwarded request copies the client's headers, so a context
295
+ * header the client sent is removed when authentication yielded none.
296
+ */
287
297
  export declare function writeRequestIdentityHeaders(headers: Headers, identity: {
288
298
  readonly partition: string;
289
299
  readonly actorId: string;
300
+ readonly context?: string;
290
301
  }): void;
291
302
  /** Write the resolved identity onto an upgrade request's headers (Worker side). */
292
303
  export declare function writeIdentityHeaders(headers: Headers, identity: RealtimeUpgradeIdentity): void;
@@ -69,7 +69,9 @@
69
69
  * is re-derived from storage, which is authoritative.
70
70
  *
71
71
  * The attachment is one `Uint8Array`, so its structured-clone size is its
72
- * byte length plus fixed framing: the identity as UTF-8 JSON and a newline,
72
+ * byte length plus fixed framing: the identity as UTF-8 JSON (`[partition,
73
+ * actorId, clientId]`, plus the authentication context as a fourth element
74
+ * when the upgrade had one) and a newline,
73
75
  * then per presence key a varint key length, the key's UTF-8 bytes, the
74
76
  * document's UTF-8 JSON and a newline (a JSON text holds no raw newline).
75
77
  * Each key costs at least 3 counted bytes (a non-empty key and `{}`) and at
@@ -121,7 +123,12 @@ export class PresenceAttachmentError extends Error {
121
123
  function encodeAttachment(identity, presence) {
122
124
  const utf8 = new TextEncoder();
123
125
  const bytes = [
124
- ...utf8.encode(JSON.stringify([identity.partition, identity.actorId, identity.clientId])),
126
+ ...utf8.encode(JSON.stringify([
127
+ identity.partition,
128
+ identity.actorId,
129
+ identity.clientId,
130
+ ...(identity.context !== undefined ? [identity.context] : []),
131
+ ])),
125
132
  0x0a,
126
133
  ];
127
134
  for (const [scopeKey, json] of presence) {
@@ -340,7 +347,7 @@ export class SyncularRealtimeHost {
340
347
  return [];
341
348
  const utf8 = new TextDecoder();
342
349
  let end = bytes.indexOf(0x0a);
343
- const [partition, actorId, clientId] = JSON.parse(utf8.decode(bytes.subarray(0, end)));
350
+ const [partition, actorId, clientId, context] = JSON.parse(utf8.decode(bytes.subarray(0, end)));
344
351
  const presence = new Map();
345
352
  for (let at = end + 1; at < bytes.length; at = end + 1) {
346
353
  let length = 0;
@@ -353,7 +360,13 @@ export class SyncularRealtimeHost {
353
360
  end = bytes.indexOf(0x0a, at + length);
354
361
  presence.set(utf8.decode(bytes.subarray(at, at + length)), utf8.decode(bytes.subarray(at + length, end)));
355
362
  }
356
- return [{ ws, identity: { partition, actorId, clientId }, presence }];
363
+ const identity = {
364
+ partition,
365
+ actorId,
366
+ clientId,
367
+ ...(context !== undefined ? { context } : {}),
368
+ };
369
+ return [{ ws, identity, presence }];
357
370
  });
358
371
  if (sockets.length === 0)
359
372
  return;
@@ -538,6 +551,7 @@ export class SyncularRealtimeHost {
538
551
  partition: identity.partition,
539
552
  actorId: identity.actorId,
540
553
  clientId: identity.clientId,
554
+ ...(identity.context !== undefined ? { context: identity.context } : {}),
541
555
  send: (data) => sendOverSocket(ws, data),
542
556
  closeSocket: () => ws.close(1008, 'protocol violation (§8.7)'),
543
557
  // §8.6.1: presence survives a hibernation in the socket's attachment.
@@ -650,6 +664,8 @@ const REALTIME_ID_HEADER = {
650
664
  partition: 'x-syncular-partition',
651
665
  actorId: 'x-syncular-actor',
652
666
  clientId: 'x-syncular-client',
667
+ // URI-encoded: a header value carries no arbitrary UTF-8.
668
+ context: 'x-syncular-context',
653
669
  };
654
670
  const ADMIN_ACTIONS_HEADER = 'x-syncular-admin-actions';
655
671
  /** Address a Worker-authorized admin request to the DO (Worker side). */
@@ -663,14 +679,24 @@ export function adminRequestForDurableObject(request, routePath, target) {
663
679
  forwarded.headers.delete(ADMIN_ACTIONS_HEADER);
664
680
  return forwarded;
665
681
  }
682
+ /**
683
+ * Write the authenticated identity onto a forwarded request's headers (Worker
684
+ * side). The forwarded request copies the client's headers, so a context
685
+ * header the client sent is removed when authentication yielded none.
686
+ */
666
687
  export function writeRequestIdentityHeaders(headers, identity) {
667
688
  headers.set(REALTIME_ID_HEADER.partition, identity.partition);
668
689
  headers.set(REALTIME_ID_HEADER.actorId, identity.actorId);
690
+ if (identity.context === undefined) {
691
+ headers.delete(REALTIME_ID_HEADER.context);
692
+ }
693
+ else {
694
+ headers.set(REALTIME_ID_HEADER.context, encodeURIComponent(identity.context));
695
+ }
669
696
  }
670
697
  /** Write the resolved identity onto an upgrade request's headers (Worker side). */
671
698
  export function writeIdentityHeaders(headers, identity) {
672
- headers.set(REALTIME_ID_HEADER.partition, identity.partition);
673
- headers.set(REALTIME_ID_HEADER.actorId, identity.actorId);
699
+ writeRequestIdentityHeaders(headers, identity);
674
700
  headers.set(REALTIME_ID_HEADER.clientId, identity.clientId);
675
701
  }
676
702
  function readIdentityHeaders(request) {
@@ -684,7 +710,13 @@ function readIdentityHeaders(request) {
684
710
  clientId === '') {
685
711
  return undefined;
686
712
  }
687
- return { partition, actorId, clientId };
713
+ const context = request.headers.get(REALTIME_ID_HEADER.context);
714
+ return {
715
+ partition,
716
+ actorId,
717
+ clientId,
718
+ ...(context !== null ? { context: decodeURIComponent(context) } : {}),
719
+ };
688
720
  }
689
721
  function readRequestIdentityHeaders(request) {
690
722
  const partition = request.headers.get(REALTIME_ID_HEADER.partition);
@@ -695,5 +727,10 @@ function readRequestIdentityHeaders(request) {
695
727
  actorId === '') {
696
728
  return undefined;
697
729
  }
698
- return { partition, actorId };
730
+ const context = request.headers.get(REALTIME_ID_HEADER.context);
731
+ return {
732
+ partition,
733
+ actorId,
734
+ ...(context !== null ? { context: decodeURIComponent(context) } : {}),
735
+ };
699
736
  }
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@syncular/server-workers",
3
- "version": "0.73.0",
3
+ "version": "0.75.0",
4
4
  "description": "Cloudflare Workers adapter for the Syncular sync server",
5
5
  "license": "Apache-2.0",
6
6
  "author": "Benjamin Kniffler",
@@ -45,9 +45,9 @@
45
45
  "!dist/**/*.test.d.ts"
46
46
  ],
47
47
  "dependencies": {
48
- "@syncular/core": "0.73.0",
49
- "@syncular/server": "0.73.0",
50
- "@syncular/server-hono": "0.73.0"
48
+ "@syncular/core": "0.75.0",
49
+ "@syncular/server": "0.75.0",
50
+ "@syncular/server-hono": "0.75.0"
51
51
  },
52
52
  "devDependencies": {
53
53
  "@electric-sql/pglite": "^0.5.4",
package/src/index.ts CHANGED
@@ -376,7 +376,11 @@ function partitionRequestPath(request: Request): string | undefined {
376
376
  export function forwardSyncRequest(
377
377
  request: Request,
378
378
  namespace: DurableObjectNamespaceLike,
379
- identity: { readonly partition: string; readonly actorId: string },
379
+ identity: {
380
+ readonly partition: string;
381
+ readonly actorId: string;
382
+ readonly context?: string;
383
+ },
380
384
  path: string = SYNC_DO_REQUEST_PATH,
381
385
  ): Promise<Response> {
382
386
  const stub = namespace.get(namespace.idFromName(identity.partition));
@@ -69,7 +69,9 @@
69
69
  * is re-derived from storage, which is authoritative.
70
70
  *
71
71
  * The attachment is one `Uint8Array`, so its structured-clone size is its
72
- * byte length plus fixed framing: the identity as UTF-8 JSON and a newline,
72
+ * byte length plus fixed framing: the identity as UTF-8 JSON (`[partition,
73
+ * actorId, clientId]`, plus the authentication context as a fourth element
74
+ * when the upgrade had one) and a newline,
73
75
  * then per presence key a varint key length, the key's UTF-8 bytes, the
74
76
  * document's UTF-8 JSON and a newline (a JSON text holds no raw newline).
75
77
  * Each key costs at least 3 counted bytes (a non-empty key and `{}`) and at
@@ -251,7 +253,12 @@ function encodeAttachment(
251
253
  const utf8 = new TextEncoder();
252
254
  const bytes = [
253
255
  ...utf8.encode(
254
- JSON.stringify([identity.partition, identity.actorId, identity.clientId]),
256
+ JSON.stringify([
257
+ identity.partition,
258
+ identity.actorId,
259
+ identity.clientId,
260
+ ...(identity.context !== undefined ? [identity.context] : []),
261
+ ]),
255
262
  ),
256
263
  0x0a,
257
264
  ];
@@ -269,6 +276,8 @@ export interface RealtimeUpgradeIdentity {
269
276
  readonly partition: string;
270
277
  readonly actorId: string;
271
278
  readonly clientId: string;
279
+ /** The authentication context (§1.1) the connection resolves scopes under. */
280
+ readonly context?: string;
272
281
  }
273
282
 
274
283
  /** Internal control-request paths on the DO stub (never client-facing). */
@@ -485,6 +494,7 @@ export class SyncularRealtimeHost<
485
494
  contextFor: (identity: {
486
495
  readonly partition: string;
487
496
  readonly actorId: string;
497
+ readonly context?: string;
488
498
  }) => SyncRequestContext,
489
499
  ) => Promise<T>,
490
500
  ): Promise<T> {
@@ -546,9 +556,9 @@ export class SyncularRealtimeHost<
546
556
  if (!(bytes instanceof Uint8Array)) return [];
547
557
  const utf8 = new TextDecoder();
548
558
  let end = bytes.indexOf(0x0a);
549
- const [partition, actorId, clientId] = JSON.parse(
559
+ const [partition, actorId, clientId, context] = JSON.parse(
550
560
  utf8.decode(bytes.subarray(0, end)),
551
- ) as [string, string, string];
561
+ ) as [string, string, string, string?];
552
562
  const presence = new Map<string, string>();
553
563
  for (let at = end + 1; at < bytes.length; at = end + 1) {
554
564
  let length = 0;
@@ -563,7 +573,13 @@ export class SyncularRealtimeHost<
563
573
  utf8.decode(bytes.subarray(at + length, end)),
564
574
  );
565
575
  }
566
- return [{ ws, identity: { partition, actorId, clientId }, presence }];
576
+ const identity: RealtimeUpgradeIdentity = {
577
+ partition,
578
+ actorId,
579
+ clientId,
580
+ ...(context !== undefined ? { context } : {}),
581
+ };
582
+ return [{ ws, identity, presence }];
567
583
  });
568
584
  if (sockets.length === 0) return;
569
585
  const results = await this.#getHub().restore(
@@ -783,6 +799,7 @@ export class SyncularRealtimeHost<
783
799
  partition: identity.partition,
784
800
  actorId: identity.actorId,
785
801
  clientId: identity.clientId,
802
+ ...(identity.context !== undefined ? { context: identity.context } : {}),
786
803
  send: (data) => sendOverSocket(ws, data),
787
804
  closeSocket: () => ws.close(1008, 'protocol violation (§8.7)'),
788
805
  // §8.6.1: presence survives a hibernation in the socket's attachment.
@@ -913,6 +930,8 @@ const REALTIME_ID_HEADER = {
913
930
  partition: 'x-syncular-partition',
914
931
  actorId: 'x-syncular-actor',
915
932
  clientId: 'x-syncular-client',
933
+ // URI-encoded: a header value carries no arbitrary UTF-8.
934
+ context: 'x-syncular-context',
916
935
  } as const;
917
936
 
918
937
  const ADMIN_ACTIONS_HEADER = 'x-syncular-admin-actions';
@@ -934,12 +953,29 @@ export function adminRequestForDurableObject(
934
953
  return forwarded;
935
954
  }
936
955
 
956
+ /**
957
+ * Write the authenticated identity onto a forwarded request's headers (Worker
958
+ * side). The forwarded request copies the client's headers, so a context
959
+ * header the client sent is removed when authentication yielded none.
960
+ */
937
961
  export function writeRequestIdentityHeaders(
938
962
  headers: Headers,
939
- identity: { readonly partition: string; readonly actorId: string },
963
+ identity: {
964
+ readonly partition: string;
965
+ readonly actorId: string;
966
+ readonly context?: string;
967
+ },
940
968
  ): void {
941
969
  headers.set(REALTIME_ID_HEADER.partition, identity.partition);
942
970
  headers.set(REALTIME_ID_HEADER.actorId, identity.actorId);
971
+ if (identity.context === undefined) {
972
+ headers.delete(REALTIME_ID_HEADER.context);
973
+ } else {
974
+ headers.set(
975
+ REALTIME_ID_HEADER.context,
976
+ encodeURIComponent(identity.context),
977
+ );
978
+ }
943
979
  }
944
980
 
945
981
  /** Write the resolved identity onto an upgrade request's headers (Worker side). */
@@ -947,8 +983,7 @@ export function writeIdentityHeaders(
947
983
  headers: Headers,
948
984
  identity: RealtimeUpgradeIdentity,
949
985
  ): void {
950
- headers.set(REALTIME_ID_HEADER.partition, identity.partition);
951
- headers.set(REALTIME_ID_HEADER.actorId, identity.actorId);
986
+ writeRequestIdentityHeaders(headers, identity);
952
987
  headers.set(REALTIME_ID_HEADER.clientId, identity.clientId);
953
988
  }
954
989
 
@@ -967,12 +1002,22 @@ function readIdentityHeaders(
967
1002
  ) {
968
1003
  return undefined;
969
1004
  }
970
- return { partition, actorId, clientId };
1005
+ const context = request.headers.get(REALTIME_ID_HEADER.context);
1006
+ return {
1007
+ partition,
1008
+ actorId,
1009
+ clientId,
1010
+ ...(context !== null ? { context: decodeURIComponent(context) } : {}),
1011
+ };
971
1012
  }
972
1013
 
973
- function readRequestIdentityHeaders(
974
- request: Request,
975
- ): { readonly partition: string; readonly actorId: string } | undefined {
1014
+ function readRequestIdentityHeaders(request: Request):
1015
+ | {
1016
+ readonly partition: string;
1017
+ readonly actorId: string;
1018
+ readonly context?: string;
1019
+ }
1020
+ | undefined {
976
1021
  const partition = request.headers.get(REALTIME_ID_HEADER.partition);
977
1022
  const actorId = request.headers.get(REALTIME_ID_HEADER.actorId);
978
1023
  if (
@@ -983,7 +1028,12 @@ function readRequestIdentityHeaders(
983
1028
  ) {
984
1029
  return undefined;
985
1030
  }
986
- return { partition, actorId };
1031
+ const context = request.headers.get(REALTIME_ID_HEADER.context);
1032
+ return {
1033
+ partition,
1034
+ actorId,
1035
+ ...(context !== null ? { context: decodeURIComponent(context) } : {}),
1036
+ };
987
1037
  }
988
1038
 
989
1039
  // -- Minimal ambient types (structural; not the real workers-types) ---------