@open-e2ee/signal-protocol-sdk 13.4.0 → 13.5.1

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 (171) hide show
  1. package/CHANGELOG.md +423 -0
  2. package/README.md +4 -8
  3. package/SECURITY.md +2 -2
  4. package/TROUBLESHOOTING.md +55 -27
  5. package/dist/client/binary-send.d.ts +28 -0
  6. package/dist/client/binary-send.d.ts.map +1 -0
  7. package/dist/client/binary-send.js +26 -0
  8. package/dist/client/binary-send.js.map +1 -0
  9. package/dist/client/client.d.ts +46 -6
  10. package/dist/client/client.d.ts.map +1 -1
  11. package/dist/client/client.js +181 -66
  12. package/dist/client/client.js.map +1 -1
  13. package/dist/client/content-adapter.d.ts +18 -0
  14. package/dist/client/content-adapter.d.ts.map +1 -1
  15. package/dist/client/content-adapter.js.map +1 -1
  16. package/dist/client/device-set-reconciliation.d.ts +23 -8
  17. package/dist/client/device-set-reconciliation.d.ts.map +1 -1
  18. package/dist/client/device-set-reconciliation.js +25 -11
  19. package/dist/client/device-set-reconciliation.js.map +1 -1
  20. package/dist/client/event-hooks.d.ts +88 -8
  21. package/dist/client/event-hooks.d.ts.map +1 -1
  22. package/dist/client/event-hooks.js +1 -0
  23. package/dist/client/event-hooks.js.map +1 -1
  24. package/dist/client/group-outbox.d.ts +45 -10
  25. package/dist/client/group-outbox.d.ts.map +1 -1
  26. package/dist/client/group-outbox.js +246 -154
  27. package/dist/client/group-outbox.js.map +1 -1
  28. package/dist/client/group-receive-authorization.d.ts +10 -1
  29. package/dist/client/group-receive-authorization.d.ts.map +1 -1
  30. package/dist/client/group-receive-authorization.js.map +1 -1
  31. package/dist/client/hosted-anonymous-delivery.d.ts +18 -1
  32. package/dist/client/hosted-anonymous-delivery.d.ts.map +1 -1
  33. package/dist/client/hosted-anonymous-delivery.js +84 -12
  34. package/dist/client/hosted-anonymous-delivery.js.map +1 -1
  35. package/dist/client/hosted-connection.js +1 -1
  36. package/dist/client/hosted-connection.js.map +1 -1
  37. package/dist/client/hosted-group-authority.d.ts +6 -2
  38. package/dist/client/hosted-group-authority.d.ts.map +1 -1
  39. package/dist/client/hosted-group-authority.js +11 -7
  40. package/dist/client/hosted-group-authority.js.map +1 -1
  41. package/dist/client/hosted-groups.d.ts +5 -1
  42. package/dist/client/hosted-groups.d.ts.map +1 -1
  43. package/dist/client/hosted-groups.js +8 -4
  44. package/dist/client/hosted-groups.js.map +1 -1
  45. package/dist/client/hosted-http-error.d.ts +5 -1
  46. package/dist/client/hosted-http-error.d.ts.map +1 -1
  47. package/dist/client/hosted-http-error.js +5 -1
  48. package/dist/client/hosted-http-error.js.map +1 -1
  49. package/dist/client/hosted-mailbox-subscription.d.ts +2 -0
  50. package/dist/client/hosted-mailbox-subscription.d.ts.map +1 -1
  51. package/dist/client/hosted-mailbox-subscription.js +5 -5
  52. package/dist/client/hosted-mailbox-subscription.js.map +1 -1
  53. package/dist/client/hosted-transport.d.ts +11 -1
  54. package/dist/client/hosted-transport.d.ts.map +1 -1
  55. package/dist/client/hosted-transport.js +75 -30
  56. package/dist/client/hosted-transport.js.map +1 -1
  57. package/dist/client/hosted.d.ts.map +1 -1
  58. package/dist/client/hosted.js +1 -1
  59. package/dist/client/hosted.js.map +1 -1
  60. package/dist/client/index.d.ts +1 -1
  61. package/dist/client/index.d.ts.map +1 -1
  62. package/dist/client/index.js.map +1 -1
  63. package/dist/client/receive-queue.d.ts +5 -2
  64. package/dist/client/receive-queue.d.ts.map +1 -1
  65. package/dist/client/receive-queue.js +55 -18
  66. package/dist/client/receive-queue.js.map +1 -1
  67. package/dist/client/relay-acceptance.d.ts +49 -6
  68. package/dist/client/relay-acceptance.d.ts.map +1 -1
  69. package/dist/client/relay-acceptance.js +49 -3
  70. package/dist/client/relay-acceptance.js.map +1 -1
  71. package/dist/client/relay-protocol.d.ts +37 -7
  72. package/dist/client/relay-protocol.d.ts.map +1 -1
  73. package/dist/client/relay-protocol.js +53 -10
  74. package/dist/client/relay-protocol.js.map +1 -1
  75. package/dist/client/retry-family.d.ts +3 -3
  76. package/dist/client/retry-family.js +1 -1
  77. package/dist/client/retry-family.js.map +1 -1
  78. package/dist/client/retry-request-envelope.d.ts +18 -8
  79. package/dist/client/retry-request-envelope.d.ts.map +1 -1
  80. package/dist/client/retry-request-envelope.js +57 -29
  81. package/dist/client/retry-request-envelope.js.map +1 -1
  82. package/dist/client/retry-request-lifecycle.d.ts +24 -11
  83. package/dist/client/retry-request-lifecycle.d.ts.map +1 -1
  84. package/dist/client/retry-request-lifecycle.js +46 -20
  85. package/dist/client/retry-request-lifecycle.js.map +1 -1
  86. package/dist/client/retry-terminal-recovery.d.ts +11 -8
  87. package/dist/client/retry-terminal-recovery.d.ts.map +1 -1
  88. package/dist/client/retry-terminal-recovery.js +18 -12
  89. package/dist/client/retry-terminal-recovery.js.map +1 -1
  90. package/dist/client/retry.d.ts +8 -7
  91. package/dist/client/retry.d.ts.map +1 -1
  92. package/dist/client/retry.js +30 -22
  93. package/dist/client/retry.js.map +1 -1
  94. package/dist/client/send-deadline.d.ts +308 -0
  95. package/dist/client/send-deadline.d.ts.map +1 -0
  96. package/dist/client/send-deadline.js +914 -0
  97. package/dist/client/send-deadline.js.map +1 -0
  98. package/dist/client/send-intent-driver.d.ts +116 -0
  99. package/dist/client/send-intent-driver.d.ts.map +1 -0
  100. package/dist/client/send-intent-driver.js +373 -0
  101. package/dist/client/send-intent-driver.js.map +1 -0
  102. package/dist/client/signal-service-cipher.d.ts +257 -27
  103. package/dist/client/signal-service-cipher.d.ts.map +1 -1
  104. package/dist/client/signal-service-cipher.js +1274 -283
  105. package/dist/client/signal-service-cipher.js.map +1 -1
  106. package/dist/client/types.d.ts +48 -5
  107. package/dist/client/types.d.ts.map +1 -1
  108. package/dist/client/types.js.map +1 -1
  109. package/dist/index.d.ts +1 -1
  110. package/dist/index.d.ts.map +1 -1
  111. package/dist/index.js.map +1 -1
  112. package/dist/local/store/conformance/cases/metadata.d.ts +3 -2
  113. package/dist/local/store/conformance/cases/metadata.d.ts.map +1 -1
  114. package/dist/local/store/conformance/cases/metadata.js +153 -2
  115. package/dist/local/store/conformance/cases/metadata.js.map +1 -1
  116. package/dist/local/store/key-value/adapter.d.ts +2 -1
  117. package/dist/local/store/key-value/adapter.d.ts.map +1 -1
  118. package/dist/local/store/key-value/adapter.js +9 -0
  119. package/dist/local/store/key-value/adapter.js.map +1 -1
  120. package/dist/local/store/memory/adapter.d.ts +2 -1
  121. package/dist/local/store/memory/adapter.d.ts.map +1 -1
  122. package/dist/local/store/memory/adapter.js +4 -0
  123. package/dist/local/store/memory/adapter.js.map +1 -1
  124. package/dist/local/store/metadata-keys.d.ts +13 -0
  125. package/dist/local/store/metadata-keys.d.ts.map +1 -0
  126. package/dist/local/store/metadata-keys.js +20 -0
  127. package/dist/local/store/metadata-keys.js.map +1 -0
  128. package/dist/local/store/receive-work.d.ts.map +1 -1
  129. package/dist/local/store/receive-work.js +12 -1
  130. package/dist/local/store/receive-work.js.map +1 -1
  131. package/dist/local/store/reliability.d.ts +482 -33
  132. package/dist/local/store/reliability.d.ts.map +1 -1
  133. package/dist/local/store/reliability.js +690 -48
  134. package/dist/local/store/reliability.js.map +1 -1
  135. package/dist/local/store/sqlite/key-storage/index.d.ts +2 -1
  136. package/dist/local/store/sqlite/key-storage/index.d.ts.map +1 -1
  137. package/dist/local/store/sqlite/key-storage/index.js +3 -0
  138. package/dist/local/store/sqlite/key-storage/index.js.map +1 -1
  139. package/dist/local/store/sqlite/key-storage/metadata.d.ts +9 -0
  140. package/dist/local/store/sqlite/key-storage/metadata.d.ts.map +1 -1
  141. package/dist/local/store/sqlite/key-storage/metadata.js +12 -0
  142. package/dist/local/store/sqlite/key-storage/metadata.js.map +1 -1
  143. package/dist/local/store/sqlite/store.d.ts +2 -1
  144. package/dist/local/store/sqlite/store.d.ts.map +1 -1
  145. package/dist/local/store/sqlite/store.js +3 -0
  146. package/dist/local/store/sqlite/store.js.map +1 -1
  147. package/dist/local/store/web/adapter.d.ts +8 -1
  148. package/dist/local/store/web/adapter.d.ts.map +1 -1
  149. package/dist/local/store/web/adapter.js +18 -0
  150. package/dist/local/store/web/adapter.js.map +1 -1
  151. package/dist/remote/relay/request-admission.d.ts +49 -0
  152. package/dist/remote/relay/request-admission.d.ts.map +1 -0
  153. package/dist/remote/relay/request-admission.js +74 -0
  154. package/dist/remote/relay/request-admission.js.map +1 -0
  155. package/dist/types/api.d.ts +77 -0
  156. package/dist/types/api.d.ts.map +1 -1
  157. package/dist/types/errors.d.ts +144 -1
  158. package/dist/types/errors.d.ts.map +1 -1
  159. package/dist/types/errors.js +146 -1
  160. package/dist/types/errors.js.map +1 -1
  161. package/docs/ASSURANCE.md +31 -15
  162. package/docs/DEVIATIONS.md +34 -4
  163. package/docs/ERROR_HANDLING.md +134 -7
  164. package/docs/GETTING_STARTED.md +30 -23
  165. package/docs/PROTOCOL_POLICY.md +31 -20
  166. package/groups/README.md +1 -1
  167. package/hooks/README.md +6 -3
  168. package/local/store/react-native/README.md +9 -10
  169. package/local/store/web/README.md +1 -1
  170. package/package.json +1 -1
  171. package/safety/README.md +48 -11
