@wtfalch/email 0.19.1 → 0.20.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -660,7 +660,7 @@ implicit TLS, user `lettermint`, the token as a `Value` secret) and rebuilds
660
660
  other sender is delivered direct (route `'mx'`). The expression always starts
661
661
  with the rule that delivers a recipient on a hosted domain to its mailbox
662
662
  (route `'local'`), whoever the sender is. `removeOrgRelay(client,
663
- { slug })` deletes the route and rebuilds; a missing route sends nothing.
663
+ { slug })` deletes the route and rebuilds; a missing route removes nothing and only repairs an outdated expression.
664
664
  `hasOrgRelay(client, { slug })` is true when the route holds a secret, so a
665
665
  caller knows whether it needs a fresh token. The domain is kept in the route's
666
666
  description, and the expression is rebuilt from the routes that exist, never
@@ -65,7 +65,7 @@ export interface PlatformMailSettingsInput {
65
65
  }
66
66
  /**
67
67
  * The platform's own mail settings: Stalwart's default hostname and an OIDC
68
- * sign-in directory, and nothing else. `mailObjects` cannot stand in for
68
+ * sign-in directory, and the local-delivery route and expression. `mailObjects` cannot stand in for
69
69
  * this — it also writes an `AcmeProvider` and a `DnsServer`, neither of which the platform step wants.
70
70
  *
71
71
  * A blank `mailHost`, `apex`, `oidc.issuerUrl` or `oidc.audience` throws,
@@ -66,9 +66,30 @@ function validatedClaimUsername(raw) {
66
66
  return 'preferred_username';
67
67
  return requireNonBlank(raw, 'oidc.claimUsername');
68
68
  }
69
+ /**
70
+ * The two objects that deliver a recipient on a hosted domain to its mailbox.
71
+ * The route expression names the `local` route for every local recipient. If
72
+ * the route is missing, Stalwart falls back to the MX lookup without an error.
73
+ */
74
+ function localDeliveryObjects() {
75
+ return [
76
+ {
77
+ key: 'local',
78
+ object: 'MtaRoute',
79
+ match: { name: LOCAL_ROUTE },
80
+ value: { '@type': 'Local', name: LOCAL_ROUTE },
81
+ },
82
+ {
83
+ key: 'outbound',
84
+ object: 'MtaOutboundStrategy',
85
+ match: { id: 'singleton' },
86
+ value: { route: routeExpression([]) },
87
+ },
88
+ ];
89
+ }
69
90
  /**
70
91
  * The platform's own mail settings: Stalwart's default hostname and an OIDC
71
- * sign-in directory, and nothing else. `mailObjects` cannot stand in for
92
+ * sign-in directory, and the local-delivery route and expression. `mailObjects` cannot stand in for
72
93
  * this — it also writes an `AcmeProvider` and a `DnsServer`, neither of which the platform step wants.
73
94
  *
74
95
  * A blank `mailHost`, `apex`, `oidc.issuerUrl` or `oidc.audience` throws,
@@ -102,6 +123,7 @@ export function platformMailSettingsObjects(input) {
102
123
  match: { id: 'singleton' },
103
124
  value: { directoryId: ref('oidc') },
104
125
  },
126
+ ...localDeliveryObjects(),
105
127
  {
106
128
  key: 'reload',
107
129
  object: 'Action',
@@ -176,20 +198,7 @@ export function mailObjects(i) {
176
198
  ...(i.oidc ? { directoryId: ref('oidc') } : {}),
177
199
  },
178
200
  },
179
- {
180
- // The route expression names this route for every local recipient. If
181
- // it is missing, Stalwart falls back to the MX lookup without an error.
182
- key: 'local',
183
- object: 'MtaRoute',
184
- match: { name: LOCAL_ROUTE },
185
- value: { '@type': 'Local', name: LOCAL_ROUTE },
186
- },
187
- {
188
- key: 'outbound',
189
- object: 'MtaOutboundStrategy',
190
- match: { id: 'singleton' },
191
- value: { route: routeExpression([]) },
192
- },
201
+ ...localDeliveryObjects(),
193
202
  {
194
203
  key: 'system',
195
204
  object: 'SystemSettings',
@@ -274,10 +283,13 @@ export async function applyObjects(client, plan, log) {
274
283
  // The match properties identified the object, so they are equal already;
275
284
  // they are also where immutable properties live (`name`), and the server
276
285
  // refuses an update that mentions one. They stay out of the patch.
277
- const patch = Object.fromEntries(Object.entries(value).filter(([k]) => !(k in p.match)));
286
+ const changes = Object.entries(value).filter(([k]) => !(k in p.match));
287
+ // A patch of only `@type` changes nothing, so an existing object gets no update.
288
+ const patch = changes.every(([k]) => k === '@type') ? {} : Object.fromEntries(changes);
278
289
  const { id, created } = await client.upsert(p.object, (existing) => entries.every(([k, v]) => existing[k] === v), value, patch);
279
290
  ids[p.key] = id;
280
- log(`${p.object}: ${created ? 'created' : 'updated'} (${id})`);
291
+ const outcome = created ? 'created' : Object.keys(patch).length > 0 ? 'updated' : 'unchanged';
292
+ log(`${p.object}: ${outcome} (${id})`);
281
293
  }
282
294
  return ids;
283
295
  }
@@ -195,7 +195,7 @@ export declare function outboundRoute(client: StalwartClient): Promise<Record<st
195
195
  * entry in the route expression.
196
196
  */
197
197
  export declare function applyOrgRelay(client: StalwartClient, input: OrgRelayInput): Promise<void>;
198
- /** Remove an org's relay. A missing route is a no-op: nothing is sent. */
198
+ /** Remove an org's relay. A missing route removes nothing, and a server with an outdated expression is still repaired. */
199
199
  export declare function removeOrgRelay(client: StalwartClient, org: {
200
200
  readonly slug: string;
201
201
  }): Promise<void>;
@@ -185,6 +185,7 @@ export async function applyOrgMail(client, org, options) {
185
185
  else {
186
186
  id = await client.create('Domain', value);
187
187
  }
188
+ await repairRoute(client);
188
189
  const [wire] = await client.get('Domain', [id]);
189
190
  const records = [
190
191
  ...mxAndSpf(domain, org.mode, options),
@@ -280,12 +281,36 @@ async function rebuildRoute(client) {
280
281
  // falls back to the MX lookup for its own recipients, without an error.
281
282
  const routes = await client.list('MtaRoute');
282
283
  if (!routes.some((r) => r.name === LOCAL_ROUTE)) {
283
- await client.create('MtaRoute', { '@type': 'Local', name: LOCAL_ROUTE });
284
+ try {
285
+ await client.create('MtaRoute', { '@type': 'Local', name: LOCAL_ROUTE });
286
+ }
287
+ catch (error) {
288
+ // Another call may have made it at the same moment.
289
+ const now = await client.list('MtaRoute');
290
+ if (!now.some((r) => r.name === LOCAL_ROUTE))
291
+ throw error;
292
+ }
284
293
  }
285
294
  const route = await outboundRoute(client);
286
295
  await client.update('MtaOutboundStrategy', 'singleton', { route });
287
296
  await client.create('Action', { '@type': 'ReloadSettings' });
288
297
  }
298
+ /**
299
+ * Rewrite the route expression when it is not the one this version writes. A
300
+ * server last written by a version before 0.19.1 has no local-delivery rule,
301
+ * and nothing else rewrites the expression while every relay is healthy.
302
+ */
303
+ async function repairRoute(client) {
304
+ const [strategy] = await client.get('MtaOutboundStrategy', [
305
+ 'singleton',
306
+ ]);
307
+ const routes = await client.list('MtaRoute');
308
+ const wanted = await outboundRoute(client);
309
+ if (!routes.some((r) => r.name === LOCAL_ROUTE) ||
310
+ JSON.stringify(strategy?.route) !== JSON.stringify(wanted)) {
311
+ await rebuildRoute(client);
312
+ }
313
+ }
289
314
  /**
290
315
  * Give an org its own Lettermint relay, or replace its token. Idempotent: the
291
316
  * route is upserted by name, so calling it twice leaves one route and one
@@ -316,12 +341,14 @@ export async function applyOrgRelay(client, input) {
316
341
  await client.create('MtaRoute', value);
317
342
  await rebuildRoute(client);
318
343
  }
319
- /** Remove an org's relay. A missing route is a no-op: nothing is sent. */
344
+ /** Remove an org's relay. A missing route removes nothing, and a server with an outdated expression is still repaired. */
320
345
  export async function removeOrgRelay(client, org) {
321
346
  const name = relayName(org.slug);
322
347
  const existing = (await listRelays(client)).find((r) => r.name === name);
323
- if (!existing)
348
+ if (!existing) {
349
+ await repairRoute(client);
324
350
  return;
351
+ }
325
352
  const { notDestroyed } = await client.destroy('MtaRoute', [existing.id]);
326
353
  const failure = notDestroyed[existing.id];
327
354
  if (failure)
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@wtfalch/email",
3
- "version": "0.19.1",
3
+ "version": "0.20.0",
4
4
  "description": "The wtfalch estate: reading a mailbox over JMAP, administering the Stalwart server it lives on, and iTIP scheduling over iMIP. Three entries with no code in common.",
5
5
  "license": "MIT",
6
6
  "type": "module",