domma-cms 1.28.3 → 1.29.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 (99) hide show
  1. package/CHANGELOG.md +9 -0
  2. package/admin/js/lib/contacts-arrange.js +1 -1
  3. package/docs/DommaFeatures.md +5 -3
  4. package/package.json +4 -1
  5. package/plugins/_lib/admin/mail/body-menu.js +2 -0
  6. package/plugins/_lib/admin/mail/cms-host.js +22 -0
  7. package/plugins/_lib/admin/mail/compose-window.js +1027 -1021
  8. package/plugins/_lib/admin/mail/contacts.js +10 -8
  9. package/plugins/_lib/admin/mail/diagnostics-section.js +2 -0
  10. package/plugins/_lib/admin/mail/drag-drop.js +46 -0
  11. package/plugins/_lib/admin/mail/folder-tree.js +2 -0
  12. package/plugins/_lib/admin/mail/font-controls.js +6 -4
  13. package/plugins/_lib/admin/mail/fonts.js +1 -1
  14. package/plugins/_lib/admin/mail/host-context.js +87 -0
  15. package/plugins/_lib/admin/mail/identity.js +2 -0
  16. package/plugins/_lib/admin/mail/image-senders-section.js +2 -0
  17. package/plugins/_lib/admin/mail/keyboard.js +2 -0
  18. package/plugins/_lib/admin/mail/mail.css +1 -1
  19. package/plugins/_lib/admin/mail/mail.html +4 -0
  20. package/plugins/_lib/admin/mail/message-actions.js +2 -0
  21. package/plugins/_lib/admin/mail/oauth-panel.js +2 -0
  22. package/plugins/_lib/admin/mail/panes.js +2 -0
  23. package/plugins/_lib/admin/mail/reader-kit.js +2 -0
  24. package/plugins/_lib/admin/mail/reader-runtime.js +6534 -0
  25. package/plugins/_lib/admin/mail/reader-view.js +9 -6380
  26. package/plugins/_lib/admin/mail/resizable.js +2 -0
  27. package/plugins/_lib/admin/mail/restore-spam.js +13 -0
  28. package/plugins/_lib/admin/mail/rules.js +14 -0
  29. package/plugins/_lib/admin/mail/scheduling.js +4 -1
  30. package/plugins/_lib/admin/mail/section-kit.js +4 -1
  31. package/plugins/_lib/admin/mail/security-note.js +2 -0
  32. package/plugins/_lib/admin/mail/settings-section.js +11 -10
  33. package/plugins/_lib/admin/mail/templates.js +5 -2
  34. package/plugins/_lib/admin/mail/threads.js +2 -0
  35. package/plugins/_lib/admin/mail/vacation.js +16 -2
  36. package/plugins/_lib/admin/mail/when-closed.js +24 -2
  37. package/plugins/_lib/admin/ui/dates.js +2 -0
  38. package/plugins/_lib/admin/ui/resizable.js +7 -5
  39. package/plugins/_lib/contacts/mailContact.js +69 -0
  40. package/plugins/_lib/contacts/model.js +199 -0
  41. package/plugins/_lib/domma-mail-contacts.lock.json +10 -0
  42. package/plugins/_lib/domma-mail.lock.json +85 -0
  43. package/plugins/_lib/games/plays.js +15 -3
  44. package/plugins/_lib/mail/accountFileStore.js +66 -0
  45. package/plugins/_lib/mail/accountRepository.js +617 -0
  46. package/plugins/_lib/mail/accountRoutes.js +130 -0
  47. package/plugins/_lib/mail/accounts.js +66 -940
  48. package/plugins/_lib/mail/automationLock.js +10 -0
  49. package/plugins/_lib/mail/bodyTokenProvider.js +36 -0
  50. package/plugins/_lib/mail/bodyTokens.js +5 -99
  51. package/plugins/_lib/mail/compose.js +5 -3
  52. package/plugins/_lib/mail/defaults.js +2 -0
  53. package/plugins/_lib/mail/envelope.js +3 -1
  54. package/plugins/_lib/mail/folderActions.js +83 -0
  55. package/plugins/_lib/mail/folderRuntime.js +109 -0
  56. package/plugins/_lib/mail/folders.js +4 -9
  57. package/plugins/_lib/mail/imapPool.js +11 -389
  58. package/plugins/_lib/mail/imapPoolRuntime.js +396 -0
  59. package/plugins/_lib/mail/mbox.js +2 -0
  60. package/plugins/_lib/mail/message-action.js +2 -0
  61. package/plugins/_lib/mail/messageSecurity.js +4 -111
  62. package/plugins/_lib/mail/messageSecurityProvider.js +116 -0
  63. package/plugins/_lib/mail/networkAddresses.js +77 -0
  64. package/plugins/_lib/mail/networkPolicy.js +62 -0
  65. package/plugins/_lib/mail/oauth.js +3 -451
  66. package/plugins/_lib/mail/oauthAccounts.js +178 -0
  67. package/plugins/_lib/mail/oauthRouteRuntime.js +282 -0
  68. package/plugins/_lib/mail/oauthRoutes.js +7 -289
  69. package/plugins/_lib/mail/oauthRuntime.js +456 -0
  70. package/plugins/_lib/mail/pollSchedule.js +2 -0
  71. package/plugins/_lib/mail/poller.js +4 -136
  72. package/plugins/_lib/mail/pollerRuntime.js +150 -0
  73. package/plugins/_lib/mail/priority.js +2 -0
  74. package/plugins/_lib/mail/publicMailbox.js +27 -0
  75. package/plugins/_lib/mail/readRoutes.js +14 -827
  76. package/plugins/_lib/mail/readRuntime.js +701 -0
  77. package/plugins/_lib/mail/render.js +2 -0
  78. package/plugins/_lib/mail/ruleRunner.js +27 -10
  79. package/plugins/_lib/mail/scheduler.js +11 -279
  80. package/plugins/_lib/mail/schedulerRuntime.js +259 -0
  81. package/plugins/_lib/mail/secretProvider.js +112 -0
  82. package/plugins/_lib/mail/secretbox.js +12 -225
  83. package/plugins/_lib/mail/send.js +21 -537
  84. package/plugins/_lib/mail/sieve.js +211 -0
  85. package/plugins/_lib/mail/sieveHost.js +24 -0
  86. package/plugins/_lib/mail/smtpService.js +553 -0
  87. package/plugins/_lib/mail/snoozeRuntime.js +60 -0
  88. package/plugins/_lib/mail/store.js +122 -64
  89. package/plugins/_lib/mail/subscriptions.js +11 -0
  90. package/plugins/_lib/mail/sync.js +64 -290
  91. package/plugins/_lib/mail/syncPlan.js +2 -0
  92. package/plugins/_lib/mail/syncRuntime.js +255 -0
  93. package/plugins/_lib/mail/syncSelection.js +2 -0
  94. package/plugins/_lib/mail/unreadBadge.js +2 -0
  95. package/plugins/_lib/mail/unsubscribe.js +2 -0
  96. package/plugins/_lib/mail/vacationRunner.js +3 -116
  97. package/plugins/_lib/mail/vacationRuntime.js +70 -0
  98. package/plugins/_lib/mail/write.js +44 -13
  99. package/server/routes/api/contacts.js +2 -196