@@ -1,4 +1,5 @@
1
1
  import { createKeyedLocks, withKeyedLock } from '../../utils/keyed-lock.js';
2
+ import { originLockScope, withOriginLock } from '../../utils/origin-lock.js';
2
3
  const OUTBOX_PREFIX = 'reliability:exact-ciphertext-outbox:v2';
3
4
  const INCOMING_PREFIX = 'reliability:processed-envelopes:v2';
4
5
  const RETRY_REQUESTED_PREFIX = 'reliability:retry-requested:v2';
@@ -6,8 +7,14 @@ const RETRY_RESEND_PREFIX = 'reliability:retry-resend:v1';
6
7
  const RETRY_FAMILY_PREFIX = 'reliability:retry-family:v1';
7
8
  const SENT_TIMESTAMP_PREFIX = 'reliability:sent-timestamps:v1';
8
9
  const DELIVERY_STATUS_PREFIX = 'reliability:delivery-status:v1';
10
+ const RECEIVED_TIMESTAMP_PREFIX = 'reliability:received-timestamps:v1';
9
11
  const DAY_MS = 24 * 60 * 60 * 1_000;
10
12
  export const RELIABILITY_RECORD_TTL_MS = 30 * DAY_MS;
13
+ /**
14
+ * The posting window of an outgoing intent. No request of the intent starts
15
+ * at or after `outgoingMessageDeadlineAt`.
16
+ */
17
+ export const OUTGOING_POSTING_WINDOW_MS = DAY_MS;
11
18
  /**
12
19
  * The lifetime of the retry-request and retry-family records of the
13
20
  * requester, and of a fulfilled processed-envelope record. Two bounds set
@@ -25,8 +32,15 @@ export const RETRY_REQUESTER_RECORD_TTL_MS = 2 * RELIABILITY_RECORD_TTL_MS;
25
32
  * at this time ends as `expired-content`.
26
33
  */
27
34
  export const RETRY_REQUEST_DEADLINE_MS = 14 * DAY_MS;
35
+ /**
36
+ * The posting window of a retry request: 24 hours from the first failure,
37
+ * `receivedAt`. No post of the request starts at or after
38
+ * `retryRequestPostingDeadlineAt`.
39
+ */
40
+ export const RETRY_REQUEST_POSTING_WINDOW_MS = DAY_MS;
28
41
  const mutationTails = new WeakMap();
29
42
  const outgoingIntentLocks = createKeyedLocks();
43
+ const outgoingIntentEndReports = new WeakMap();
30
44
  const incomingEnvelopeLocks = createKeyedLocks();
