@pithy-sh/email 0.2.0 → 0.3.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/dist/send/errorMapping.d.ts +27 -3
- package/dist/send/errorMapping.d.ts.map +1 -1
- package/dist/send/errorMapping.js +71 -9
- package/dist/send/runSend.d.ts.map +1 -1
- package/dist/send/runSend.js +3 -3
- package/dist/version.generated.d.ts +1 -1
- package/dist/version.generated.js +1 -1
- package/package.json +1 -1
- package/src/send/errorMapping.ts +92 -11
- package/src/send/runSend.ts +7 -3
- package/src/version.generated.ts +1 -1
|
@@ -10,8 +10,23 @@ import type { PithyError } from "@pithy-sh/core/src/error/pithyError";
|
|
|
10
10
|
*/
|
|
11
11
|
/** How a given send error is handled: which Pithy error to raise, and whether the send Workflow retries. */
|
|
12
12
|
export interface ClassifiedSendError {
|
|
13
|
-
/** The `E_*` code reported by the binding, or `E_UNKNOWN`
|
|
13
|
+
/** The `E_*` code reported by the binding, a numeric provider code as a string, or `E_UNKNOWN` for none. */
|
|
14
14
|
code: string;
|
|
15
|
+
/**
|
|
16
|
+
* The cause, as one operator-facing line: the code and whatever the provider said with it.
|
|
17
|
+
*
|
|
18
|
+
* **Exposed because the job row needs it and only the error object had it (pithy-sh/pithy#555).**
|
|
19
|
+
* `runSend` persisted the bare `code` into `pithy_email_jobs.error`, so a magic link that failed five
|
|
20
|
+
* times against a token for the wrong account recorded `E_UNKNOWN` five times and nothing about why —
|
|
21
|
+
* while this exact string, naming `10000 Authentication error`, was being built two lines down and
|
|
22
|
+
* thrown away with the error it decorated. Same family as #534: a failure that discards the cause it
|
|
23
|
+
* was handed.
|
|
24
|
+
*
|
|
25
|
+
* Identical to `error.payload.detail`, deliberately — one composition, two readers, so the row and the
|
|
26
|
+
* log cannot drift. `detail` is stripped at the client boundary, which is where a provider's own words
|
|
27
|
+
* belong.
|
|
28
|
+
*/
|
|
29
|
+
detail: string;
|
|
15
30
|
/** Whether the send should be retried with backoff. */
|
|
16
31
|
retryable: boolean;
|
|
17
32
|
/** Whether the failure means the recipient is suppressed (so the address should be locally suppressed). */
|
|
@@ -22,8 +37,17 @@ export interface ClassifiedSendError {
|
|
|
22
37
|
/**
|
|
23
38
|
* Classify a send failure. `E_RECIPIENT_SUPPRESSED` is terminal and means the address must be
|
|
24
39
|
* suppressed locally too; rate/quota and transient delivery codes are retryable; everything else
|
|
25
|
-
* (validation, sender, content, headers) is terminal.
|
|
26
|
-
*
|
|
40
|
+
* (validation, sender, content, headers) is terminal.
|
|
41
|
+
*
|
|
42
|
+
* **An unrecognized code is retryable, and that is deliberately unchanged.** A failure this module has
|
|
43
|
+
* no code at all keeps its bounded retry, and so does a *numeric* provider code nobody here has listed —
|
|
44
|
+
* see {@link isProviderNumericCode} for why those two are alike and an unlisted `E_*` is not.
|
|
45
|
+
*
|
|
46
|
+
* What changed for #555 is that the **authentication** class is now named and terminal: `10000
|
|
47
|
+
* Authentication error` is a token that cannot send as this domain, and spending five attempts on it in
|
|
48
|
+
* silence is what hid the whole incident. See {@link UNAUTHORIZED} for why that is a list rather than
|
|
49
|
+
* "numeric means permanent" — the latter was this fix's first shape, and it made a momentary numeric
|
|
50
|
+
* failure permanent as a side effect.
|
|
27
51
|
*/
|
|
28
52
|
export declare function classifySendError(err: unknown): ClassifiedSendError;
|
|
29
53
|
//# sourceMappingURL=errorMapping.d.ts.map
|
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"errorMapping.d.ts","sourceRoot":"","sources":["../../src/send/errorMapping.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,qCAAqC,CAAC;AAGtE;;;;;;GAMG;AAEH,4GAA4G;AAC5G,MAAM,WAAW,mBAAmB;IAClC,
|
|
1
|
+
{"version":3,"file":"errorMapping.d.ts","sourceRoot":"","sources":["../../src/send/errorMapping.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,qCAAqC,CAAC;AAGtE;;;;;;GAMG;AAEH,4GAA4G;AAC5G,MAAM,WAAW,mBAAmB;IAClC,4GAA4G;IAC5G,IAAI,EAAE,MAAM,CAAC;IACb;;;;;;;;;;;;;OAaG;IACH,MAAM,EAAE,MAAM,CAAC;IACf,uDAAuD;IACvD,SAAS,EAAE,OAAO,CAAC;IACnB,2GAA2G;IAC3G,UAAU,EAAE,OAAO,CAAC;IACpB,qFAAqF;IACrF,KAAK,EAAE,UAAU,CAAC;CACnB;AAsED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,iBAAiB,CAAC,GAAG,EAAE,OAAO,GAAG,mBAAmB,CA6BnE"}
|
|
@@ -11,41 +11,103 @@ const RETRYABLE = /* @__PURE__ */ new Set([
|
|
|
11
11
|
]);
|
|
12
12
|
/** Rate/quota codes map to the dedicated 429 error so the cause reads clearly in logs. */
|
|
13
13
|
const RATE_LIMITED = /* @__PURE__ */ new Set(["E_RATE_LIMIT_EXCEEDED", "E_DAILY_LIMIT_EXCEEDED"]);
|
|
14
|
-
/**
|
|
14
|
+
/**
|
|
15
|
+
* Codes that mean **this Worker could not authenticate** — terminal, because no retry clears a credential.
|
|
16
|
+
*
|
|
17
|
+
* `10000` is Cloudflare's own: a token that is alive but not scoped for Email Sending, or scoped for an
|
|
18
|
+
* account that does not own the sending domain, is answered `{ code: 10000, message: "Authentication
|
|
19
|
+
* error" }` (#534 captured the body; `liveSend.integration.test.ts` documents the same rejection for a
|
|
20
|
+
* general account token). That is the exact failure #555 spent five attempts on in silence.
|
|
21
|
+
*
|
|
22
|
+
* **Named rather than inferred from the code being numeric.** Treating every numeric code as terminal was
|
|
23
|
+
* the first shape of this fix and it bought the auth case by making a *momentary* numeric failure
|
|
24
|
+
* permanent too — one attempt, `status: "failed"`, where the retry budget used to apply. A code nobody
|
|
25
|
+
* here recognizes is still unknown, whichever alphabet it is written in, and unknown has earned its
|
|
26
|
+
* bounded retry since the module was written. So the auth class is listed, and the rule below is
|
|
27
|
+
* unchanged for everything else.
|
|
28
|
+
*/
|
|
29
|
+
const UNAUTHORIZED = /* @__PURE__ */ new Set([
|
|
30
|
+
"10000",
|
|
31
|
+
"E_UNAUTHORIZED",
|
|
32
|
+
"E_FORBIDDEN"
|
|
33
|
+
]);
|
|
34
|
+
/**
|
|
35
|
+
* Whether a code is one of Cloudflare's numeric ones rather than the binding's `E_*` spelling.
|
|
36
|
+
*
|
|
37
|
+
* The distinction decides the retry, so it is a predicate rather than a guess at the call site. An `E_*`
|
|
38
|
+
* code this module does not list stays **terminal**, exactly as it always has — the binding's documented
|
|
39
|
+
* unknowns are validation, sender, content and header faults, and retrying one cannot help. A *numeric*
|
|
40
|
+
* code this module does not list is retryable, because it arrives from the account/REST layer where a
|
|
41
|
+
* momentary fault is ordinary and nothing here has an opinion yet.
|
|
42
|
+
*/
|
|
43
|
+
function isProviderNumericCode(code) {
|
|
44
|
+
return /^[0-9]+$/.test(code);
|
|
45
|
+
}
|
|
46
|
+
/**
|
|
47
|
+
* Read a thrown value's `.code`/`.message` without assuming its shape.
|
|
48
|
+
*
|
|
49
|
+
* **A numeric code counts, and that is not a detail.** The Email Service binding surfaces `E_*` strings,
|
|
50
|
+
* but the REST path and the account layer behind it answer with Cloudflare's own numeric codes — an
|
|
51
|
+
* unauthorized send is `{ code: 10000, message: "Authentication error" }` (#534 captured the body). Read
|
|
52
|
+
* as "no code" that became `E_UNKNOWN`, which is both silent *and* retryable, so a credential fault
|
|
53
|
+
* consumed every attempt without ever naming itself (#555).
|
|
54
|
+
*
|
|
55
|
+
* **And a value with neither field still leaves a trace.** `String(err)` rather than `""`: an opaque
|
|
56
|
+
* throw is the case where the operator has least to go on, so an empty string is the one answer that
|
|
57
|
+
* cannot help. `E_UNKNOWN` remains the code — it means *nothing named itself*, which is the fact that
|
|
58
|
+
* earns the bounded retry.
|
|
59
|
+
*/
|
|
15
60
|
function readError(err) {
|
|
16
|
-
if (err && typeof err === "object")
|
|
17
|
-
|
|
18
|
-
|
|
19
|
-
|
|
61
|
+
if (err && typeof err === "object") {
|
|
62
|
+
const raw = "code" in err ? err.code : void 0;
|
|
63
|
+
const code = typeof raw === "string" && raw !== "" ? raw : typeof raw === "number" ? String(raw) : "E_UNKNOWN";
|
|
64
|
+
const named = "message" in err && typeof err.message === "string" ? err.message : "";
|
|
65
|
+
return {
|
|
66
|
+
code,
|
|
67
|
+
message: named !== "" ? named : code === "E_UNKNOWN" ? String(err) : ""
|
|
68
|
+
};
|
|
69
|
+
}
|
|
20
70
|
return {
|
|
21
71
|
code: "E_UNKNOWN",
|
|
22
|
-
message: typeof err === "string" ? err :
|
|
72
|
+
message: typeof err === "string" ? err : String(err)
|
|
23
73
|
};
|
|
24
74
|
}
|
|
25
75
|
/**
|
|
26
76
|
* Classify a send failure. `E_RECIPIENT_SUPPRESSED` is terminal and means the address must be
|
|
27
77
|
* suppressed locally too; rate/quota and transient delivery codes are retryable; everything else
|
|
28
|
-
* (validation, sender, content, headers) is terminal.
|
|
29
|
-
*
|
|
78
|
+
* (validation, sender, content, headers) is terminal.
|
|
79
|
+
*
|
|
80
|
+
* **An unrecognized code is retryable, and that is deliberately unchanged.** A failure this module has
|
|
81
|
+
* no code at all keeps its bounded retry, and so does a *numeric* provider code nobody here has listed —
|
|
82
|
+
* see {@link isProviderNumericCode} for why those two are alike and an unlisted `E_*` is not.
|
|
83
|
+
*
|
|
84
|
+
* What changed for #555 is that the **authentication** class is now named and terminal: `10000
|
|
85
|
+
* Authentication error` is a token that cannot send as this domain, and spending five attempts on it in
|
|
86
|
+
* silence is what hid the whole incident. See {@link UNAUTHORIZED} for why that is a list rather than
|
|
87
|
+
* "numeric means permanent" — the latter was this fix's first shape, and it made a momentary numeric
|
|
88
|
+
* failure permanent as a side effect.
|
|
30
89
|
*/
|
|
31
90
|
function classifySendError(err) {
|
|
32
91
|
const { code, message } = readError(err);
|
|
33
92
|
const detail = `email send failed: ${code}${message ? ` — ${message}` : ""}`;
|
|
34
93
|
if (code === "E_RECIPIENT_SUPPRESSED") return {
|
|
35
94
|
code,
|
|
95
|
+
detail,
|
|
36
96
|
retryable: false,
|
|
37
97
|
suppressed: true,
|
|
38
98
|
error: new EmailSuppressedError({ detail }, { cause: err })
|
|
39
99
|
};
|
|
40
100
|
if (RATE_LIMITED.has(code)) return {
|
|
41
101
|
code,
|
|
102
|
+
detail,
|
|
42
103
|
retryable: true,
|
|
43
104
|
suppressed: false,
|
|
44
105
|
error: new EmailRateLimitedError({ detail }, { cause: err })
|
|
45
106
|
};
|
|
46
107
|
return {
|
|
47
108
|
code,
|
|
48
|
-
|
|
109
|
+
detail,
|
|
110
|
+
retryable: RETRYABLE.has(code) || code === "E_UNKNOWN" || isProviderNumericCode(code) && !UNAUTHORIZED.has(code),
|
|
49
111
|
suppressed: false,
|
|
50
112
|
error: new EmailSendFailedError({ detail }, { cause: err })
|
|
51
113
|
};
|
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"runSend.d.ts","sourceRoot":"","sources":["../../src/send/runSend.ts"],"names":[],"mappings":"AASA,OAAO,KAAK,EAAE,cAAc,EAAE,iBAAiB,EAAE,MAAM,eAAe,CAAC;AACvE,OAAO,KAAK,EAAE,aAAa,EAAE,wBAAwB,EAAe,MAAM,gBAAgB,CAAC;AAE3F,OAAO,EAAE,KAAK,kBAAkB,EAAmC,MAAM,uBAAuB,CAAC;AACjG,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,oBAAoB,CAAC;AAGrD,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,UAAU,CAAC;AAG5C;;;;;;;;;;;;;;;;;;GAkBG;AAEH,kGAAkG;AAClG,MAAM,WAAW,WAAW;IAC1B,qCAAqC;IACrC,GAAG,EAAE,MAAM,CAAC;IACZ,oEAAoE;IACpE,GAAG,EAAE,MAAM,CAAC;CACb;AAED,yDAAyD;AACzD,MAAM,WAAW,QAAQ;IACvB,gDAAgD;IAChD,EAAE,EAAE,aAAa,CAAC;IAClB,sGAAsG;IACtG,aAAa,EAAE,wBAAwB,CAAC;IACxC,MAAM,EAAE,WAAW,CAAC;IACpB,KAAK,EAAE,UAAU,CAAC;IAClB;;;;;;;OAOG;IACH,SAAS,CAAC,EAAE,kBAAkB,CAAC;IAC/B,8CAA8C;IAC9C,OAAO,EAAE,MAAM,CAAC;IAChB,6GAA6G;IAC7G,OAAO,CAAC,EAAE,WAAW,CAAC;IACtB,2CAA2C;IAC3C,WAAW,EAAE,MAAM,CAAC;IACpB,qEAAqE;IACrE,WAAW,EAAE,MAAM,CAAC;IACpB,iHAAiH;IACjH,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB;;;;;;;;;;;;OAYG;IACH,aAAa,EAAE,IAAI,CAAC;IACpB;;;;;;;;;;;;;OAaG;IACH,WAAW,EAAE,MAAM,IAAI,CAAC;CACzB;AAED,qCAAqC;AACrC,MAAM,WAAW,WAAW;IAC1B,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,cAAc,CAAC;IACvB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB;;;;;;;OAOG;IACH,iBAAiB,CAAC,EAAE,iBAAiB,CAAC;CACvC;AAuBD,wBAAsB,OAAO,CAAC,IAAI,EAAE,QAAQ,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,WAAW,CAAC,
|
|
1
|
+
{"version":3,"file":"runSend.d.ts","sourceRoot":"","sources":["../../src/send/runSend.ts"],"names":[],"mappings":"AASA,OAAO,KAAK,EAAE,cAAc,EAAE,iBAAiB,EAAE,MAAM,eAAe,CAAC;AACvE,OAAO,KAAK,EAAE,aAAa,EAAE,wBAAwB,EAAe,MAAM,gBAAgB,CAAC;AAE3F,OAAO,EAAE,KAAK,kBAAkB,EAAmC,MAAM,uBAAuB,CAAC;AACjG,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,oBAAoB,CAAC;AAGrD,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,UAAU,CAAC;AAG5C;;;;;;;;;;;;;;;;;;GAkBG;AAEH,kGAAkG;AAClG,MAAM,WAAW,WAAW;IAC1B,qCAAqC;IACrC,GAAG,EAAE,MAAM,CAAC;IACZ,oEAAoE;IACpE,GAAG,EAAE,MAAM,CAAC;CACb;AAED,yDAAyD;AACzD,MAAM,WAAW,QAAQ;IACvB,gDAAgD;IAChD,EAAE,EAAE,aAAa,CAAC;IAClB,sGAAsG;IACtG,aAAa,EAAE,wBAAwB,CAAC;IACxC,MAAM,EAAE,WAAW,CAAC;IACpB,KAAK,EAAE,UAAU,CAAC;IAClB;;;;;;;OAOG;IACH,SAAS,CAAC,EAAE,kBAAkB,CAAC;IAC/B,8CAA8C;IAC9C,OAAO,EAAE,MAAM,CAAC;IAChB,6GAA6G;IAC7G,OAAO,CAAC,EAAE,WAAW,CAAC;IACtB,2CAA2C;IAC3C,WAAW,EAAE,MAAM,CAAC;IACpB,qEAAqE;IACrE,WAAW,EAAE,MAAM,CAAC;IACpB,iHAAiH;IACjH,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB;;;;;;;;;;;;OAYG;IACH,aAAa,EAAE,IAAI,CAAC;IACpB;;;;;;;;;;;;;OAaG;IACH,WAAW,EAAE,MAAM,IAAI,CAAC;CACzB;AAED,qCAAqC;AACrC,MAAM,WAAW,WAAW;IAC1B,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,cAAc,CAAC;IACvB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB;;;;;;;OAOG;IACH,iBAAiB,CAAC,EAAE,iBAAiB,CAAC;CACvC;AAuBD,wBAAsB,OAAO,CAAC,IAAI,EAAE,QAAQ,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,WAAW,CAAC,CAoLjF"}
|
package/dist/send/runSend.js
CHANGED
|
@@ -197,18 +197,18 @@ async function runSend(deps, jobId) {
|
|
|
197
197
|
};
|
|
198
198
|
}
|
|
199
199
|
if (classified.retryable && attempts < deps.maxAttempts) {
|
|
200
|
-
await patchJob(deps, jobId, { error: classified.
|
|
200
|
+
await patchJob(deps, jobId, { error: classified.detail });
|
|
201
201
|
throw classified.error;
|
|
202
202
|
}
|
|
203
203
|
await patchJob(deps, jobId, {
|
|
204
204
|
status: "failed",
|
|
205
|
-
error: classified.
|
|
205
|
+
error: classified.detail
|
|
206
206
|
});
|
|
207
207
|
await recordEvent(deps.db, {
|
|
208
208
|
jobId,
|
|
209
209
|
recipient,
|
|
210
210
|
type: "failed",
|
|
211
|
-
detail: classified.
|
|
211
|
+
detail: classified.detail
|
|
212
212
|
}, deps.passStartedAt);
|
|
213
213
|
return {
|
|
214
214
|
jobId,
|
|
@@ -3,5 +3,5 @@
|
|
|
3
3
|
/** This package's npm name — the join key against a release feed. */
|
|
4
4
|
export declare const PACKAGE_NAME = "@pithy-sh/email";
|
|
5
5
|
/** This package's version, stamped from its own package.json at generation time. */
|
|
6
|
-
export declare const PACKAGE_VERSION = "0.
|
|
6
|
+
export declare const PACKAGE_VERSION = "0.3.0";
|
|
7
7
|
//# sourceMappingURL=version.generated.d.ts.map
|
|
@@ -4,6 +4,6 @@
|
|
|
4
4
|
/** This package's npm name — the join key against a release feed. */
|
|
5
5
|
const PACKAGE_NAME = "@pithy-sh/email";
|
|
6
6
|
/** This package's version, stamped from its own package.json at generation time. */
|
|
7
|
-
const PACKAGE_VERSION = "0.
|
|
7
|
+
const PACKAGE_VERSION = "0.3.0";
|
|
8
8
|
//#endregion
|
|
9
9
|
export { PACKAGE_NAME, PACKAGE_VERSION };
|
package/package.json
CHANGED
package/src/send/errorMapping.ts
CHANGED
|
@@ -14,8 +14,23 @@ import { EmailRateLimitedError, EmailSendFailedError, EmailSuppressedError } fro
|
|
|
14
14
|
|
|
15
15
|
/** How a given send error is handled: which Pithy error to raise, and whether the send Workflow retries. */
|
|
16
16
|
export interface ClassifiedSendError {
|
|
17
|
-
/** The `E_*` code reported by the binding, or `E_UNKNOWN`
|
|
17
|
+
/** The `E_*` code reported by the binding, a numeric provider code as a string, or `E_UNKNOWN` for none. */
|
|
18
18
|
code: string;
|
|
19
|
+
/**
|
|
20
|
+
* The cause, as one operator-facing line: the code and whatever the provider said with it.
|
|
21
|
+
*
|
|
22
|
+
* **Exposed because the job row needs it and only the error object had it (pithy-sh/pithy#555).**
|
|
23
|
+
* `runSend` persisted the bare `code` into `pithy_email_jobs.error`, so a magic link that failed five
|
|
24
|
+
* times against a token for the wrong account recorded `E_UNKNOWN` five times and nothing about why —
|
|
25
|
+
* while this exact string, naming `10000 Authentication error`, was being built two lines down and
|
|
26
|
+
* thrown away with the error it decorated. Same family as #534: a failure that discards the cause it
|
|
27
|
+
* was handed.
|
|
28
|
+
*
|
|
29
|
+
* Identical to `error.payload.detail`, deliberately — one composition, two readers, so the row and the
|
|
30
|
+
* log cannot drift. `detail` is stripped at the client boundary, which is where a provider's own words
|
|
31
|
+
* belong.
|
|
32
|
+
*/
|
|
33
|
+
detail: string;
|
|
19
34
|
/** Whether the send should be retried with backoff. */
|
|
20
35
|
retryable: boolean;
|
|
21
36
|
/** Whether the failure means the recipient is suppressed (so the address should be locally suppressed). */
|
|
@@ -35,21 +50,77 @@ const RETRYABLE = new Set([
|
|
|
35
50
|
/** Rate/quota codes map to the dedicated 429 error so the cause reads clearly in logs. */
|
|
36
51
|
const RATE_LIMITED = new Set(["E_RATE_LIMIT_EXCEEDED", "E_DAILY_LIMIT_EXCEEDED"]);
|
|
37
52
|
|
|
38
|
-
/**
|
|
53
|
+
/**
|
|
54
|
+
* Codes that mean **this Worker could not authenticate** — terminal, because no retry clears a credential.
|
|
55
|
+
*
|
|
56
|
+
* `10000` is Cloudflare's own: a token that is alive but not scoped for Email Sending, or scoped for an
|
|
57
|
+
* account that does not own the sending domain, is answered `{ code: 10000, message: "Authentication
|
|
58
|
+
* error" }` (#534 captured the body; `liveSend.integration.test.ts` documents the same rejection for a
|
|
59
|
+
* general account token). That is the exact failure #555 spent five attempts on in silence.
|
|
60
|
+
*
|
|
61
|
+
* **Named rather than inferred from the code being numeric.** Treating every numeric code as terminal was
|
|
62
|
+
* the first shape of this fix and it bought the auth case by making a *momentary* numeric failure
|
|
63
|
+
* permanent too — one attempt, `status: "failed"`, where the retry budget used to apply. A code nobody
|
|
64
|
+
* here recognizes is still unknown, whichever alphabet it is written in, and unknown has earned its
|
|
65
|
+
* bounded retry since the module was written. So the auth class is listed, and the rule below is
|
|
66
|
+
* unchanged for everything else.
|
|
67
|
+
*/
|
|
68
|
+
const UNAUTHORIZED = new Set(["10000", "E_UNAUTHORIZED", "E_FORBIDDEN"]);
|
|
69
|
+
|
|
70
|
+
/**
|
|
71
|
+
* Whether a code is one of Cloudflare's numeric ones rather than the binding's `E_*` spelling.
|
|
72
|
+
*
|
|
73
|
+
* The distinction decides the retry, so it is a predicate rather than a guess at the call site. An `E_*`
|
|
74
|
+
* code this module does not list stays **terminal**, exactly as it always has — the binding's documented
|
|
75
|
+
* unknowns are validation, sender, content and header faults, and retrying one cannot help. A *numeric*
|
|
76
|
+
* code this module does not list is retryable, because it arrives from the account/REST layer where a
|
|
77
|
+
* momentary fault is ordinary and nothing here has an opinion yet.
|
|
78
|
+
*/
|
|
79
|
+
function isProviderNumericCode(code: string): boolean {
|
|
80
|
+
return /^[0-9]+$/.test(code);
|
|
81
|
+
}
|
|
82
|
+
|
|
83
|
+
/**
|
|
84
|
+
* Read a thrown value's `.code`/`.message` without assuming its shape.
|
|
85
|
+
*
|
|
86
|
+
* **A numeric code counts, and that is not a detail.** The Email Service binding surfaces `E_*` strings,
|
|
87
|
+
* but the REST path and the account layer behind it answer with Cloudflare's own numeric codes — an
|
|
88
|
+
* unauthorized send is `{ code: 10000, message: "Authentication error" }` (#534 captured the body). Read
|
|
89
|
+
* as "no code" that became `E_UNKNOWN`, which is both silent *and* retryable, so a credential fault
|
|
90
|
+
* consumed every attempt without ever naming itself (#555).
|
|
91
|
+
*
|
|
92
|
+
* **And a value with neither field still leaves a trace.** `String(err)` rather than `""`: an opaque
|
|
93
|
+
* throw is the case where the operator has least to go on, so an empty string is the one answer that
|
|
94
|
+
* cannot help. `E_UNKNOWN` remains the code — it means *nothing named itself*, which is the fact that
|
|
95
|
+
* earns the bounded retry.
|
|
96
|
+
*/
|
|
39
97
|
function readError(err: unknown): { code: string; message: string } {
|
|
40
98
|
if (err && typeof err === "object") {
|
|
41
|
-
const
|
|
42
|
-
const
|
|
43
|
-
|
|
99
|
+
const raw = "code" in err ? err.code : undefined;
|
|
100
|
+
const code = typeof raw === "string" && raw !== "" ? raw : typeof raw === "number" ? String(raw) : "E_UNKNOWN";
|
|
101
|
+
// `String(err)` only where nothing named itself. A coded throw carrying no message would otherwise
|
|
102
|
+
// record `E_INVALID_SENDER — [object Object]`, which is the code the operator already had plus noise —
|
|
103
|
+
// and that string is what the job row and the admin detail route now read.
|
|
104
|
+
const named = "message" in err && typeof err.message === "string" ? err.message : "";
|
|
105
|
+
return { code, message: named !== "" ? named : code === "E_UNKNOWN" ? String(err) : "" };
|
|
44
106
|
}
|
|
45
|
-
return { code: "E_UNKNOWN", message: typeof err === "string" ? err :
|
|
107
|
+
return { code: "E_UNKNOWN", message: typeof err === "string" ? err : String(err) };
|
|
46
108
|
}
|
|
47
109
|
|
|
48
110
|
/**
|
|
49
111
|
* Classify a send failure. `E_RECIPIENT_SUPPRESSED` is terminal and means the address must be
|
|
50
112
|
* suppressed locally too; rate/quota and transient delivery codes are retryable; everything else
|
|
51
|
-
* (validation, sender, content, headers) is terminal.
|
|
52
|
-
*
|
|
113
|
+
* (validation, sender, content, headers) is terminal.
|
|
114
|
+
*
|
|
115
|
+
* **An unrecognized code is retryable, and that is deliberately unchanged.** A failure this module has
|
|
116
|
+
* no code at all keeps its bounded retry, and so does a *numeric* provider code nobody here has listed —
|
|
117
|
+
* see {@link isProviderNumericCode} for why those two are alike and an unlisted `E_*` is not.
|
|
118
|
+
*
|
|
119
|
+
* What changed for #555 is that the **authentication** class is now named and terminal: `10000
|
|
120
|
+
* Authentication error` is a token that cannot send as this domain, and spending five attempts on it in
|
|
121
|
+
* silence is what hid the whole incident. See {@link UNAUTHORIZED} for why that is a list rather than
|
|
122
|
+
* "numeric means permanent" — the latter was this fix's first shape, and it made a momentary numeric
|
|
123
|
+
* failure permanent as a side effect.
|
|
53
124
|
*/
|
|
54
125
|
export function classifySendError(err: unknown): ClassifiedSendError {
|
|
55
126
|
const { code, message } = readError(err);
|
|
@@ -58,6 +129,7 @@ export function classifySendError(err: unknown): ClassifiedSendError {
|
|
|
58
129
|
if (code === "E_RECIPIENT_SUPPRESSED") {
|
|
59
130
|
return {
|
|
60
131
|
code,
|
|
132
|
+
detail,
|
|
61
133
|
retryable: false,
|
|
62
134
|
suppressed: true,
|
|
63
135
|
error: new EmailSuppressedError({ detail }, { cause: err }),
|
|
@@ -65,9 +137,18 @@ export function classifySendError(err: unknown): ClassifiedSendError {
|
|
|
65
137
|
}
|
|
66
138
|
|
|
67
139
|
if (RATE_LIMITED.has(code)) {
|
|
68
|
-
return {
|
|
140
|
+
return {
|
|
141
|
+
code,
|
|
142
|
+
detail,
|
|
143
|
+
retryable: true,
|
|
144
|
+
suppressed: false,
|
|
145
|
+
error: new EmailRateLimitedError({ detail }, { cause: err }),
|
|
146
|
+
};
|
|
69
147
|
}
|
|
70
148
|
|
|
71
|
-
|
|
72
|
-
|
|
149
|
+
// Three ways to earn a retry, and nothing else: a code documented as transient, no code at all, or a
|
|
150
|
+
// numeric provider code that is not the authentication class. An unlisted `E_*` stays terminal.
|
|
151
|
+
const retryable =
|
|
152
|
+
RETRYABLE.has(code) || code === "E_UNKNOWN" || (isProviderNumericCode(code) && !UNAUTHORIZED.has(code));
|
|
153
|
+
return { code, detail, retryable, suppressed: false, error: new EmailSendFailedError({ detail }, { cause: err }) };
|
|
73
154
|
}
|
package/src/send/runSend.ts
CHANGED
|
@@ -309,12 +309,16 @@ export async function runSend(deps: SendDeps, jobId: string): Promise<SendOutcom
|
|
|
309
309
|
|
|
310
310
|
if (classified.retryable && attempts < deps.maxAttempts) {
|
|
311
311
|
// Persist the last error, then throw so the Workflow step retries with backoff (row stays `sending`).
|
|
312
|
-
await patchJob(deps, jobId, { error: classified.
|
|
312
|
+
await patchJob(deps, jobId, { error: classified.detail });
|
|
313
313
|
throw classified.error;
|
|
314
314
|
}
|
|
315
315
|
|
|
316
|
-
|
|
317
|
-
|
|
316
|
+
// **`detail`, not `code`.** The column is described as "the last error code/message", and it held only
|
|
317
|
+
// the code — so a magic link that failed five times recorded `E_UNKNOWN` five times, and the one
|
|
318
|
+
// sentence naming the cause was discarded with the error object (pithy-sh/pithy#555, and #534's
|
|
319
|
+
// family). `detail` leads with the code, so nothing a reader had before is lost.
|
|
320
|
+
await patchJob(deps, jobId, { status: "failed", error: classified.detail });
|
|
321
|
+
await recordEvent(deps.db, { jobId, recipient, type: "failed", detail: classified.detail }, deps.passStartedAt);
|
|
318
322
|
return { jobId, status: "failed" };
|
|
319
323
|
}
|
|
320
324
|
}
|
package/src/version.generated.ts
CHANGED