@@ -1,3 +1,5 @@
1
+ // Source: @domma-mail/core 0.18.0, packages/core/src/mail/render.js.
2
+ // Update with domma-mail/scripts/sync-cms.mjs; edit the shared source.
1
3
  /**
2
4
  * Message rendering for the Mail Reader plugin.
3
5
  *
@@ -1,3 +1,5 @@
1
+ // Source: @domma-mail/core 0.18.0, packages/core/src/mail/ruleRunner.js.
2
+ // Update with domma-mail/scripts/sync-cms.mjs; edit the shared source.
1
3
  /**
2
4
  * Carrying out what the rules decided.
3
5
  *
@@ -29,7 +31,8 @@ import {
29
31
  deleteMessage,
30
32
  findJunkFolder,
31
33
  JUNK_KEYWORD,
32
- moveMessage
34
+ moveMessage,
35
+ safeWritePool
33
36
  } from './write.js';
34
37
 
35
38
  /**
@@ -44,7 +47,9 @@ export function eligible(messages, sync, since) {
44
47
  // A full resync is the whole folder arriving again, not new mail.
45
48
  if (sync?.mode === 'full') return [];
46
49
 
47
- const floor = since ? new Date(since).getTime() : null;
50
+ // Email Date headers usually have second precision; account settings have
51
+ // milliseconds. UID checkpoints keep earlier mail out within that second.
52
+ const floor = since ? Math.floor(new Date(since).getTime() / 1000) * 1000 : null;
48
53
  return (messages ?? []).filter(message => {
49
54
  if (floor === null) return true;
50
55
  const date = new Date(String(message?.date ?? '')).getTime();
@@ -74,19 +79,25 @@ export function eligible(messages, sync, since) {
74
79
  export async function applyRules({
75
80
  pool, store, account, poolKey, connection, folder, messages, rules
76
81
  }) {
82
+ pool = safeWritePool(pool);
77
83
  const report = {considered: messages?.length ?? 0, acted: 0, moved: 0, errors: []};
78
84
  if (!report.considered || !(rules ?? []).length) return report;
79
85
 
80
86
  // Resolved once for the whole pass rather than per message: it is a LIST
81
87
  // round trip, and a folder of newsletters would otherwise make one per
82
88
  // message.
83
- let junk;
89
+ let junk, trash;
84
90
 
85
91
  for (const message of messages) {
86
92
  const {actions} = planActions(rules, message);
87
93
  if (!actions.length) continue;
88
94
 
89
95
  try {
96
+ const destination = actions.find(a => ['move', 'junk', 'delete'].includes(a.type));
97
+ if (destination?.type === 'delete') {
98
+ if (trash === undefined) trash = (await pool.withClient(poolKey, connection, client => client.list())).find(box => box.specialUse === '\\Trash')?.path ?? null;
99
+ if (!trash || trash === folder) throw new Error('This rule cannot move to Trash safely. No mail was permanently deleted.');
100
+ }
90
101
  // Flags first, destination last. A message that is moved has a new
91
102
  // UID in its new home, so anything flagged afterwards would be
92
103
  // flagging a UID that no longer exists here.
@@ -98,24 +109,28 @@ export async function applyRules({
98
109
  }
99
110
 
100
111
  if (add.length) {
101
- await pool.withMailbox(poolKey, connection, folder, client =>
102
- client.messageFlagsAdd({uid: String(message.uid)}, add, {uid: true}),
112
+ await pool.withMailbox(poolKey, connection, folder, async client => {
113
+ if (await client.messageFlagsAdd({uid: String(message.uid)}, add, {uid: true}) === false) throw new Error('The server refused the rule flag change.');
114
+ },
103
115
  {writable: true});
104
116
  }
105
117
 
106
118
  const copy = actions.find(a => a.type === 'copy');
107
119
  if (copy) {
108
- await pool.withMailbox(poolKey, connection, folder, client =>
109
- client.messageCopy({uid: String(message.uid)}, copy.folder, {uid: true}),
120
+ await pool.withMailbox(poolKey, connection, folder, async client => {
121
+ if (await client.messageCopy({uid: String(message.uid)}, copy.folder, {uid: true}) === false) throw new Error('The server refused the rule copy.');
122
+ },
110
123
  {writable: true});
111
124
  }
112
125
 
113
- const destination = actions.find(a => ['move', 'junk', 'delete'].includes(a.type));
126
+ let filed = false;
114
127
  if (destination) {
115
128
  if (destination.type === 'delete') {
116
129
  await deleteMessage({
117
- pool, store, account, poolKey, connection, folder, uid: message.uid
130
+ pool, store, account, poolKey, connection, folder, uid: message.uid, trash
118
131
  });
132
+ filed = true;
133
+ report.moved += 1;
119
134
  } else {
120
135
  if (destination.type === 'junk' && junk === undefined) {
121
136
  junk = await findJunkFolder(pool, poolKey, connection);
@@ -130,9 +145,11 @@ export async function applyRules({
130
145
  folder, uid: message.uid, destination: target
131
146
  });
132
147
  report.moved += 1;
148
+ filed = true;
133
149
  }
134
150
  }
135
- } else if (add.length && store) {
151
+ }
152
+ if (!filed && add.length && store) {
136
153
  // Flagged in place: the mirror row is still ours to correct,
137
154
  // and leaving it stale means the list shows unread mail that
138
155
  // a rule has just read.
@@ -1,283 +1,15 @@
1
- /**
2
- * The worker behind "send later", "undo send" and "snooze".
3
- *
4
- * One ticker, two queues, for the same reason the poller is one ticker rather
5
- * than a timer per mailbox: the work is small, the queues are short, and a
6
- * timer per queued message is a timer to cancel when the message is cancelled.
7
- *
8
- * ## Why a queue at all, for a ten second undo
9
- *
10
- * Holding a message in memory for ten seconds would be simpler and would lose
11
- * mail. A restart during the hold - a deploy, a crash, `pm2 reload` - takes
12
- * the only copy with it, and the sender has already been told it is on its
13
- * way. Everything that has been accepted from a person is durable before they
14
- * are told it was accepted.
15
- *
16
- * ## Sent exactly once
17
- *
18
- * The claim is a conditional update in the store (`claimDueSends`), so a tick
19
- * that overruns into the next one cannot pick the same message up twice.
20
- * Everything after the claim is best-effort and reported; the claim itself is
21
- * the part that must be exact, because a duplicate message cannot be recalled.
22
- *
23
- * @module _lib/mail/scheduler
24
- */
1
+ /** CMS worker adapter for the shared scheduler. */
2
+ import {withMailAutomation} from './automationLock.js';
25
3
  import * as accounts from './accounts.js';