31
45
  const LEDGER_PREFIXES = {
32
46
  outbox: OUTBOX_PREFIX,
@@ -36,6 +50,7 @@ const LEDGER_PREFIXES = {
36
50
  'retry-resend': RETRY_RESEND_PREFIX,
37
51
  'sent-timestamp': SENT_TIMESTAMP_PREFIX,
38
52
  'delivery-status': DELIVERY_STATUS_PREFIX,
53
+ 'received-timestamp': RECEIVED_TIMESTAMP_PREFIX,
39
54
  };
40
55
  const LEDGER_TTL_MS = {
41
56
  outbox: RELIABILITY_RECORD_TTL_MS,
@@ -45,6 +60,10 @@ const LEDGER_TTL_MS = {
45
60
  'retry-resend': RELIABILITY_RECORD_TTL_MS,
46
61
  'sent-timestamp': RELIABILITY_RECORD_TTL_MS,
47
62
  'delivery-status': RELIABILITY_RECORD_TTL_MS,
63
+ // Two bounds: the last manual resend of a sender posts at most
64
+ // RELIABILITY_RECORD_TTL_MS after its intent, and the Relay keeps a post
65
+ // for at most RELIABILITY_RECORD_TTL_MS.
66
+ 'received-timestamp': RETRY_REQUESTER_RECORD_TTL_MS,
48
67
  };
49
68
  function prefix(kind) {
50
69
  return LEDGER_PREFIXES[kind];
@@ -76,8 +95,41 @@ async function serializeMutation(store, operation) {
76
95
  mutationTails.set(key, current.then(() => undefined, () => undefined));
77
96
  return current;
78
97
  }
79
- export async function withOutgoingMessageIntentLock(store, clientMessageId, operation) {
80
- return withKeyedLock(outgoingIntentLocks, store, clientMessageId, operation);
98
+ /** The end report of the send call that holds the lock of this intent. */
99
+ function outgoingIntentEndReport(store, clientMessageId) {
100
+ return outgoingIntentEndReports.get(store)?.get(clientMessageId);
101
+ }
102
+ /**
103
+ * Run `operation` under the lock of one outgoing intent. When
104
+ * `navigator.locks.request` exists and the store sets `storeIdentity`, the
105
+ * lock is the Web Lock `open-e2ee:outbox:<store identity>:<clientMessageId>`,
106
+ * so the tabs, workers and threads of one origin that share the store share
107
+ * it. Otherwise it is an in-process lock keyed by the store object. The lock
108
+ * is not reentrant. With `report`, an end write or a completion write of the
109
+ * intent during `operation` records the end in it.
110
+ */
111
+ export async function withOutgoingMessageIntentLock(store, clientMessageId, operation, report) {
112
+ const reported = report
113
+ ? async () => {
114
+ let reports = outgoingIntentEndReports.get(store);
115
+ if (!reports) {
116
+ reports = new Map();
117
+ outgoingIntentEndReports.set(store, reports);
118
+ }
119
+ reports.set(clientMessageId, report);
120
+ try {
121
+ return await operation();
122
+ }
123
+ finally {
124
+ reports.delete(clientMessageId);
125
+ }
126
+ }
127
+ : operation;
128
+ const scope = originLockScope(store);
129
+ if (scope !== null) {
130
+ return withOriginLock(`open-e2ee:outbox:${scope}:${clientMessageId}`, reported);
131
+ }
132
+ return withKeyedLock(outgoingIntentLocks, store, clientMessageId, reported);
81
133
  }
82
134
  export async function withProcessedEnvelopeLock(store, envelopeId, operation) {
83
135
  return withKeyedLock(incomingEnvelopeLocks, store, envelopeId, operation);
@@ -85,18 +137,47 @@ export async function withProcessedEnvelopeLock(store, envelopeId, operation) {
85
137
  async function pruneExpiredBuckets(store, kind, now) {
86
138
  const days = parseJson(await store.getMetadata(manifestKey(kind)), []);
87
139
  const firstRetainedDay = dayFor(now - LEDGER_TTL_MS[kind]);
88
- const retained = [];
140
+ const manifest = new Set(days);
89
141
  for (const day of days) {
90
- if (day >= firstRetainedDay) {
91
- retained.push(day);
142
+ if (day >= firstRetainedDay)
92
143
  continue;
93
- }
94
144
  const ids = parseJson(await store.getMetadata(bucketKey(kind, day)), []);
95
- for (const id of ids)
145
+ for (const id of ids) {
146
+ if (kind === 'outbox' && (await keepOutgoingIntent(store, id, now, manifest)))
147
+ continue;
96
148
  await store.deleteMetadata(recordKey(kind, id));
149
+ }
97
150
  await store.deleteMetadata(bucketKey(kind, day));
98
151
  }
99
- return retained;
152
+ return [...manifest].filter((day) => day >= firstRetainedDay).sort((a, b) => a - b);
153
+ }
154
+ /**
155
+ * Keep an intent of an expired outbox bucket that a manual resend retains,
156
+ * and index it under the day of `outgoingIntentRetainedFrom`. The bucket and
157
+ * the manifest are written before the expired bucket is deleted, so a stop
158
+ * leaves the intent in a bucket.
159
+ *
160
+ * @returns True when the intent is kept.
161
+ */
162
+ async function keepOutgoingIntent(store, clientMessageId, now, manifest) {
163
+ const record = parseJson(await store.getMetadata(recordKey('outbox', clientMessageId)), null);
164
+ if (!record)
165
+ return false;
166
+ const retainedFrom = outgoingIntentRetainedFrom(record);
167
+ if (retainedFrom < now - RELIABILITY_RECORD_TTL_MS)
168
+ return false;
169
+ const day = dayFor(retainedFrom);
170
+ const dayKey = bucketKey('outbox', day);
171
+ const ids = parseJson(await store.getMetadata(dayKey), []);
172
+ if (!ids.includes(clientMessageId)) {
173
+ ids.push(clientMessageId);
174
+ await store.setMetadata(dayKey, JSON.stringify(ids));
175
+ }
176
+ if (!manifest.has(day)) {
177
+ manifest.add(day);
178
+ await store.setMetadata(manifestKey('outbox'), JSON.stringify([...manifest].sort((a, b) => a - b)));
179
+ }
180
+ return true;
100
181
  }
101
182
  async function indexRecord(store, kind, id, timestamp, retainedDays) {
102
183
  const day = dayFor(timestamp);
@@ -152,6 +233,11 @@ function sameIntent(a, b) {
152
233
  * appended to its list. A new message for a device that still has a message
153
234
  * in the same list must be equal to it, and is not appended again. The same
154
235
  * write replaces or removes the shared body when the change names one.
236
+ *
237
+ * A device whose pre-message or device message the change appends after it
238
+ * removed that device gets `repaired` and `repairedFor` on its progress
239
+ * entry. The write creates the entry when none exists. A device that the
240
+ * change appends without a removal gets no mark.
155
241
  */
156
242
  export async function reconcileOutgoingGroupDeviceSet(store, clientMessageId, change) {
157
243
  return serializeMutation(store, async () => {
@@ -170,6 +256,12 @@ export async function reconcileOutgoingGroupDeviceSet(store, clientMessageId, ch
170
256
  else
171
257
  delete existing.preMessages;
172
258
  applyGroupSharedMessage(existing, change.groupSharedMessage);
259
+ for (const message of [...change.preMessages, ...change.deviceMessages]) {
260
+ if (removed.has(outgoingMessageDeviceKey(message))) {
261
+ markOutgoingDestinationRepaired(existing, 'recipient', message, 'stale-device', true);
262
+ }
263
+ }
264
+ stampOutgoingDeadline(existing);
173
265
  await store.setMetadata(key, JSON.stringify(existing));
174
266
  return cloneReliabilityValue(existing);
175
267
  });
@@ -188,8 +280,13 @@ function applyGroupSharedMessage(intent, groupSharedMessage) {
188
280
  /**
189
281
  * Commit the repair of a declared send phase and its restart count in one
190
282
  * write. Each removed device first loses all of its messages. Then each new
191
- * message is appended to its list. A completed intent takes a repair only of
192
- * its pending sync phase, and a terminal intent takes none.
283
+ * message is appended to its list, and the progress entry of its device
284
+ * gets `repairedFor`. The entry of a device that the repair also removed
285
+ * gets `repaired`, because the repair replaced its message. The entry of an
286
+ * added device does not. A completed intent takes a repair only of its
287
+ * pending sync phase, and a terminal intent takes none.
288
+ *
289
+ * @returns The stored intent, with the progress entry of each appended device
193
290
  */
194
291
  export async function repairOutgoingDeviceSet(store, clientMessageId, repair) {
195
292
  return serializeMutation(store, async () => {
@@ -214,6 +311,13 @@ export async function repairOutgoingDeviceSet(store, clientMessageId, repair) {
214
311
  existing.preMessages = preMessages;
215
312
  else
216
313
  delete existing.preMessages;
314
+ const replaced = (message) => removed.has(outgoingMessageDeviceKey(message));
315
+ for (const message of [...(repair.preMessages ?? []), ...(repair.deviceMessages ?? [])]) {
316
+ markOutgoingDestinationRepaired(existing, 'recipient', message, 'device-set', replaced(message));
317
+ }
318
+ for (const message of repair.syncMessages ?? []) {
319
+ markOutgoingDestinationRepaired(existing, 'sync', message, 'device-set', replaced(message));
320
+ }
217
321
  applyGroupSharedMessage(existing, repair.groupSharedMessage);
218
322
  existing.deviceSetRestarts = { ...existing.deviceSetRestarts, [repair.phase]: repair.restarts };
219
323
  const bundleMissing = (repair.bundleMissing ?? []).map((device) => ({
@@ -230,16 +334,24 @@ export async function repairOutgoingDeviceSet(store, clientMessageId, repair) {
230
334
  ...(bundleMissing.length > 0 && { [repair.phase]: bundleMissing }),
231
335
  };
232
336
  }
337
+ stampOutgoingDeadline(existing);
233
338
  await store.setMetadata(key, JSON.stringify(existing));
234
339
  return cloneReliabilityValue(existing);
235
340
  });
236
341
  }
237
342
  /**
238
343
  * Record that a phase of a declared send ended without reconciliation. The
239
- * restart counts stay. The SDK does not post the phase again until the
240
- * application calls `send()` with the same `clientMessageId`.
344
+ * restart counts stay. A recipient-phase end stores the send outcome. A
345
+ * later `send()` with the same `clientMessageId` then throws the stored-end
346
+ * class and posts nothing. A sync-phase end keeps the result, and a later
347
+ * `send()` posts the sync phase again. `resendMessage` posts a new
348
+ * operation.
349
+ *
350
+ * `end` is the class of the recipient phase at the end: its outcome and the
351
+ * progress of each recipient destination, which replaces the stored entry
352
+ * under its key. Only a recipient-phase end of an open intent writes it.
241
353
  */
242
- export async function markOutgoingDeviceSetUnresolved(store, clientMessageId, unresolved) {
354
+ export async function markOutgoingDeviceSetUnresolved(store, clientMessageId, unresolved, end) {
243
355
  return serializeMutation(store, async () => {
244
356
  const key = recordKey('outbox', clientMessageId);
245
357
  const existing = parseJson(await store.getMetadata(key), null);
@@ -247,26 +359,26 @@ export async function markOutgoingDeviceSetUnresolved(store, clientMessageId, un
247
359
  throw new Error('Cannot end the device set of a missing or completed outbox intent');
248
360
  }
249
361
  existing.deviceSetUnresolved = cloneReliabilityValue(unresolved);
250
- await store.setMetadata(key, JSON.stringify(existing));
251
- return cloneReliabilityValue(existing);
252
- });
253
- }
254
- /**
255
- * Start a new run of a terminal declared send at 0 restarts: remove the
256
- * terminal record and the restart counts in one write. An intent that is not
257
- * terminal keeps its counts.
258
- */
259
- export async function restartOutgoingDeviceSet(store, clientMessageId) {
260
- return serializeMutation(store, async () => {
261
- const key = recordKey('outbox', clientMessageId);
262
- const existing = parseJson(await store.getMetadata(key), null);
263
- if (!existing)
264
- throw new Error('Cannot restart a missing outbox intent');
265
- if (existing.deviceSetUnresolved) {
266
- delete existing.deviceSetUnresolved;
267
- delete existing.deviceSetRestarts;
268
- await store.setMetadata(key, JSON.stringify(existing));
362
+ // A sync-phase end keeps the result of the recipient phase, so it
363
+ // writes no outcome beside it.
364
+ const ends = unresolved.phase === 'recipient' &&
365
+ end !== undefined &&
366
+ !existing.result &&
367
+ existing.outcome === undefined;
368
+ const report = ends ? outgoingIntentEndReport(store, clientMessageId) : undefined;
369
+ if (ends) {
370
+ if (report?.driven && !existing.internal)
371
+ existing.outcomeReportPending = true;
372
+ existing.outcome = end.outcome;
373
+ existing.destinationProgress = {
374
+ ...existing.destinationProgress,
375
+ ...cloneReliabilityValue(end.destinationProgress),
376
+ };
269
377
  }
378
+ stampOutgoingDeadline(existing);
379
+ await store.setMetadata(key, JSON.stringify(existing));
380
+ if (report)
381
+ report.ended = cloneReliabilityValue(existing);
270
382
  return cloneReliabilityValue(existing);
271
383
  });
272
384
  }
@@ -303,6 +415,290 @@ export function outgoingMessageIntentResult(intent) {
303
415
  function outgoingDeviceKey({ userId, deviceId }) {
304
416
  return `${userId}\u0000${String(deviceId)}`;
305
417
  }
418
+ /**
419
+ * The posting deadline of an intent: the stored `deadlineAt`, else the
420
+ * earlier of `createdAt` and `clientTimestamp`, plus
421
+ * `OUTGOING_POSTING_WINDOW_MS`. An intent that an earlier SDK stored has no
422
+ * `deadlineAt`, and it gets the same value from its stored times.
423
+ */
424
+ export function outgoingMessageDeadlineAt(intent) {
425
+ return (intent.deadlineAt ??
426
+ Math.min(intent.createdAt, intent.clientTimestamp) + OUTGOING_POSTING_WINDOW_MS);
427
+ }
428
+ /** Store the posting deadline on an open intent that has none. */
429
+ function stampOutgoingDeadline(existing) {
430
+ if (existing.result || existing.deadlineAt !== undefined)
431
+ return;
432
+ existing.deadlineAt = outgoingMessageDeadlineAt(existing);
433
+ }
434
+ /** The `destinationProgress` key of one device of one post. */
435
+ export function outgoingDestinationProgressKey(postMessageId, device) {
436
+ return `${postMessageId}\u0000${outgoingDeviceKey(device)}`;
437
+ }
438
+ /**
439
+ * The stored progress entry under this key, or a new `pending` entry with no
440
+ * request. A new entry of an intent without `progressFromStart` starts
441
+ * uncertain, because an earlier SDK can have posted the device.
442
+ */
443
+ function outgoingDestinationProgressEntry(existing, key, destination) {
444
+ const progress = (existing.destinationProgress ??= {});
445
+ const entry = (progress[key] ??= {
446
+ phase: destination.phase,
447
+ userId: destination.userId,
448
+ deviceId: destination.deviceId,
449
+ postMessageId: destination.postMessageId,
450
+ state: 'pending',
451
+ requests: 0,
452
+ ...(!existing.progressFromStart && { uncertain: true }),
453
+ });
454
+ entry.postMessageId = destination.postMessageId;
455
+ return entry;
456
+ }
457
+ /**
458
+ * Mark the progress entry of a device that a repair gave a new message,
459
+ * with the recovery that the repair ran and the ID of the new message. When
460
+ * `replaced` is true, the repair replaced the message of the device, and the
461
+ * entry also gets `repaired`. An earlier `repaired` mark stays.
462
+ */
463
+ function markOutgoingDestinationRepaired(existing, phase, message, recovery, replaced) {
464
+ const device = { userId: message.recipientUserId, deviceId: message.recipientDeviceId };
465
+ const postMessageId = message.clientMessageId ?? existing.clientMessageId;
466
+ const entry = outgoingDestinationProgressEntry(existing, outgoingDestinationProgressKey(postMessageId, device), { phase, ...device, postMessageId });
467
+ if (replaced)
468
+ entry.repaired = true;
469
+ entry.repairedFor = { recovery, postMessageId };
470
+ }
471
+ /**
472
+ * True when a refusal of `entry` refuses its repair: the refused post is
473
+ * the repaired message, and the kind of the refusal is the one that the
474
+ * recovery of the repair answers. A stale-device repair answers
475
+ * `STALE_DEVICE` and `device-rejection`, and a device-set repair answers
476
+ * `device-set`. An entry with `repaired` and no stored recovery counts each
477
+ * refusal. An entry with a stored recovery and no `repaired` mark (an added
478
+ * device) reads the same rule.
479
+ */
480
+ function refusesRepair(entry, postMessageId, refusalCode) {
481
+ const repair = entry.repairedFor;
482
+ if (!repair)
483
+ return entry.repaired === true;
484
+ if (repair.postMessageId !== postMessageId)
485
+ return false;
486
+ return repair.recovery === 'device-set'
487
+ ? refusalCode === 'device-set'
488
+ : refusalCode === 'STALE_DEVICE' || refusalCode === 'device-rejection';
489
+ }
490
+ /**
491
+ * Merge one request or one answer into a progress entry, by the rules of
492
+ * `recordOutgoingDestinationProgress`.
493
+ */
494
+ function applyDestinationUpdate(entry, update) {
495
+ if ('request' in update) {
496
+ if (entry.state === 'posted')
497
+ entry.uncertain = true;
498
+ if (entry.state !== 'accepted') {
499
+ entry.state = 'posted';
500
+ delete entry.refusalCode;
501
+ }
502
+ entry.requests += 1;
503
+ return;
504
+ }
505
+ if (entry.state === 'accepted')
506
+ return;
507
+ entry.state = update.answer;
508
+ if (update.answer === 'unknown')
509
+ entry.uncertain = true;
510
+ if (update.answer !== 'refused')
511
+ delete entry.refusalCode;
512
+ if (update.answer === 'refused') {
513
+ if (update.refusalCode === undefined)
514
+ delete entry.refusalCode;
515
+ else
516
+ entry.refusalCode = update.refusalCode;
517
+ if (update.repairSpent || refusesRepair(entry, update.postMessageId, update.refusalCode)) {
518
+ entry.repairSpent = true;
519
+ }
520
+ }
521
+ if (update.answer === 'accepted') {
522
+ if (update.messageId !== undefined)
523
+ entry.messageId = update.messageId;
524
+ if (update.enqueuedAt !== undefined)
525
+ entry.enqueuedAt = update.enqueuedAt;
526
+ if (update.expiresAt !== undefined)
527
+ entry.expiresAt = update.expiresAt;
528
+ if (update.duplicate)
529
+ entry.duplicate = true;
530
+ }
531
+ }
532
+ /**
533
+ * Record one request or one answer of one destination of an open intent,
534
+ * and merge it into the entry under `key`.
535
+ *
536
+ * - Before each request, the entry becomes `posted` and its `requests` count
537
+ * grows by one. When the entry is already `posted`, an earlier request
538
+ * has no answer, so the entry becomes uncertain.
539
+ * - After an answer, the entry takes the class of the answer. An uncertain
540
+ * answer sets `uncertain`. A refusal stores its code. A refusal that
541
+ * refuses the repair of the entry (`refusesRepair`) stores `repairSpent`.
542
+ * An `accepted` entry stays accepted.
543
+ * - The refusal code belongs to the last answer, so a later request or a
544
+ * later answer that is not a refusal clears it. `repairSpent` stays: the
545
+ * refusal spent the repair, and a later answer does not give it back.
546
+ *
547
+ * The `uncertain` flag is never cleared. A completed or ended intent takes
548
+ * no write, except a sync entry of a completed intent with `syncPending`.
549
+ * The caller holds the intent lock, so this takes only the store mutation
550
+ * order.
551
+ *
552
+ * @returns The stored entry, or undefined when nothing was written
553
+ */
554
+ export async function recordOutgoingDestinationProgress(store, clientMessageId, key, update) {
555
+ return serializeMutation(store, async () => {
556
+ const intentKey = recordKey('outbox', clientMessageId);
557
+ const existing = parseJson(await store.getMetadata(intentKey), null);
558
+ if (!existing) {
559
+ throw new Error('Cannot record the progress of a missing outgoing message intent');
560
+ }
561
+ const pendingSync = update.phase === 'sync' && existing.result && existing.syncPending;
562
+ if ((existing.result || existing.outcome !== undefined) && !pendingSync)
563
+ return undefined;
564
+ const entry = outgoingDestinationProgressEntry(existing, key, update);
565
+ applyDestinationUpdate(entry, update);
566
+ stampOutgoingDeadline(existing);
567
+ await store.setMetadata(intentKey, JSON.stringify(existing));
568
+ return cloneReliabilityValue(entry);
569
+ });
570
+ }
571
+ /**
572
+ * The manual resends of an intent. An intent that an earlier SDK stored, or
573
+ * that has no resend, has no `manualResends` field and reads as an empty
574
+ * list.
575
+ */
576
+ export function outgoingManualResends(intent) {
577
+ return intent.manualResends ?? [];
578
+ }
579
+ /**
580
+ * The time that the retention of an intent counts from: its `createdAt`, or
581
+ * the `createdAt` of its latest manual resend. The ledger indexes the intent
582
+ * at this time, so a manual resend keeps the intent, and its listing, for
583
+ * `RELIABILITY_RECORD_TTL_MS` after the resend. That is past the posting
584
+ * deadline of the resend.
585
+ */
586
+ export function outgoingIntentRetainedFrom(intent) {
587
+ return Math.max(intent.createdAt, ...outgoingManualResends(intent).map((resend) => resend.createdAt));
588
+ }
589
+ /** True when a manual resend has neither a result nor an outcome. */
590
+ export function isOpenManualResend(resend) {
591
+ return resend.result === undefined && resend.outcome === undefined;
592
+ }
593
+ /**
594
+ * The client message ID of manual resend number `n` of an intent, from 1.
595
+ */
596
+ export function manualResendMessageId(clientMessageId, n) {
597
+ return `${clientMessageId}:manual:${String(n)}`;
598
+ }
599
+ /**
600
+ * Store a new manual resend on an ended intent. The caller holds the intent
601
+ * lock. Only an intent with `outcome` and no `result` takes one, and only
602
+ * when no earlier resend of it is open. The intent keeps its own fields. The
603
+ * ledger indexes the intent again at the `createdAt` of the resend, as
604
+ * `outgoingIntentRetainedFrom` gives it. The new bucket is written before
605
+ * the intent leaves its old bucket, so a stop leaves it in a bucket, and a
606
+ * prune of the old bucket keeps an intent that the resend retains.
607
+ */
608
+ export async function addOutgoingManualResend(store, clientMessageId, resend, now = Date.now()) {
609
+ return serializeMutation(store, async () => {
610
+ const key = recordKey('outbox', clientMessageId);
611
+ const existing = parseJson(await store.getMetadata(key), null);
612
+ if (!existing || existing.result || existing.outcome === undefined) {
613
+ throw new Error('Only an ended outgoing message intent takes a manual resend');
614
+ }
615
+ const resends = outgoingManualResends(existing);
616
+ if (resends.some(isOpenManualResend)) {
617
+ throw new Error('An outgoing message intent has an open manual resend');
618
+ }
619
+ if (resend.manualMessageId !== manualResendMessageId(clientMessageId, resends.length + 1)) {
620
+ throw new Error('A manual resend has the wrong message ID');
621
+ }
622
+ const retainedFrom = outgoingIntentRetainedFrom(existing);
623
+ existing.manualResends = [...resends, cloneReliabilityValue(resend)];
624
+ await store.setMetadata(key, JSON.stringify(existing));
625
+ const indexTime = outgoingIntentRetainedFrom(existing);
626
+ const retainedDays = await pruneExpiredBuckets(store, 'outbox', now);
627
+ await indexRecord(store, 'outbox', clientMessageId, indexTime, retainedDays);
628
+ if (dayFor(indexTime) !== dayFor(retainedFrom)) {
629
+ await unindexRecord(store, 'outbox', clientMessageId, retainedFrom);
630
+ }
631
+ return cloneReliabilityValue(existing);
632
+ });
633
+ }
634
+ /** The stored intent and the index of its manual resend, for a write under the store order. */
635
+ async function readManualResend(store, clientMessageId, manualMessageId) {
636
+ const key = recordKey('outbox', clientMessageId);
637
+ const existing = parseJson(await store.getMetadata(key), null);
638
+ const resend = existing?.manualResends?.find((candidate) => candidate.manualMessageId === manualMessageId);
639
+ if (!existing || !resend)
640
+ throw new Error('Cannot write a missing manual resend');
641
+ return { key, existing, resend };
642
+ }
643
+ /**
644
+ * Record one request or one answer of one destination of an open manual
645
+ * resend, by the rules of `recordOutgoingDestinationProgress`. The resend
646
+ * writes progress before each of its requests from its first write, so a
647
+ * new entry starts with no uncertain request. An ended resend takes no
648
+ * write.
649
+ *
650
+ * @returns The stored entry, or undefined when nothing was written
651
+ */
652
+ export async function recordOutgoingManualResendProgress(store, clientMessageId, manualMessageId, key, update) {
653
+ return serializeMutation(store, async () => {
654
+ const read = await readManualResend(store, clientMessageId, manualMessageId);
655
+ const { resend } = read;
656
+ if (!isOpenManualResend(resend))
657
+ return undefined;
658
+ const progress = (resend.destinationProgress ??= {});
659
+ const entry = (progress[key] ??= {
660
+ phase: update.phase,
661
+ userId: update.userId,
662
+ deviceId: update.deviceId,
663
+ postMessageId: update.postMessageId,
664
+ state: 'pending',
665
+ requests: 0,
666
+ });
667
+ entry.postMessageId = update.postMessageId;
668
+ applyDestinationUpdate(entry, update);
669
+ await store.setMetadata(read.key, JSON.stringify(read.existing));
670
+ return cloneReliabilityValue(entry);
671
+ });
672
+ }
673
+ /**
674
+ * End an open manual resend: with its Relay result when the Relay accepted
675
+ * each of its destinations, else with its outcome. One write stores the end
676
+ * and `outcomeReportedAt`, so the end is reported at most once. Each entry
677
+ * of `destinationProgress` replaces the stored entry under its key.
678
+ *
679
+ * @returns The ended resend, or undefined when it had already ended
680
+ */
681
+ export async function endOutgoingManualResend(store, clientMessageId, manualMessageId, end, at = Date.now()) {
682
+ return serializeMutation(store, async () => {
683
+ const read = await readManualResend(store, clientMessageId, manualMessageId);
684
+ const { resend } = read;
685
+ if (!isOpenManualResend(resend))
686
+ return undefined;
687
+ if ('result' in end) {
688
+ resend.result = cloneReliabilityValue(end.result);
689
+ }
690
+ else {
691
+ resend.outcome = end.outcome;
692
+ resend.destinationProgress = {
693
+ ...resend.destinationProgress,
694
+ ...cloneReliabilityValue(end.destinationProgress),
695
+ };
696
+ }
697
+ resend.outcomeReportedAt = at;
698
+ await store.setMetadata(read.key, JSON.stringify(read.existing));
699
+ return cloneReliabilityValue(resend);
700
+ });
701
+ }
306
702
  function outgoingMessageDeviceKey(message) {
307
703
  return outgoingDeviceKey({
308
704
  userId: message.recipientUserId,
@@ -349,6 +745,7 @@ export async function confirmOutgoingPreMessages(store, clientMessageId, accepte
349
745
  existing.preMessages = remaining;
350
746
  else
351
747
  delete existing.preMessages;
748
+ stampOutgoingDeadline(existing);
352
749
  await store.setMetadata(key, JSON.stringify(existing));
353
750
  return cloneReliabilityValue(existing);
354
751
  });
@@ -356,7 +753,11 @@ export async function confirmOutgoingPreMessages(store, clientMessageId, accepte
356
753
  /**
357
754
  * Replace stored pre-messages of a group intent in one write. Each
358
755
  * replacement keeps the target and the timestamp of the pre-message that it
359
- * replaces, and the stored pre-message must still equal the expected one.
756
+ * replaces, and the stored pre-message must still equal the expected one. A
757
+ * replacement under a new client message ID is a repair: its progress entry
758
+ * gets `repaired`, and the write creates the entry when none exists. A
759
+ * replacement under the same ID, such as the sealed form of the stored
760
+ * pre-message, gets no mark.
360
761
  */
361
762
  export async function replaceOutgoingGroupPreMessages(store, clientMessageId, replacements) {
362
763
  return serializeMutation(store, async () => {
@@ -377,8 +778,12 @@ export async function replaceOutgoingGroupPreMessages(store, clientMessageId, re
377
778
  replacement.timestamp !== expected.timestamp) {
378
779
  throw new Error('A group pre-message replacement cannot change its target or timestamp');
379
780
  }
781
+ if (replacement.clientMessageId !== expected.clientMessageId) {
782
+ markOutgoingDestinationRepaired(existing, 'recipient', replacement, 'stale-device', true);
783
+ }
380
784
  preMessages[index] = cloneReliabilityValue(replacement);
381
785
  }
786
+ stampOutgoingDeadline(existing);
382
787
  await store.setMetadata(key, JSON.stringify(existing));
383
788
  return cloneReliabilityValue(existing);
384
789
  });
@@ -410,6 +815,7 @@ export async function reconcileOutgoingDirectDeviceMessages(store, clientMessage
410
815
  existing.deviceMessages.push(cloneReliabilityValue(message));
411
816
  }
412
817
  delete existing.reconcilePending;
818
+ stampOutgoingDeadline(existing);
413
819
  await store.setMetadata(key, JSON.stringify(existing));
414
820
  return cloneReliabilityValue(existing);
415
821
  });
@@ -429,10 +835,17 @@ export async function reconcileOutgoingSyncMessages(store, clientMessageId, remo
429
835
  throw new Error('Cannot change the sync copies of a missing or completed outbox intent');
430
836
  }
431
837
  existing.syncMessages = appendOutgoingDeviceMessages(existing.syncMessages.filter((message) => !removedDeviceIds.includes(message.recipientDeviceId)), additions, 'Cannot replace a persisted sync transmission');
838
+ stampOutgoingDeadline(existing);
432
839
  await store.setMetadata(key, JSON.stringify(existing));
433
840
  return cloneReliabilityValue(existing);
434
841
  });
435
842
  }
843
+ /**
844
+ * Replace the stored message of one device of an open direct intent after a
845
+ * session repair. The progress entry of the device gets the repair mark.
846
+ *
847
+ * @returns The stored intent, with the progress entry of the device
848
+ */
436
849
  export async function replaceOutgoingDirectDeviceMessage(store, clientMessageId, expected, replacement) {
437
850
  return serializeMutation(store, async () => {
438
851
  const key = recordKey('outbox', clientMessageId);
@@ -451,13 +864,15 @@ export async function replaceOutgoingDirectDeviceMessage(store, clientMessageId,
451
864
  throw new Error('A direct outbox repair cannot change its target or timestamp');
452
865
  }
453
866
  existing.deviceMessages[index] = cloneReliabilityValue(replacement);
867
+ markOutgoingDestinationRepaired(existing, 'recipient', replacement, 'stale-device', true);
868
+ stampOutgoingDeadline(existing);
454
869
  await store.setMetadata(key, JSON.stringify(existing));
455
870
  return cloneReliabilityValue(existing);
456
871
  });
457
872
  }
458
873
  export async function getOutgoingMessageIntent(store, clientMessageId, now = Date.now()) {
459
874
  const record = parseJson(await store.getMetadata(recordKey('outbox', clientMessageId)), null);
460
- if (!record || record.createdAt < now - RELIABILITY_RECORD_TTL_MS)
875
+ if (!record || outgoingIntentRetainedFrom(record) < now - RELIABILITY_RECORD_TTL_MS)
461
876
  return null;
462
877
  return cloneReliabilityValue(record);
463
878
  }
@@ -466,7 +881,9 @@ export async function storeOutgoingMessageIntent(store, intent, now = Date.now()
466
881
  const retainedDays = await pruneExpiredBuckets(store, 'outbox', now);
467
882
  const key = recordKey('outbox', intent.clientMessageId);
468
883
  const existing = parseJson(await store.getMetadata(key), null);
469
- const retainedExisting = existing && existing.createdAt >= now - RELIABILITY_RECORD_TTL_MS ? existing : null;
884
+ const retainedExisting = existing && outgoingIntentRetainedFrom(existing) >= now - RELIABILITY_RECORD_TTL_MS
885
+ ? existing
886
+ : null;
470
887
  if (retainedExisting && !sameIntent(retainedExisting, intent)) {
471
888
  throw new Error('A clientMessageId cannot identify two different encrypted sends');
472
889
  }
@@ -474,13 +891,19 @@ export async function storeOutgoingMessageIntent(store, intent, now = Date.now()
474
891
  await store.setMetadata(key, JSON.stringify(intent));
475
892
  await indexSentTimestamp(store, intent, now);
476
893
  }
477
- await indexRecord(store, 'outbox', intent.clientMessageId, intent.createdAt, retainedDays);
894
+ else {
895
+ // A failed index write after the intent write leaves the retained
896
+ // intent without its timestamp lookup. The same intent repairs only
897
+ // that index, under the retained creation time.
898
+ await indexSentTimestamp(store, retainedExisting, now);
899
+ }
900
+ await indexRecord(store, 'outbox', intent.clientMessageId, outgoingIntentRetainedFrom(retainedExisting ?? intent), retainedDays);
478
901
  });
479
902
  }
480
903
  /**
481
- * Index the client message ID of a new intent under its client timestamp,
904
+ * Index the client message ID of an intent under its client timestamp,
482
905
  * the value by which an E2EE receipt names the message. The index expires
483
- * with the intent.
906
+ * with the intent. A second call for the same intent changes no entry.
484
907
  */
485
908
  async function indexSentTimestamp(store, intent, now) {
486
909
  const retainedDays = await pruneExpiredBuckets(store, 'sent-timestamp', now);
@@ -501,6 +924,33 @@ async function indexSentTimestamp(store, intent, now) {
501
924
  export async function getSentClientMessageIds(store, clientTimestamp) {
502
925
  return parseJson(await store.getMetadata(recordKey('sent-timestamp', String(clientTimestamp))), []);
503
926
  }
927
+ /** The record ID of one received message. */
928
+ function receivedMessageId(key) {
929
+ return JSON.stringify([key.senderUserId, key.senderDeviceId, key.timestamp, key.contentDigest]);
930
+ }
931
+ /**
932
+ * True when the local device processed a message with this key. The record
933
+ * expires after `RETRY_REQUESTER_RECORD_TTL_MS`.
934
+ */
935
+ export async function hasReceivedTimestamp(store, key) {
936
+ const value = await store.getMetadata(recordKey('received-timestamp', receivedMessageId(key)));
937
+ return value !== null;
938
+ }
939
+ /** Write the record of one received message. The caller serializes the write. */
940
+ async function writeReceivedTimestamp(store, key, now) {
941
+ const retainedDays = await pruneExpiredBuckets(store, 'received-timestamp', now);
942
+ const id = receivedMessageId(key);
943
+ await store.setMetadata(recordKey('received-timestamp', id), JSON.stringify({ receivedAt: now }));
944
+ await indexRecord(store, 'received-timestamp', id, now, retainedDays);
945
+ }
946
+ /**
947
+ * Record that the local device processed a message with this key. The
948
+ * record expires after `RETRY_REQUESTER_RECORD_TTL_MS`. A receive that completes
949
+ * its record writes the key with `completeReceiveRecord` instead.
950
+ */
951
+ export async function recordReceivedTimestamp(store, key, now = Date.now()) {
952
+ await serializeMutation(store, () => writeReceivedTimestamp(store, key, now));
953
+ }
504
954
  /**
505
955
  * Read and change the delivery status of one outgoing message in one
506
956
  * serialized step. The step also reads the outbox intent, so an intent that
@@ -534,7 +984,8 @@ export async function updateDeliveryStatus(store, clientMessageId, update, now =
534
984
  * the recipient phase completed and the sync phase did not: the intent keeps
535
985
  * its sync messages and the restart count of its sync phase, so a replay
536
986
  * posts only the sync messages. With `syncPending` and no sync messages, the
537
- * read of the own device list failed, and a replay reads it.
987
+ * read of the own device list failed, and a replay reads it. The intent
988
+ * keeps `destinationProgress`.
538
989
  */
539
990
  export async function completeOutgoingMessageIntent(store, clientMessageId, result, options = {}) {
540
991
  await serializeMutation(store, async () => {
@@ -545,6 +996,9 @@ export async function completeOutgoingMessageIntent(store, clientMessageId, resu
545
996
  if (existing.result && JSON.stringify(existing.result) !== JSON.stringify(result)) {
546
997
  throw new Error('Cannot replace an outgoing message intent with a different Relay result');
547
998
  }
999
+ const report = existing.result ? undefined : outgoingIntentEndReport(store, clientMessageId);
1000
+ if (report?.driven && !existing.internal)
1001
+ existing.outcomeReportPending = true;
548
1002
  existing.result = cloneReliabilityValue(result);
549
1003
  delete existing.reconcilePending;
550
1004
  delete existing.preMessages;
@@ -576,6 +1030,170 @@ export async function completeOutgoingMessageIntent(store, clientMessageId, resu
576
1030
  delete existing.groupSenderKeyDistributionId;
577
1031
  delete existing.groupSharedMessage;
578
1032
  await store.setMetadata(key, JSON.stringify(existing));
1033
+ if (report)
1034
+ report.ended = cloneReliabilityValue(existing);
1035
+ });
1036
+ }
1037
+ /**
1038
+ * End an open intent at its posting deadline. It keeps the device messages
1039
+ * and every other field, and it stores the posting deadline. Each entry of
1040
+ * `destinationProgress` replaces the stored entry under its key, and each
1041
+ * other stored entry stays. A completed
1042
+ * intent keeps its `result`, which takes precedence, and this writes nothing.
1043
+ * An intent that ended with another outcome is refused.
1044
+ */
1045
+ export async function endOutgoingMessageIntent(store, clientMessageId, end) {
1046
+ await serializeMutation(store, async () => {
1047
+ const key = recordKey('outbox', clientMessageId);
1048
+ const existing = parseJson(await store.getMetadata(key), null);
1049
+ if (!existing)
1050
+ throw new Error('Cannot end a missing outgoing message intent');
1051
+ if (existing.result)
1052
+ return;
1053
+ if (existing.outcome !== undefined && existing.outcome !== end.outcome) {
1054
+ throw new Error('Cannot end an outgoing message intent with a different outcome');
1055
+ }
1056
+ const report = existing.outcome === undefined ? outgoingIntentEndReport(store, clientMessageId) : undefined;
1057
+ if (report?.driven && !existing.internal)
1058
+ existing.outcomeReportPending = true;
1059
+ existing.outcome = end.outcome;
1060
+ existing.destinationProgress = {
1061
+ ...existing.destinationProgress,
1062
+ ...cloneReliabilityValue(end.destinationProgress),
1063
+ };
1064
+ stampOutgoingDeadline(existing);
1065
+ await store.setMetadata(key, JSON.stringify(existing));
1066
+ if (report)
1067
+ report.ended = cloneReliabilityValue(existing);
1068
+ });
1069
+ }
1070
+ /** The key prefix of the outgoing intent records. */
1071
+ const OUTGOING_INTENT_RECORD_PREFIX = `${OUTBOX_PREFIX}:record:`;
1072
+ /** The keys of one listing page of the outgoing intent records. */
1073
+ const OUTGOING_INTENT_PAGE_SIZE = 100;
1074
+ /** The intent of the record under `key`, or null for a value that is not an intent. */
1075
+ function parseOutgoingIntentRecord(key, value) {
1076
+ try {
1077
+ const clientMessageId = decodeURIComponent(key.slice(OUTGOING_INTENT_RECORD_PREFIX.length));
1078
+ const record = parseJson(value, null);
1079
+ if (record === null ||
1080
+ typeof record !== 'object' ||
1081
+ (record.kind !== 'direct' && record.kind !== 'group') ||
1082
+ record.clientMessageId !== clientMessageId ||
1083
+ typeof record.recipientId !== 'string' ||
1084
+ typeof record.plaintextDigest !== 'string' ||
1085
+ !Number.isFinite(record.clientTimestamp) ||
1086
+ !Number.isFinite(record.createdAt) ||
1087
+ !Array.isArray(record.deviceMessages) ||
1088
+ !Array.isArray(record.syncMessages)) {
1089
+ return null;
1090
+ }
1091
+ return record;
1092
+ }
1093
+ catch {
1094
+ return null;
1095
+ }
1096
+ }
1097
+ /**
1098
+ * Every stored outgoing intent, in the key order of the store, or undefined
1099
+ * when the store does not implement `listMetadataKeys`. It skips a value
1100
+ * that is not an intent. It lists exactly the record prefix of the outbox,
1101
+ * so the bucket and manifest rows of the outbox stay out.
1102
+ */
1103
+ async function scanOutgoingIntentRecords(store) {
1104
+ if (typeof store.listMetadataKeys !== 'function')
1105
+ return undefined;
1106
+ const intents = [];
1107
+ let after;
1108
+ for (;;) {
1109
+ const keys = await store.listMetadataKeys({
1110
+ prefix: OUTGOING_INTENT_RECORD_PREFIX,
1111
+ ...(after !== undefined && { after }),
1112
+ limit: OUTGOING_INTENT_PAGE_SIZE,
1113
+ });
1114
+ for (const key of keys) {
1115
+ if (!key.startsWith(OUTGOING_INTENT_RECORD_PREFIX))
1116
+ continue;
1117
+ if (after !== undefined && key <= after)
1118
+ continue;
1119
+ const intent = parseOutgoingIntentRecord(key, await store.getMetadata(key));
1120
+ if (intent)
1121
+ intents.push(intent);
1122
+ }
1123
+ const last = keys[keys.length - 1];
1124
+ // A page that ends at or below `after` would list the same keys again.
1125
+ if (keys.length < OUTGOING_INTENT_PAGE_SIZE || (after !== undefined && last <= after)) {
1126
+ return intents;
1127
+ }
1128
+ after = last;
1129
+ }
1130
+ }
1131
+ /**
1132
+ * The outgoing intents that the SDK send driver acts on, or undefined when
1133
+ * the store does not implement `listMetadataKeys`. It returns each intent
1134
+ * whose `outgoingIntentRetainedFrom` is not older than
1135
+ * `RELIABILITY_RECORD_TTL_MS` and that is open (no
1136
+ * `result` and no `outcome`), holds `outcomeReportPending`, or holds a
1137
+ * manual resend with no `result` and no `outcome` of its own.
1138
+ */
1139
+ export async function listOpenOutgoingIntents(store, now = Date.now()) {
1140
+ const intents = await scanOutgoingIntentRecords(store);
1141
+ if (intents === undefined)
1142
+ return undefined;
1143
+ return intents.filter((intent) => outgoingIntentRetainedFrom(intent) >= now - RELIABILITY_RECORD_TTL_MS &&
1144
+ ((!intent.result && intent.outcome === undefined) ||
1145
+ intent.outcomeReportPending === true ||
1146
+ outgoingManualResends(intent).some(isOpenManualResend)));
1147
+ }
1148
+ /**
1149
+ * Clear `outcomeReportPending` on an intent and record the time of the
1150
+ * report. The SDK send driver calls it before it calls `onSendOutcome`, and
1151
+ * calls the hook only when it returns true. It reads the record again under
1152
+ * the intent lock, so of two drivers on one store, only one clears the mark.
1153
+ * It returns false, and writes nothing, for an intent without the field.
1154
+ */
1155
+ export async function markOutgoingIntentReported(store, clientMessageId, at = Date.now()) {
1156
+ return withOutgoingMessageIntentLock(store, clientMessageId, () => serializeMutation(store, async () => {
1157
+ const key = recordKey('outbox', clientMessageId);
1158
+ const existing = parseJson(await store.getMetadata(key), null);
1159
+ if (!existing?.outcomeReportPending)
1160
+ return false;
1161
+ delete existing.outcomeReportPending;
1162
+ existing.outcomeReportedAt = at;
1163
+ await store.setMetadata(key, JSON.stringify(existing));
1164
+ return true;
1165
+ }));
1166
+ }
1167
+ /**
1168
+ * Store the posting deadline on each open outgoing intent that an earlier
1169
+ * SDK stored without one. The deadline comes from the stored times, as
1170
+ * `outgoingMessageDeadlineAt` computes it, so the moved deadline is the one
1171
+ * that the intent already had. It writes no report field, so the SDK send
1172
+ * driver reports no end that an earlier SDK wrote. With a store that does
1173
+ * not implement `listMetadataKeys`, or with no open intent without a
1174
+ * deadline, it writes nothing. Such an intent then gets its deadline at its
1175
+ * next mutation write.
1176
+ */
1177
+ export async function migrateOutgoingIntentRecords(store, now = Date.now()) {
1178
+ const intents = await listOpenOutgoingIntents(store, now);
1179
+ const unstamped = (intents ?? []).filter((intent) => !intent.result && intent.outcome === undefined && intent.deadlineAt === undefined);
1180
+ if (unstamped.length === 0)
1181
+ return;
1182
+ await serializeMutation(store, async () => {
1183
+ for (const intent of unstamped) {
1184
+ const key = recordKey('outbox', intent.clientMessageId);
1185
+ const existing = parseOutgoingIntentRecord(key, await store.getMetadata(key));
1186
+ if (!existing ||
1187
+ existing.result ||
1188
+ existing.outcome !== undefined ||
1189
+ existing.deadlineAt !== undefined) {
1190
+ continue;
1191
+ }
1192
+ stampOutgoingDeadline(existing);
1193
+ if (existing.deadlineAt === undefined)
1194
+ continue;
1195
+ await store.setMetadata(key, JSON.stringify(existing));
1196
+ }
579
1197
  });
580
1198
  }
581
1199
  /** The lifetime of one processed-envelope record. */
@@ -689,9 +1307,9 @@ async function writeProcessedEnvelope(store, processedAt, write) {
689
1307
  }
690
1308
  /**
691
1309
  * Complete one receive record: delete it and write its processed-envelope
692
- * records in one atomic store write. The writes run against a buffer over
693
- * the store, so the ledger index and the records commit with the delete or
694
- * not at all.
1310
+ * records and the record of its received message in one atomic store write.
1311
+ * The writes run against a buffer over the store, so the ledger index and the
1312
+ * records commit with the delete or not at all.
695
1313
  *
696
1314
  * @returns False, with nothing written, when the stored revision of the
697
1315
  * receive record is not `expectedRevision`.
@@ -708,8 +1326,14 @@ export async function completeReceiveRecord(store, workId, expectedRevision, wri
708
1326
  buffer.set(key, null);
709
1327
  },
710
1328
  };
711
- for (const write of writes)
712
- await writeProcessedEnvelope(buffered, processedAt, write);
1329
+ for (const write of writes) {
1330
+ if ('receivedMessage' in write) {
1331
+ await writeReceivedTimestamp(buffered, write.receivedMessage, processedAt);
1332
+ }
1333
+ else {
1334
+ await writeProcessedEnvelope(buffered, processedAt, write);
1335
+ }
1336
+ }
713
1337
  return store.completeReceiveWork(workId, expectedRevision, [...buffer].map(([key, value]) => ({ key, value })));
714
1338
  });
715
1339
  }
@@ -758,9 +1382,9 @@ export function retryNullMessageClientMessageId(retryId) {
758
1382
  * The client message ID of one attempt of a retry request or a retry resend.
759
1383
  * Attempt 1 posts under the given ID, and attempt `n` posts under
760
1384
  * `<id>:<n>`. A resend takes the attempt number of the request that it
761
- * answers. A new encryption for the same request attempt posts the same
762
- * ID, and the processed ledger of the requester and the RETRY_CONFLICT
763
- * answer of the Relay cover the new bytes.
1385
+ * answers. Each attempt ID gets one encryption. When the Relay refuses the
1386
+ * stored bytes of an attempt with OPERATION_EXPIRED, the attempt is marked
1387
+ * acceptance-unknown, and nothing more posts under its ID.
764
1388
  */
765
1389
  export function retryAttemptClientMessageId(id, attempt) {
766
1390
  if (!Number.isSafeInteger(attempt) || attempt < 1) {
@@ -838,6 +1462,20 @@ export async function resolveRetryFamilyMember(store, envelopeId, now = Date.now
838
1462
  return undefined;
839
1463
  return { retryId: member.retryId, failedEnvelopeId, kind: member.kind, attempt: member.attempt };
840
1464
  }
1465
+ /**
1466
+ * The posting deadline of a retry request: the stored `postingDeadlineAt`.
1467
+ * A record that an earlier SDK stored has none. Its deadline is then the
1468
+ * first failure, `receivedAt`, else the time of the stored attempt, plus
1469
+ * `RETRY_REQUEST_POSTING_WINDOW_MS`, and at most `deadlineAt`. An earlier
1470
+ * SDK can store a `deadlineAt` one day after the first failure, so
1471
+ * `deadlineAt` does not give the time of the first failure.
1472
+ */
1473
+ export function retryRequestPostingDeadlineAt(record) {
1474
+ if (record.postingDeadlineAt !== undefined)
1475
+ return record.postingDeadlineAt;
1476
+ const firstFailureAt = record.receivedAt ?? record.requestedAt;
1477
+ return Math.min(record.deadlineAt, firstFailureAt + RETRY_REQUEST_POSTING_WINDOW_MS);
1478
+ }
841
1479
  /** The shortest time between two session reset null messages to one device. */
842
1480
  export const RETRY_TERMINAL_NULL_MESSAGE_INTERVAL_MS = 60 * 60 * 1_000;
843
1481
  const RETRY_TERMINAL_CLASSES = new Set([
@@ -845,6 +1483,7 @@ const RETRY_TERMINAL_CLASSES = new Set([
845
1483
  'missing-prekey',
846
1484
  'revoked-authority',
847
1485
  'expired-content',
1486
+ 'posting-deadline',
848
1487
  'attempts-exhausted',
849
1488
  'deletion',
850
1489
  'abuse-allowance-exhausted',
@@ -893,6 +1532,7 @@ export async function getRetryRequest(store, failedEnvelopeId, now = Date.now(),
893
1532
  record.attempt < 1 ||
894
1533
  typeof record.answered !== 'boolean' ||
895
1534
  !Number.isFinite(record.deadlineAt) ||
1535
+ (record.postingDeadlineAt !== undefined && !Number.isFinite(record.postingDeadlineAt)) ||
896
1536
  (record.nextAttemptAt !== undefined && !Number.isFinite(record.nextAttemptAt)) ||
897
1537
  (record.lastFailureClass !== undefined &&
898
1538
  record.lastFailureClass !== 'transport-outage' &&
@@ -907,7 +1547,9 @@ export async function getRetryRequest(store, failedEnvelopeId, now = Date.now(),
907
1547
  (typeof record.failedSender?.userId !== 'string' ||
908
1548
  !Number.isSafeInteger(record.failedSender.deviceId))) ||
909
1549
  (record.recovery !== undefined &&
910
- (record.terminal?.class !== 'expired-content' || !isRetryTerminalRecovery(record.recovery)))) {
1550
+ ((record.terminal?.class !== 'expired-content' &&
1551
+ record.terminal?.class !== 'posting-deadline') ||
1552
+ !isRetryTerminalRecovery(record.recovery)))) {
911
1553
  throw new Error('Corrupt retry-request record');
912
1554
  }
913
1555
  if (record.requestedAt < now - RETRY_REQUESTER_RECORD_TTL_MS)