26
4
  import {sendMessage} from './send.js';
27
- import {describeError} from './imapPool.js';
28
-
29
- /** How often the ticker looks for work. */
30
- const TICK_MS = 5_000;
31
-
32
- /**
33
- * How many times a queued send is retried before it is given up on.
34
- *
35
- * A mail server that is briefly unreachable should not lose the message; one
36
- * that refuses it should not be asked forever. Three is enough for the first
37
- * and few enough for the second.
38
- */
39
- const MAX_ATTEMPTS = 3;
40
-
41
- /** How long to wait before trying a failed send again. */
42
- const RETRY_MS = 120_000;
43
-
44
- /**
45
- * The reason recorded on a queued item whose mailbox needs signing in again.
46
- *
47
- * @param {Error} err
48
- * @returns {string}
49
- */
50
- export function reconnectReason(err) {
51
- if (!err?.needsReconnect) return err?.message || 'The mailbox could not be used.';
52
- return `The mailbox needs signing in again (Mail Settings > Mailboxes > Reconnect): ${err.message}`;
53
- }
54
-
55
- /**
56
- * Create the scheduler.
57
- *
58
- * @param {{store: object, pool: object, config: object, logger: object,
59
- * tickMs?: number}} deps
60
- * @returns {{start: Function, stop: Function, runNow: Function}}
61
- */
62
- export function createScheduler({store, pool, config, logger, tickMs = TICK_MS}) {
63
- let timer = null;
64
- let stopped = false;
65
- let running = false;
66
-
67
- /**
68
- * Send one claimed message.
69
- *
70
- * @param {object} item
71
- * @returns {Promise<void>}
72
- */
73
- async function runSend(item) {
74
- const account = await accounts.getAccount(item.userId, item.accountId);
75
- if (!account) {
76
- // The mailbox was removed while this was queued. There is nothing
77
- // to send it from and never will be.
78
- await store.finishSend(item._id, {
79
- status: 'failed',
80
- error: 'That mailbox no longer exists.'
81
- });
82
- return;
83
- }
84
-
85
- // Built INSIDE the try: a signed-in mailbox whose sign-in is dead throws
86
- // here (OAuthReconnectError), and escaping would leave the claimed item
87
- // `sending` with no finishSend - picked up again on every reclaim.
88
- let smtp;
89
- try {
90
- smtp = accounts.toSmtpConnection(account, item.identityId ?? null);
91
- } catch (err) {
92
- await store.finishSend(item._id, {status: 'failed', error: reconnectReason(err)});
93
- return;
94
- }
95
- if (!smtp) {
96
- await store.finishSend(item._id, {
97
- status: 'failed',
98
- error: 'No outgoing server is configured for this mailbox.'
99
- });
100
- return;
101
- }
102
-
103
- try {
104
- const result = await sendMessage({
105
- smtp,
106
- account,
107
- store,
108
- draft: item.draft,
109
- pool,
110
- poolKey: `${item.userId}:${item.accountId}`,
111
- connection: accounts.toConnection(account),
112
- sentFolder: smtp.sentFolder,
113
- allowInsecureTLS: config.allowInsecureTLS === true,
114
- replaces: item.replaces ?? null
115
- });
116
- await store.finishSend(item._id, {status: 'sent', result, error: null});
117
- } catch (err) {
118
- // A dead sign-in will not fix itself between retries: fail now, so
119
- // the sender is told (the send-failed notice) instead of waiting.
120
- const giveUp = err?.needsReconnect || (item.attempts ?? 1) >= MAX_ATTEMPTS;
121
- await store.finishSend(item._id, giveUp
122
- // describeError: a queue item is read in the browser, and the mail
123
- // server's own words are for the log (they say what listens on a port).
124
- ? {status: 'failed', error: err?.needsReconnect ? reconnectReason(err) : describeError(err)}
125
- // Back to pending, a little later. `finishedAt` is set either
126
- // way, which is harmless on a retry and is what tells a
127
- // screen when the last attempt was.
128
- : {status: 'pending', at: new Date(Date.now() + RETRY_MS), error: describeError(err)});
129
-
130
- logger.warn(
131
- `[mail] queued send ${item._id} failed (attempt ${item.attempts}): ${err.message}`
132
- );
133
- }
134
- }
135
-
136
- /**
137
- * Bring one snoozed message back.
138
- *
139
- * Moved back where it came from and marked unread, because the whole
140
- * point of putting it away was to be shown it again - a message that
141
- * returns already read returns invisibly.
142
- *
143
- * @param {object} item
144
- * @returns {Promise<void>}
145
- */
146
- async function runWake(item) {
147
- const account = await accounts.getAccount(item.userId, item.accountId);
148
- if (!account) {
149
- await store.finishSnooze(item._id, {status: 'failed', error: 'That mailbox no longer exists.'});
150
- return;
151
- }
152
-
153
- const poolKey = `${item.userId}:${item.accountId}`;
154
- let connection;
155
-
156
- try {
157
- // Inside the try for the same reason as runSend: a dead sign-in throws here.
158
- connection = accounts.toConnection(account);
159
- // The UID the move reported, when the server has UIDPLUS. Without
160
- // it the message is found by its Message-ID instead - a snooze on
161
- // such a server is still a snooze, and refusing to bring it back
162
- // would be losing the message rather than delaying it.
163
- const uid = item.uid ?? await findByMessageId(poolKey, connection, item);
164
- if (uid === null) {
165
- throw new Error('That message is no longer in the snooze folder.');
166
- }
167
-
168
- // Unread first, then moved. The other order would be flagging a
169
- // UID that has just stopped existing in this folder.
170
- await pool.withMailbox(poolKey, connection, item.folder, client =>
171
- client.messageFlagsRemove({uid: String(uid)}, ['\\Seen'], {uid: true}),
172
- {writable: true});
173
-
174
- const {moveMessage} = await import('./write.js');
175
- const moved = await moveMessage({
176
- pool, store, account, poolKey, connection,
177
- folder: item.folder, uid, destination: item.returnTo
178
- });
179
-
180
- await store.finishSnooze(item._id, {
181
- status: 'woken', error: null, newUid: moved.newUid ?? null
182
- });
183
- } catch (err) {
184
- // Retried, not given up on. A mail server that is briefly
185
- // unreachable is an ordinary condition, and a snooze abandoned on
186
- // the first blip leaves the message parked in a folder the user
187
- // does not read, absent from the list that was supposed to bring
188
- // it back.
189
- const attempts = (item.attempts ?? 0) + 1;
190
- const giveUp = err?.needsReconnect || attempts >= MAX_ATTEMPTS;
191
- await store.finishSnooze(item._id, giveUp
192
- ? {status: 'failed', error: err?.needsReconnect ? `${reconnectReason(err)} The message is still in ${item.folder}.` : describeError(err), attempts}
193
- : {status: 'pending', at: new Date(Date.now() + RETRY_MS), error: describeError(err), attempts});
194
- logger.warn(
195
- `[mail] could not wake snoozed message ${item._id} (attempt ${attempts}): ${err.message}`
196
- );
197
- }
198
- }
199
-
200
- /**
201
- * Find a parked message by its Message-ID.
202
- *
203
- * The way back on a server with no UIDPLUS, which cannot report the UID a
204
- * moved message was given. A HEADER search is not fast, but the snooze
205
- * folder holds only what is waiting, and this runs once per message when
206
- * it comes due.
207
- *
208
- * @param {string} poolKey
209
- * @param {object} connection
210
- * @param {object} item
211
- * @returns {Promise<number|null>}
212
- */
213
- async function findByMessageId(poolKey, connection, item) {
214
- if (!item.messageId) return null;
215
- return pool.withMailbox(poolKey, connection, item.folder, async (client) => {
216
- const found = await client.search({header: {'message-id': item.messageId}}, {uid: true});
217
- // The newest match, in the vanishingly unlikely case a folder
218
- // holds two messages with one id.
219
- return found?.length ? Number(found[found.length - 1]) : null;
220
- });
221
- }
222
-
223
- /**
224
- * One pass over both queues.
225
- *
226
- * Guarded against overlapping itself: a slow mail server can make a send
227
- * take longer than the tick interval, and a second pass starting
228
- * underneath the first would double the connections without doubling the
229
- * throughput.
230
- *
231
- * @returns {Promise<void>}
232
- */
233
- async function tick() {
234
- if (stopped || running) return;
235
- running = true;
236
- try {
237
- for (const item of await store.claimDueSends()) {
238
- if (stopped) return;
239
- await runSend(item);
240
- }
241
- for (const item of await store.claimDueSnoozes()) {
242
- if (stopped) return;
243
- await runWake(item);
244
- }
245
- } catch (err) {
246
- // The store being unreachable is an ordinary condition here -
247
- // Mongo restarting, say - and the next tick will try again.
248
- logger.warn(`[mail] scheduler tick failed: ${err.message}`);
249
- } finally {
250
- running = false;
251
- }
252
- }
253
-
254
- return {
255
- /**
256
- * @returns {void}
257
- */
258
- start() {
259
- if (timer) return;
260
- stopped = false;
261
- timer = setInterval(() => {
262
- tick().catch(err => logger.warn(`[mail] scheduler tick failed: ${err.message}`));
263
- }, tickMs);
264
- timer.unref?.();
265
- },
266
-
267
- /**
268
- * @returns {void}
269
- */
270
- stop() {
271
- stopped = true;
272
- if (timer) clearInterval(timer);
273
- timer = null;
274
- },
275
-
276
- /**
277
- * Run a pass immediately - used by "send it now" on a queued message.
278
- *
279
- * @returns {Promise<void>}
280
- */
281
- runNow: tick
5
+ import {createScheduler as createRuntime, reconnectReason} from './schedulerRuntime.js';
6
+ export {reconnectReason};
7
+ export function createScheduler(options) {
8
+ const invalidateWake = async ({account, item}) => {
9
+ for (const path of [item.folder, item.returnTo]) try {await options.store.saveFolder?.(account.id, path, {lastSyncAt: null});} catch { /* IMAP remains authoritative. */ }
282
10
  };
11
+ return createRuntime({...options, accounts, sendMessage,
12
+ withAccount: (account, action) => withMailAutomation(account.id, action),
13
+ beforeWake: invalidateWake, afterWake: invalidateWake
14
+ });
283
15
  }
@@ -0,0 +1,259 @@
1
+ // Source: @domma-mail/core 0.18.0, packages/core/src/mail/schedulerRuntime.js.
2
+ // Update with domma-mail/scripts/sync-cms.mjs; edit the shared source.
3
+ /**
4
+ * The worker behind "send later", "undo send" and "snooze".
5
+ *
6
+ * One ticker, two queues, for the same reason the poller is one ticker rather
7
+ * than a timer per mailbox: the work is small, the queues are short, and a
8
+ * timer per queued message is a timer to cancel when the message is cancelled.
9
+ *
10
+ * ## Why a queue at all, for a ten second undo
11
+ *
12
+ * Holding a message in memory for ten seconds would be simpler and would lose
13
+ * mail. A restart during the hold - a deploy, a crash, `pm2 reload` - takes
14
+ * the only copy with it, and the sender has already been told it is on its
15
+ * way. Everything that has been accepted from a person is durable before they
16
+ * are told it was accepted.
17
+ *
18
+ * ## Claims and delivery acknowledgement
19
+ *
20
+ * The claim is a conditional update in the store (`claimDueSends`), so a tick
21
+ * that overruns into the next one cannot pick the same message up twice.
22
+ * An SMTP acknowledgement can be lost after delivery. Such attempts need
23
+ * inspection and must never be retried automatically.
24
+ *
25
+ * @module _lib/mail/scheduler
26
+ */
27
+ import {describeError as defaultDescribeError} from './imapPoolRuntime.js';
28
+ import {wakeSnoozedMessage} from './snoozeRuntime.js';
29
+ import {normaliseIdentityList} from '../admin/mail/identity.js';
30
+
31
+ /** How often the ticker looks for work. */
32
+ const TICK_MS = 5_000;
33
+
34
+ /**
35
+ * How many times a queued send is retried before it is given up on.
36
+ *
37
+ * A mail server that is briefly unreachable should not lose the message; one
38
+ * that refuses it should not be asked forever. Three is enough for the first
39
+ * and few enough for the second.
40
+ */
41
+ const MAX_ATTEMPTS = 3;
42
+
43
+ /** How long to wait before trying a failed send again. */
44
+ const RETRY_MS = 120_000;
45
+
46
+ /**
47
+ * The reason recorded on a queued item whose mailbox needs signing in again.
48
+ *
49
+ * @param {Error} err
50
+ * @returns {string}
51
+ */
52
+ export function reconnectReason(err) {
53
+ if (!err?.needsReconnect) return err?.message || 'The mailbox could not be used.';
54
+ return `The mailbox needs signing in again (Mail Settings > Mailboxes > Reconnect): ${err.message}`;
55
+ }
56
+
57
+ /**
58
+ * Create the scheduler.
59
+ *
60
+ * @param {{store: object, pool: object, accounts: object, sendMessage: Function,
61
+ * config?: object, logger?: object, tickMs?: number, sends?: boolean,
62
+ * snoozes?: boolean, describeError?: Function, withAccount?: Function,
63
+ * beforeWake?: Function, afterWake?: Function}} deps
64
+ * @returns {{start: Function, stop: Function, runNow: Function}}
65
+ */
66
+ export function createScheduler({store, pool, accounts, sendMessage, config = {}, logger = {warn() {}}, tickMs = TICK_MS,
67
+ describeError = defaultDescribeError, sends = true, snoozes = true, withAccount = (account, action) => action(), beforeWake = async () => {}, afterWake = async () => {}}) {
68
+ if (!accounts || typeof sendMessage !== 'function') throw new Error('Scheduler requires account and sending services.');
69
+ let timer = null;
70
+ let stopped = false;
71
+ let active = null;
72
+
73
+ /**
74
+ * Send one claimed message.
75
+ *
76
+ * @param {object} item
77
+ * @returns {Promise<void>}
78
+ */
79
+ async function runSend(item) {
80
+ return withAccount({id: item.accountId, userId: item.userId}, async () => {
81
+ const account = await accounts.getAccount(item.userId, item.accountId);
82
+ if (!account) {
83
+ // The mailbox was removed while this was queued. There is nothing
84
+ // to send it from and never will be.
85
+ await store.finishSend(item._id, {
86
+ status: 'failed',
87
+ error: 'That mailbox no longer exists.'
88
+ });
89
+ return;
90
+ }
91
+ if (item.identityId && Array.isArray(account.identities) && !normaliseIdentityList(account).some(identity => identity.id === item.identityId)) {
92
+ await store.finishSend(item._id, {status: 'failed', error: 'The selected sender identity no longer exists. Restore it before retrying.'});
93
+ return;
94
+ }
95
+
96
+ // Built INSIDE the try: a signed-in mailbox whose sign-in is dead throws
97
+ // here (OAuthReconnectError), and escaping would leave the claimed item
98
+ // `sending` with no finishSend and an ambiguous result.
99
+ let smtp;
100
+ try {
101
+ smtp = accounts.toSmtpConnection(account, item.identityId ?? null);
102
+ } catch (err) {
103
+ await store.finishSend(item._id, {status: 'failed', error: reconnectReason(err)});
104
+ return;
105
+ }
106
+ if (!smtp) {
107
+ await store.finishSend(item._id, {
108
+ status: 'failed',
109
+ error: 'No outgoing server is configured for this mailbox.'
110
+ });
111
+ return;
112
+ }
113
+
114
+ try {
115
+ const result = await sendMessage({
116
+ smtp,
117
+ account,
118
+ store,
119
+ draft: item.draft,
120
+ pool,
121
+ poolKey: `${item.userId}:${item.accountId}`,
122
+ connection: accounts.toConnection(account),
123
+ sentFolder: smtp.sentFolder,
124
+ allowInsecureTLS: config.allowInsecureTLS === true,
125
+ replaces: item.replaces ?? null
126
+ });
127
+ // Completion persistence is outside the delivery catch. A DB failure
128
+ // after SMTP success must leave an ambiguous claim, never a retry.
129
+ return {result};
130
+ } catch (err) {
131
+ // A dead sign-in will not fix itself between retries: fail now, so
132
+ // the sender is told (the send-failed notice) instead of waiting.
133
+ const giveUp = err?.needsReconnect || err?.retryable !== true || (item.attempts ?? 1) >= MAX_ATTEMPTS;
134
+ await store.finishSend(item._id, giveUp
135
+ // describeError: a queue item is read in the browser, and the mail
136
+ // server's own words are for the log (they say what listens on a port).
137
+ ? {status: 'failed', deliveryUnknown: err?.deliveryUnknown === true, error: err?.deliveryUnknown ? 'Delivery could not be confirmed. Check Sent and the recipient before sending again.' : err?.needsReconnect ? reconnectReason(err) : describeError(err)}
138
+ // Back to pending, a little later. `finishedAt` is set either
139
+ // way, which is harmless on a retry and is what tells a
140
+ // screen when the last attempt was.
141
+ : {status: 'pending', at: new Date(Date.now() + RETRY_MS), error: describeError(err)});
142
+
143
+ logger.warn(
144
+ `[mail] queued send ${item._id} failed (attempt ${item.attempts}): ${err.message}`
145
+ );
146
+ }
147
+ }).then(async completed => {
148
+ if (completed) await store.finishSend(item._id, {status: 'sent', result: completed.result,
149
+ error: completed.result?.fileError ? 'Sent, but the Sent copy could not be filed. Do not resend.' : null, deliveryUnknown: false});
150
+ });
151
+ }
152
+
153
+ /**
154
+ * Bring one snoozed message back.
155
+ *
156
+ * Moved back where it came from and marked unread, because the whole
157
+ * point of putting it away was to be shown it again - a message that
158
+ * returns already read returns invisibly.
159
+ *
160
+ * @param {object} item
161
+ * @returns {Promise<void>}
162
+ */
163
+ async function runWake(item) {
164
+ return withAccount({id: item.accountId, userId: item.userId}, async () => {
165
+ const account = await accounts.getAccount(item.userId, item.accountId);
166
+ if (!account) {
167
+ await store.finishSnooze(item._id, {status: 'failed', error: 'That mailbox no longer exists.'});
168
+ return;
169
+ }
170
+ let attempted = false;
171
+ let result;
172
+ try {
173
+ await beforeWake({account, item});
174
+ result = await wakeSnoozedMessage({pool, account, poolKey: `${item.userId}:${item.accountId}`,
175
+ connection: accounts.toConnection(account), item, beforeMove: () => {attempted = true;}});
176
+ } catch (error) {
177
+ const inspection = attempted || error.snoozeAttention === true;
178
+ const attempts = Math.max(1, item.attempts ?? 1);
179
+ const giveUp = inspection || error.needsReconnect || attempts >= MAX_ATTEMPTS;
180
+ await store.finishSnooze(item._id, giveUp
181
+ ? {status: 'failed', requiresInspection: inspection, error: inspection
182
+ ? `The message could not be brought back safely. Check ${item.folder} and ${item.returnTo} manually.`
183
+ : error.needsReconnect ? `${reconnectReason(error)} The message is still in ${item.folder}.` : describeError(error)}
184
+ : {status: 'pending', at: new Date(Date.now() + RETRY_MS), error: describeError(error)});
185
+ logger.warn(`[mail] could not wake snoozed message ${item._id}: ${error.message}`);
186
+ return;
187
+ }
188
+ // A completed MOVE must never be replayed because its database
189
+ // acknowledgement or cache cleanup failed.
190
+ await afterWake({account, item, result});
191
+ await store.finishSnooze(item._id, {status: 'woken', error: null, requiresInspection: false, newUid: result.newUid ?? null});
192
+ });
193
+ }
194
+
195
+ /**
196
+ * One pass over both queues.
197
+ *
198
+ * Guarded against overlapping itself: a slow mail server can make a send
199
+ * take longer than the tick interval, and a second pass starting
200
+ * underneath the first would double the connections without doubling the
201
+ * throughput.
202
+ *
203
+ * @returns {Promise<void>}
204
+ */
205
+ async function pass() {
206
+ if (stopped) return;
207
+ try {
208
+ // Claim only the item about to run. Shutdown must not strand the
209
+ // rest of a batch in sending before it ever reached SMTP.
210
+ if (sends) for (let count = 0; count < 10 && !stopped; count++) {
211
+ const [item] = await store.claimDueSends(Date.now(), 1);
212
+ if (!item) break;
213
+ await runSend(item);
214
+ }
215
+ if (snoozes) for (let count = 0; count < 20 && !stopped; count++) {
216
+ const [item] = await store.claimDueSnoozes(Date.now(), 1);
217
+ if (!item) break;
218
+ await runWake(item);
219
+ }
220
+ } catch (err) {
221
+ logger.warn(`[mail] scheduler tick failed: ${err.message}`);
222
+ }
223
+ }
224
+
225
+ function tick() {
226
+ if (stopped) return Promise.resolve();
227
+ if (!active) active = pass().finally(() => {active = null;});
228
+ return active;
229
+ }
230
+
231
+ return {
232
+ /**
233
+ * @returns {void}
234
+ */
235
+ start() {
236
+ if (timer) return;
237
+ stopped = false;
238
+ timer = setInterval(() => {
239
+ tick().catch(err => logger.warn(`[mail] scheduler tick failed: ${err.message}`));
240
+ }, tickMs);
241
+ timer.unref?.();
242
+ },
243
+
244
+ /** Stop claiming work and drain the active attempt. @returns {Promise<void>} */
245
+ stop() {
246
+ stopped = true;
247
+ if (timer) clearInterval(timer);
248
+ timer = null;
249
+ return active ?? Promise.resolve();
250
+ },
251
+
252
+ /**
253
+ * Run a pass immediately - used by "send it now" on a queued message.
254
+ *
255
+ * @returns {Promise<void>}
256
+ */
257
+ runNow: tick
258
+ };
259
+ }