@pithy-sh/email 0.1.2 → 0.1.3
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/analytics.d.ts +19 -0
- package/dist/analytics.d.ts.map +1 -0
- package/dist/analytics.js +13 -0
- package/dist/audit/actions.d.ts +45 -0
- package/dist/audit/actions.d.ts.map +1 -0
- package/dist/audit/actions.js +45 -0
- package/dist/bounce/classify.d.ts +38 -0
- package/dist/bounce/classify.d.ts.map +1 -0
- package/dist/bounce/classify.js +46 -0
- package/dist/bounce/handler.d.ts +32 -0
- package/dist/bounce/handler.d.ts.map +1 -0
- package/dist/bounce/handler.js +81 -0
- package/dist/capability.d.ts +158 -0
- package/dist/capability.d.ts.map +1 -0
- package/dist/capability.js +255 -0
- package/dist/crypto/signingKey.d.ts +36 -0
- package/dist/crypto/signingKey.d.ts.map +1 -0
- package/dist/crypto/signingKey.js +36 -0
- package/dist/crypto/token.d.ts +47 -0
- package/dist/crypto/token.d.ts.map +1 -0
- package/dist/crypto/token.js +99 -0
- package/dist/data/emailEvent.d.ts +28 -0
- package/dist/data/emailEvent.d.ts.map +1 -0
- package/dist/data/emailEvent.js +22 -0
- package/dist/data/emailJob.d.ts +76 -0
- package/dist/data/emailJob.d.ts.map +1 -0
- package/dist/data/emailJob.js +62 -0
- package/dist/data/emailSuppression.d.ts +23 -0
- package/dist/data/emailSuppression.d.ts.map +1 -0
- package/dist/data/emailSuppression.js +21 -0
- package/dist/data/enums.d.ts +76 -0
- package/dist/data/enums.d.ts.map +1 -0
- package/dist/data/enums.js +65 -0
- package/dist/data/tables.d.ts +114 -0
- package/dist/data/tables.d.ts.map +1 -0
- package/dist/data/tables.js +30 -0
- package/dist/error/errors.d.ts +60 -0
- package/dist/error/errors.d.ts.map +1 -0
- package/dist/error/errors.js +82 -0
- package/dist/http/callbacks.d.ts +21 -0
- package/dist/http/callbacks.d.ts.map +1 -0
- package/dist/http/callbacks.js +110 -0
- package/dist/http/guards.d.ts +99 -0
- package/dist/http/guards.d.ts.map +1 -0
- package/dist/http/guards.js +144 -0
- package/dist/http/responses.d.ts +295 -0
- package/dist/http/responses.d.ts.map +1 -0
- package/dist/http/responses.js +115 -0
- package/dist/http/routes.d.ts +71 -0
- package/dist/http/routes.d.ts.map +1 -0
- package/dist/http/routes.js +292 -0
- package/dist/http/schemas.d.ts +90 -0
- package/dist/http/schemas.d.ts.map +1 -0
- package/dist/http/schemas.js +91 -0
- package/dist/http/view.d.ts +78 -0
- package/dist/http/view.d.ts.map +1 -0
- package/dist/http/view.js +130 -0
- package/dist/index.d.ts +46 -0
- package/dist/index.d.ts.map +1 -0
- package/dist/index.js +11 -0
- package/dist/jobs/read.d.ts +191 -0
- package/dist/jobs/read.d.ts.map +1 -0
- package/dist/jobs/read.js +143 -0
- package/dist/jobs/retry.d.ts +99 -0
- package/dist/jobs/retry.d.ts.map +1 -0
- package/dist/jobs/retry.js +67 -0
- package/dist/migrations/0001_init.d.ts +32 -0
- package/dist/migrations/0001_init.d.ts.map +1 -0
- package/dist/migrations/0001_init.js +60 -0
- package/dist/migrations/0001_suppressions.d.ts +10 -0
- package/dist/migrations/0001_suppressions.d.ts.map +1 -0
- package/dist/migrations/0001_suppressions.js +20 -0
- package/dist/provision/devDelivery.d.ts +32 -0
- package/dist/provision/devDelivery.d.ts.map +1 -0
- package/dist/provision/devDelivery.js +37 -0
- package/dist/provision/hostCatalogs.d.ts +10 -0
- package/dist/provision/hostCatalogs.d.ts.map +1 -0
- package/dist/provision/hostCatalogs.js +78 -0
- package/dist/provision/provisionEmail.d.ts +143 -0
- package/dist/provision/provisionEmail.d.ts.map +1 -0
- package/dist/provision/provisionEmail.js +118 -0
- package/dist/provision/resolveEmailConfig.d.ts +122 -0
- package/dist/provision/resolveEmailConfig.d.ts.map +1 -0
- package/dist/provision/resolveEmailConfig.js +124 -0
- package/dist/provision/settingsCheck.d.ts +40 -0
- package/dist/provision/settingsCheck.d.ts.map +1 -0
- package/dist/provision/settingsCheck.js +138 -0
- package/dist/send/batchIdentity.d.ts +42 -0
- package/dist/send/batchIdentity.d.ts.map +1 -0
- package/dist/send/batchIdentity.js +46 -0
- package/dist/send/enqueue.d.ts +216 -0
- package/dist/send/enqueue.d.ts.map +1 -0
- package/dist/send/enqueue.js +153 -0
- package/dist/send/errorMapping.d.ts +27 -0
- package/dist/send/errorMapping.d.ts.map +1 -0
- package/dist/send/errorMapping.js +52 -0
- package/dist/send/events.d.ts +15 -0
- package/dist/send/events.d.ts.map +1 -0
- package/dist/send/events.js +17 -0
- package/dist/send/fromComposition.d.ts +47 -0
- package/dist/send/fromComposition.d.ts.map +1 -0
- package/dist/send/fromComposition.js +53 -0
- package/dist/send/retryPolicy.d.ts +32 -0
- package/dist/send/retryPolicy.d.ts.map +1 -0
- package/dist/send/retryPolicy.js +39 -0
- package/dist/send/runSend.d.ts +106 -0
- package/dist/send/runSend.d.ts.map +1 -0
- package/dist/send/runSend.js +218 -0
- package/dist/send/sendAt.d.ts +6 -0
- package/dist/send/sendAt.d.ts.map +1 -0
- package/dist/send/sendAt.js +62 -0
- package/dist/send/sender.d.ts +42 -0
- package/dist/send/sender.d.ts.map +1 -0
- package/dist/send/sender.js +0 -0
- package/dist/send/senderBinding.d.ts +44 -0
- package/dist/send/senderBinding.d.ts.map +1 -0
- package/dist/send/senderBinding.js +21 -0
- package/dist/send/suppression.d.ts +93 -0
- package/dist/send/suppression.d.ts.map +1 -0
- package/dist/send/suppression.js +132 -0
- package/dist/templates/engine.d.ts +109 -0
- package/dist/templates/engine.d.ts.map +1 -0
- package/dist/templates/engine.js +258 -0
- package/dist/templates/messages.d.ts +94 -0
- package/dist/templates/messages.d.ts.map +1 -0
- package/dist/templates/messages.es.d.ts +29 -0
- package/dist/templates/messages.es.d.ts.map +1 -0
- package/dist/templates/messages.es.js +82 -0
- package/dist/templates/messages.js +266 -0
- package/dist/templates/partials.d.ts +5 -0
- package/dist/templates/partials.d.ts.map +1 -0
- package/dist/templates/partials.js +59 -0
- package/dist/templates/precompiled.generated.d.ts +266 -0
- package/dist/templates/precompiled.generated.d.ts.map +1 -0
- package/dist/templates/precompiled.generated.js +4039 -0
- package/dist/templates/registry.d.ts +118 -0
- package/dist/templates/registry.d.ts.map +1 -0
- package/dist/templates/registry.js +323 -0
- package/dist/templates/samples.d.ts +7 -0
- package/dist/templates/samples.d.ts.map +1 -0
- package/dist/templates/samples.js +98 -0
- package/dist/templates/severity.d.ts +40 -0
- package/dist/templates/severity.d.ts.map +1 -0
- package/dist/templates/severity.js +81 -0
- package/dist/templates/theme.d.ts +193 -0
- package/dist/templates/theme.d.ts.map +1 -0
- package/dist/templates/theme.js +168 -0
- package/dist/version.generated.d.ts +5 -0
- package/dist/version.generated.d.ts.map +1 -0
- package/dist/version.generated.js +7 -0
- package/dist/workflows/hostApp.d.ts +33 -0
- package/dist/workflows/hostApp.d.ts.map +1 -0
- package/dist/workflows/hostApp.js +19 -0
- package/dist/workflows/hostEnv.d.ts +129 -0
- package/dist/workflows/hostEnv.d.ts.map +1 -0
- package/dist/workflows/hostEnv.js +147 -0
- package/dist/workflows/instanceLiveness.d.ts +3 -0
- package/dist/workflows/instanceLiveness.d.ts.map +1 -0
- package/dist/workflows/instanceLiveness.js +37 -0
- package/dist/workflows/instances.d.ts +18 -0
- package/dist/workflows/instances.d.ts.map +1 -0
- package/dist/workflows/instances.js +0 -0
- package/dist/workflows/params.d.ts +23 -0
- package/dist/workflows/params.d.ts.map +1 -0
- package/dist/workflows/params.js +21 -0
- package/dist/workflows/scheduler.d.ts +82 -0
- package/dist/workflows/scheduler.d.ts.map +1 -0
- package/dist/workflows/scheduler.js +111 -0
- package/dist/workflows/sendBatch.d.ts +85 -0
- package/dist/workflows/sendBatch.d.ts.map +1 -0
- package/dist/workflows/sendBatch.js +50 -0
- package/dist/workflows/worker.d.ts +100 -0
- package/dist/workflows/worker.d.ts.map +1 -0
- package/dist/workflows/worker.js +117 -0
- package/package.json +22 -11
- package/src/version.generated.ts +1 -1
|
@@ -0,0 +1,147 @@
|
|
|
1
|
+
import { EmailTheme, defaultTheme } from "../templates/theme.js";
|
|
2
|
+
import { z } from "zod";
|
|
3
|
+
import { defineHostEnv } from "@pithy-sh/core/src/workflow/hostEnv";
|
|
4
|
+
//#region src/workflows/hostEnv.ts
|
|
5
|
+
/**
|
|
6
|
+
* What the prebuilt email host worker reads out of its env — declared once, validated at boot, and
|
|
7
|
+
* read statically by `pithy doctor` (pithy-sh/pithy#410, #411).
|
|
8
|
+
*
|
|
9
|
+
* Nobody authors this Worker. `pithy email provision` resolves the committed template beside this
|
|
10
|
+
* file and deploys it, so every value here arrives as a binding, a var or a Secrets Store entry that
|
|
11
|
+
* a *machine* wrote — and until this module, none of it was checked. Three failures, all of them
|
|
12
|
+
* discovered as mail that did not arrive:
|
|
13
|
+
*
|
|
14
|
+
* - `BASE_URL` absent → every magic link in the batch pointed at `undefined/auth/…`.
|
|
15
|
+
* - `EMAIL_THEME` unparseable → a `JSON.parse` threw inside a render step, three retries deep,
|
|
16
|
+
* where the message reads as a template fault.
|
|
17
|
+
* - `SCHEDULER_BATCH_SIZE` written `"fifty"` → `Number(...)` gave `NaN`, the scheduler claimed
|
|
18
|
+
* nothing, and it did so on every tick, forever, without a line in the log.
|
|
19
|
+
*
|
|
20
|
+
* So the parse is the boot check: `z.output` is what the host actually runs on, which is why the
|
|
21
|
+
* coercions live in the schema rather than at the call sites. `Number(env.MAX_ATTEMPTS ?? 5)` in
|
|
22
|
+
* `worker.ts` was the shape of the bug — a default and a coercion restated at every reader, each free
|
|
23
|
+
* to disagree with the next.
|
|
24
|
+
*
|
|
25
|
+
* ## Two names, deliberately
|
|
26
|
+
*
|
|
27
|
+
* {@link EmailHostEnv} is the schema (and the type the host runs on). {@link emailHostEnv} is the
|
|
28
|
+
* *declaration*: the schema plus what fills each field, which is the object the CLI imports. The
|
|
29
|
+
* second is the one an operator's report is built from — a missing field is only actionable when
|
|
30
|
+
* something names the binding, var or command that writes it.
|
|
31
|
+
*
|
|
32
|
+
* Node-safe on purpose. No `cloudflare:` import and no filesystem, so `pithy doctor` can import this
|
|
33
|
+
* without executing the Worker — the same constraint `@pithy-sh/core`'s host modules carry.
|
|
34
|
+
*/
|
|
35
|
+
/** The command that writes every provisioned value here. Stated once so nine action lines cannot drift. */
|
|
36
|
+
const PROVISION = "pithy email provision --env <env>";
|
|
37
|
+
/** A binding `pithy email provision` wires into the resolved `wrangler.jsonc`. */
|
|
38
|
+
const binding = (name) => ({
|
|
39
|
+
kind: "binding",
|
|
40
|
+
name,
|
|
41
|
+
command: PROVISION
|
|
42
|
+
});
|
|
43
|
+
/** A var the same run stamps into that config's `vars` block. */
|
|
44
|
+
const provisionedVar = (name) => ({
|
|
45
|
+
kind: "var",
|
|
46
|
+
name,
|
|
47
|
+
command: PROVISION
|
|
48
|
+
});
|
|
49
|
+
/** A var with a shipped default — the template carries it, and an adopter may tune it in place. */
|
|
50
|
+
const tunedVar = (name) => ({
|
|
51
|
+
kind: "var",
|
|
52
|
+
name
|
|
53
|
+
});
|
|
54
|
+
/**
|
|
55
|
+
* A binding the host calls one method on, checked structurally.
|
|
56
|
+
*
|
|
57
|
+
* Duck-typed rather than `instanceof`-checked because these are host objects the runtime hands over:
|
|
58
|
+
* there is no class to compare against, and `wrangler dev`'s stand-ins are different objects again.
|
|
59
|
+
* What the host depends on is the method, so the method is what is asserted.
|
|
60
|
+
*/
|
|
61
|
+
function callable(method, what) {
|
|
62
|
+
return z.custom((value) => typeof value?.[method] === "function", { error: `${what} — the binding is missing, or it is not the kind of binding this name expects.` });
|
|
63
|
+
}
|
|
64
|
+
/** A D1 binding. `prepare` is the whole of what Kysely's D1 dialect needs from one. */
|
|
65
|
+
const d1Binding = (what) => callable("prepare", what);
|
|
66
|
+
/**
|
|
67
|
+
* A count or a duration wrangler binds as a string.
|
|
68
|
+
*
|
|
69
|
+
* `z.coerce` before the integer check, so `"50"` is fifty and `"fifty"` is a refusal naming the field
|
|
70
|
+
* — which is precisely the difference between this and the `Number(...)` it replaces.
|
|
71
|
+
*/
|
|
72
|
+
const tunedNumber = (fallback) => z.coerce.number().int().positive().default(fallback);
|
|
73
|
+
/** The email host's env, as the host runs on it. Every field is coerced here, never at its reader. */
|
|
74
|
+
const EmailHostEnv = z.object({
|
|
75
|
+
DB: d1Binding("The app database holding this environment's email jobs and events").describe("The app D1 database. The `pithy_email_jobs` and `pithy_email_events` tables live here, beside the adopter's own data. Bound by `pithy email provision`, which fills the id for the environment being deployed."),
|
|
76
|
+
EMAIL_SUPPRESSIONS: d1Binding("The shared suppression database every environment of this project binds").describe("The durable suppression D1 database — one per project, bound identically in every environment, so an unsubscribe or a hard bounce applies everywhere the project sends from. Named `<project>-global-email-suppressions`."),
|
|
77
|
+
SECRETS: d1Binding("The per-environment secrets database the link-signing key is read from").describe("The per-environment secrets D1 database. The link-signing key is stored here as an encrypted row and read through `@pithy-sh/secrets`; without it, tracking and unsubscribe links cannot be signed."),
|
|
78
|
+
SECRETS_ENCRYPTION_KEYS: z.union([z.string().min(1), callable("get", "The master key binding")]).describe("The master key that decrypts the secrets database — a Cloudflare Secrets Store binding in a deployed environment, and the same name as a plain string in `.dev.vars` locally. The one secret read outside the `secretsStore` accessor, because it is what makes the accessor work."),
|
|
79
|
+
EMAIL: callable("send", "The Cloudflare Email Service send binding").describe("The Cloudflare Email Service `send_email` binding — the only thing in the kit that puts a message on the wire. `wrangler dev` simulates it locally; `remote: true` (the default under `pithy dev`) sends for real from the developer's machine."),
|
|
80
|
+
EMAIL_SENDER: z.custom((value) => isCallable(value, "create") && isCallable(value, "get"), { error: "The send Workflow binding — it must both start an instance and answer about one." }).describe("This host's own send Workflow, same-script. Two calls, and both matter: `create` starts a batch, and `get` is how the scheduler asks whether the instance a stranded row names is still alive before re-driving it."),
|
|
81
|
+
EMAIL_SCHEDULER: callable("create", "The scheduler Workflow binding").describe("This host's own scheduler Workflow, same-script. Fired by the every-minute cron; it finds due jobs and fans them out into send batches."),
|
|
82
|
+
BASE_URL: z.url().describe("The app worker's public base URL for this environment. Every link that leaves in an email — magic link, tracked click, unsubscribe — is built against it, so a wrong value is a message that arrives and cannot be acted on."),
|
|
83
|
+
EMAIL_THEME: z.string().optional().transform((raw, ctx) => {
|
|
84
|
+
if (raw === void 0 || raw.trim().length === 0) return defaultTheme;
|
|
85
|
+
try {
|
|
86
|
+
return JSON.parse(raw);
|
|
87
|
+
} catch {
|
|
88
|
+
ctx.addIssue({
|
|
89
|
+
code: "custom",
|
|
90
|
+
message: "Not valid JSON. The whole theme travels as one JSON var."
|
|
91
|
+
});
|
|
92
|
+
return z.NEVER;
|
|
93
|
+
}
|
|
94
|
+
}).pipe(EmailTheme).describe("The resolved brand theme, serialized as one JSON var at provision from the adopter's `email()` config. Absent falls back to the kit's default theme; present-and-unreadable is refused."),
|
|
95
|
+
ENVIRONMENT: z.string().min(1).optional().describe("The environment this host was deployed for. Stamped on every send as `X-Pithy-Env`, which is how the single inbound bounce worker attributes a bounce back to the environment that sent it."),
|
|
96
|
+
LINK_TTL_DAYS: tunedNumber(90).describe("How long a signed tracking or unsubscribe link stays valid, in days. Long by design: the link is minted into mail nobody can recall, and an unsubscribe that has expired is a complaint."),
|
|
97
|
+
MAX_ATTEMPTS: tunedNumber(5).describe("How many times one job may be attempted before it is failed terminally. Spent attempts are what separates a provider hiccup from an address that will never accept mail."),
|
|
98
|
+
SCHEDULER_ENABLED: z.enum(["true", "false"]).describe("The var as wrangler binds it — a string, and only these two spellings of it.").default("true").transform((value) => value === "true").describe("Whether the every-minute scheduler Workflow runs. `false` stops due jobs being claimed at all — the cron still fires and does nothing — so it is a maintenance switch, not a tuning knob."),
|
|
99
|
+
SCHEDULER_BATCH_SIZE: tunedNumber(50).describe("How many jobs one send Workflow instance takes. Each job is a durable step, so this is the unit of retry and of the instance's report."),
|
|
100
|
+
SCHEDULER_MAX_JOBS: tunedNumber(500).describe("The most rows one scheduler tick will claim. A ceiling on the work a single minute can start, so a backlog drains steadily rather than in one instance-creating burst."),
|
|
101
|
+
SCHEDULER_GRACE_MS: tunedNumber(12e4).describe("How long an immediate job is left alone before the safety net treats it as stranded, in milliseconds. The window a freshly-enqueued job's own dispatch has to land in; too short re-drives sends that were already on their way."),
|
|
102
|
+
SCHEDULER_STUCK_MS: tunedNumber(9e5).describe("How long a job may sit `sending` before the safety net re-drives it, in milliseconds. A send Workflow in retry backoff writes nothing, so this is what tells a slow batch apart from a dead one.")
|
|
103
|
+
}).describe("Everything the prebuilt email host worker reads out of its env, in the shape it runs on.");
|
|
104
|
+
/** Whether a value carries a callable method of that name. */
|
|
105
|
+
function isCallable(value, method) {
|
|
106
|
+
return typeof value?.[method] === "function";
|
|
107
|
+
}
|
|
108
|
+
/**
|
|
109
|
+
* The email host's env declaration — the schema plus what fills each field.
|
|
110
|
+
*
|
|
111
|
+
* The host validates against this at boot ({@link import("@pithy-sh/core/src/workflow/hostEnv").requireHostEnv});
|
|
112
|
+
* `pithy doctor` walks the same object to check an adopter's *resolved* settings without running a
|
|
113
|
+
* Worker. One declaration, so the check an operator runs and the check the host runs cannot disagree.
|
|
114
|
+
*/
|
|
115
|
+
const emailHostEnv = defineHostEnv({
|
|
116
|
+
capability: "email",
|
|
117
|
+
env: EmailHostEnv,
|
|
118
|
+
provided: {
|
|
119
|
+
DB: binding("DB"),
|
|
120
|
+
EMAIL_SUPPRESSIONS: binding("EMAIL_SUPPRESSIONS"),
|
|
121
|
+
SECRETS: binding("SECRETS"),
|
|
122
|
+
SECRETS_ENCRYPTION_KEYS: {
|
|
123
|
+
kind: "secret",
|
|
124
|
+
name: "SECRETS_ENCRYPTION_KEYS",
|
|
125
|
+
command: "pithy secrets provision --env <env>"
|
|
126
|
+
},
|
|
127
|
+
EMAIL: binding("EMAIL"),
|
|
128
|
+
EMAIL_SENDER: binding("EMAIL_SENDER"),
|
|
129
|
+
EMAIL_SCHEDULER: binding("EMAIL_SCHEDULER"),
|
|
130
|
+
BASE_URL: provisionedVar("BASE_URL"),
|
|
131
|
+
EMAIL_THEME: {
|
|
132
|
+
kind: "config",
|
|
133
|
+
name: "email({ theme, customTheme })",
|
|
134
|
+
command: PROVISION
|
|
135
|
+
},
|
|
136
|
+
ENVIRONMENT: provisionedVar("ENVIRONMENT"),
|
|
137
|
+
LINK_TTL_DAYS: tunedVar("LINK_TTL_DAYS"),
|
|
138
|
+
MAX_ATTEMPTS: tunedVar("MAX_ATTEMPTS"),
|
|
139
|
+
SCHEDULER_ENABLED: tunedVar("SCHEDULER_ENABLED"),
|
|
140
|
+
SCHEDULER_BATCH_SIZE: tunedVar("SCHEDULER_BATCH_SIZE"),
|
|
141
|
+
SCHEDULER_MAX_JOBS: tunedVar("SCHEDULER_MAX_JOBS"),
|
|
142
|
+
SCHEDULER_GRACE_MS: tunedVar("SCHEDULER_GRACE_MS"),
|
|
143
|
+
SCHEDULER_STUCK_MS: tunedVar("SCHEDULER_STUCK_MS")
|
|
144
|
+
}
|
|
145
|
+
});
|
|
146
|
+
//#endregion
|
|
147
|
+
export { EmailHostEnv, emailHostEnv };
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"instanceLiveness.d.ts","sourceRoot":"","sources":["../../src/workflows/instanceLiveness.ts"],"names":[],"mappings":"AAmCA,gEAAgE;AAChE,wBAAgB,oBAAoB,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAE5D"}
|
|
@@ -0,0 +1,37 @@
|
|
|
1
|
+
//#region src/workflows/instanceLiveness.ts
|
|
2
|
+
/**
|
|
3
|
+
* What a Workflow instance's status means to the scheduler (pithy-sh/pithy#342).
|
|
4
|
+
*
|
|
5
|
+
* The scheduler re-drives a `sending` job only when the batch holding it is not alive, and "alive" is a
|
|
6
|
+
* question about a Workflow instance rather than about a row. This is the one statement of which answers
|
|
7
|
+
* count as alive — kept out of `worker.ts` because that module imports `cloudflare:workers` and can
|
|
8
|
+
* therefore only be exercised by deploying it, and this is a rule worth driving.
|
|
9
|
+
*/
|
|
10
|
+
/**
|
|
11
|
+
* The statuses that mean "this batch is still coming".
|
|
12
|
+
*
|
|
13
|
+
* Named as the live set rather than the dead one, deliberately. A status the platform adds tomorrow then
|
|
14
|
+
* reads as dead and its jobs are re-driven — the safety net erring towards recovery, which costs a
|
|
15
|
+
* duplicate render that `runSend` short-circuits for anything already `sent` — instead of this code
|
|
16
|
+
* silently vouching for an instance state it has never heard of.
|
|
17
|
+
*
|
|
18
|
+
* `queued` is live because the instance exists and will start. `paused` is live because a paused
|
|
19
|
+
* instance is resumable and still owns its rows; re-driving one would put a second Workflow behind the
|
|
20
|
+
* same jobs and make pausing a batch a way to send everyone in it twice.
|
|
21
|
+
*
|
|
22
|
+
* Outside it today: `errored`, `terminated`, `complete`, and anything unrecognized. None of those will
|
|
23
|
+
* touch another job, so whatever they left in `sending` is genuinely stranded.
|
|
24
|
+
*/
|
|
25
|
+
const LIVE_INSTANCE_STATUSES = /* @__PURE__ */ new Set([
|
|
26
|
+
"queued",
|
|
27
|
+
"running",
|
|
28
|
+
"paused",
|
|
29
|
+
"waiting",
|
|
30
|
+
"waitingForPause"
|
|
31
|
+
]);
|
|
32
|
+
/** Does this instance status mean the batch is still coming? */
|
|
33
|
+
function isLiveInstanceStatus(status) {
|
|
34
|
+
return LIVE_INSTANCE_STATUSES.has(status);
|
|
35
|
+
}
|
|
36
|
+
//#endregion
|
|
37
|
+
export { isLiveInstanceStatus };
|
|
@@ -0,0 +1,18 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* The half of the Workflows binding that answers about an instance already created.
|
|
3
|
+
*
|
|
4
|
+
* Declared here rather than taken from `cloudflare:workers` because the scheduler must not depend on
|
|
5
|
+
* the platform types — it takes a question as a function, and only the host answers it with a real
|
|
6
|
+
* Workflow. It lives in its own module rather than beside that host because `workflows/worker.ts`
|
|
7
|
+
* imports `cloudflare:workers` and so cannot be loaded under node, while
|
|
8
|
+
* {@link ./hostEnv.ts} — which `pithy doctor` imports — has to be.
|
|
9
|
+
*/
|
|
10
|
+
export interface SendWorkflowInstances {
|
|
11
|
+
/** Look an instance up by the id it was created with. Rejects when no such instance exists. */
|
|
12
|
+
get(id: string): Promise<{
|
|
13
|
+
status(): Promise<{
|
|
14
|
+
status: string;
|
|
15
|
+
}>;
|
|
16
|
+
}>;
|
|
17
|
+
}
|
|
18
|
+
//# sourceMappingURL=instances.d.ts.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"instances.d.ts","sourceRoot":"","sources":["../../src/workflows/instances.ts"],"names":[],"mappings":"AAGA;;;;;;;;GAQG;AACH,MAAM,WAAW,qBAAqB;IACpC,+FAA+F;IAC/F,GAAG,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC;QAAE,MAAM,IAAI,OAAO,CAAC;YAAE,MAAM,EAAE,MAAM,CAAA;SAAE,CAAC,CAAA;KAAE,CAAC,CAAC;CACrE"}
|
|
File without changes
|
|
@@ -0,0 +1,23 @@
|
|
|
1
|
+
import { z } from "zod";
|
|
2
|
+
/**
|
|
3
|
+
* What each of email's two durable jobs is started with.
|
|
4
|
+
*
|
|
5
|
+
* Declared here rather than inline on the capability because **three places now need the same
|
|
6
|
+
* object**: the capability's `workflows` map (which is what the app worker dispatches through), the
|
|
7
|
+
* host's mirrored registry in `provision/resolveEmailConfig.ts` (which derives the deployed Workflow
|
|
8
|
+
* names), and the host's dispatch route, which validates an incoming loopback payload against the
|
|
9
|
+
* declaring spec's own schema before it starts anything (pithy-sh/pithy#410).
|
|
10
|
+
*
|
|
11
|
+
* That last one is why the mirror could no longer carry `z.unknown()`. A params schema that accepts
|
|
12
|
+
* everything turns a malformed dispatch into a durable instance that fails somewhere inside its first
|
|
13
|
+
* step, which is exactly the class of failure the request contract exists to name at the door.
|
|
14
|
+
*/
|
|
15
|
+
/** The batch of queued rows one send Workflow instance is responsible for. */
|
|
16
|
+
export declare const EmailSendParams: z.ZodObject<{
|
|
17
|
+
jobIds: z.ZodArray<z.ZodString>;
|
|
18
|
+
}, z.core.$strip>;
|
|
19
|
+
export type EmailSendParams = z.infer<typeof EmailSendParams>;
|
|
20
|
+
/** The scheduler's parameters: none. It finds its own work. */
|
|
21
|
+
export declare const EmailScheduleParams: z.ZodObject<{}, z.core.$strip>;
|
|
22
|
+
export type EmailScheduleParams = z.infer<typeof EmailScheduleParams>;
|
|
23
|
+
//# sourceMappingURL=params.d.ts.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"params.d.ts","sourceRoot":"","sources":["../../src/workflows/params.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB;;;;;;;;;;;;GAYG;AAEH,8EAA8E;AAC9E,eAAO,MAAM,eAAe;;iBAOyB,CAAC;AACtD,MAAM,MAAM,eAAe,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,eAAe,CAAC,CAAC;AAE9D,+DAA+D;AAC/D,eAAO,MAAM,mBAAmB,gCAE6C,CAAC;AAC9E,MAAM,MAAM,mBAAmB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,mBAAmB,CAAC,CAAC"}
|
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
import { z } from "zod";
|
|
2
|
+
//#region src/workflows/params.ts
|
|
3
|
+
/**
|
|
4
|
+
* What each of email's two durable jobs is started with.
|
|
5
|
+
*
|
|
6
|
+
* Declared here rather than inline on the capability because **three places now need the same
|
|
7
|
+
* object**: the capability's `workflows` map (which is what the app worker dispatches through), the
|
|
8
|
+
* host's mirrored registry in `provision/resolveEmailConfig.ts` (which derives the deployed Workflow
|
|
9
|
+
* names), and the host's dispatch route, which validates an incoming loopback payload against the
|
|
10
|
+
* declaring spec's own schema before it starts anything (pithy-sh/pithy#410).
|
|
11
|
+
*
|
|
12
|
+
* That last one is why the mirror could no longer carry `z.unknown()`. A params schema that accepts
|
|
13
|
+
* everything turns a malformed dispatch into a durable instance that fails somewhere inside its first
|
|
14
|
+
* step, which is exactly the class of failure the request contract exists to name at the door.
|
|
15
|
+
*/
|
|
16
|
+
/** The batch of queued rows one send Workflow instance is responsible for. */
|
|
17
|
+
const EmailSendParams = z.object({ jobIds: z.array(z.string().min(1).describe("A queued `pithy_email_jobs` row id.")).min(1).describe("The batch of queued job ids this instance sends — one durable step each.") }).describe("Parameters for one durable send batch.");
|
|
18
|
+
/** The scheduler's parameters: none. It finds its own work. */
|
|
19
|
+
const EmailScheduleParams = z.object({}).describe("The scheduler takes no parameters — it finds its own due jobs.");
|
|
20
|
+
//#endregion
|
|
21
|
+
export { EmailScheduleParams, EmailSendParams };
|
|
@@ -0,0 +1,82 @@
|
|
|
1
|
+
import type { EmailDatabase } from "../data/tables";
|
|
2
|
+
/**
|
|
3
|
+
* The every-minute scheduler. It finds due rows — `scheduled`/`timezone` jobs whose `sendAt` has
|
|
4
|
+
* arrived, plus the safety net of `pending` and `undispatched` immediate jobs that never dispatched and
|
|
5
|
+
* `sending` jobs left stale by a dead dispatch — claims them (status → `sending`, so the next tick won't
|
|
6
|
+
* repick them), and fans them out into sender batches. **The fan-out scales with volume:** the more rows are due, the
|
|
7
|
+
* more batches are dispatched, each its own durable send Workflow. Cron is cheap; this runs every
|
|
8
|
+
* minute and does nothing when nothing is due.
|
|
9
|
+
*
|
|
10
|
+
* Jobs are claimed before dispatch, so a dispatch failure strands a row in `sending` rather than
|
|
11
|
+
* double-sending; the `sending` re-drive recovers it on a later tick, and `runSend`'s idempotency makes
|
|
12
|
+
* any recovery a no-op for a job that did go out.
|
|
13
|
+
*
|
|
14
|
+
* **The claim is the batch.** Every job claimed in one dispatch carries that batch's id, which is the id
|
|
15
|
+
* of the send Workflow instance started for it, so the tick that finds those rows stale can ask the
|
|
16
|
+
* runtime whether the batch is still alive instead of guessing from a timestamp. That is the whole of
|
|
17
|
+
* the re-drive decision (pithy-sh/pithy#342), and it costs the claim one column and the tick one question
|
|
18
|
+
* per batch.
|
|
19
|
+
*/
|
|
20
|
+
/** Inputs the scheduler needs. `dispatch` creates one send Workflow per batch. */
|
|
21
|
+
export interface SchedulerDeps {
|
|
22
|
+
db: EmailDatabase;
|
|
23
|
+
now: Date;
|
|
24
|
+
/** How stale (ms) a `pending`/`undispatched` immediate job must be before the safety net re-drives it. */
|
|
25
|
+
graceMs: number;
|
|
26
|
+
/**
|
|
27
|
+
* How stale (ms) a job must be before this tick will *consider* re-driving it.
|
|
28
|
+
*
|
|
29
|
+
* **It is a filter, not the verdict.** A row's timestamp cannot say whether the batch holding it is
|
|
30
|
+
* alive: a batch is claimed whole and walked one job at a time, so a job it has not reached carries the
|
|
31
|
+
* claim instant however busy the batch is, and a step waiting out its retry backoff writes nothing at
|
|
32
|
+
* all while being entirely alive. {@link SchedulerDeps.batchIsAlive} settles both; this only decides
|
|
33
|
+
* what is old enough to ask about (pithy-sh/pithy#342).
|
|
34
|
+
*
|
|
35
|
+
* So it is not a knob for outrunning a long queue. Widening it to cover one would be a race with a
|
|
36
|
+
* slower horse, and the queue gets longer.
|
|
37
|
+
*/
|
|
38
|
+
stuckMs: number;
|
|
39
|
+
/**
|
|
40
|
+
* Jobs per dispatched batch — one send Workflow each. From `SCHEDULER_BATCH_SIZE`.
|
|
41
|
+
*
|
|
42
|
+
* **A fan-out knob, and nothing else.** It has no ceiling: the claim statement sizes itself against
|
|
43
|
+
* D1's bound-parameter cap independently, so raising this changes how many Workflows a tick starts and
|
|
44
|
+
* cannot make a statement too wide. It used to be both, and 100 was enough to fail every tick (#250).
|
|
45
|
+
*/
|
|
46
|
+
batchSize: number;
|
|
47
|
+
/** The most jobs to claim in one tick. */
|
|
48
|
+
maxJobs: number;
|
|
49
|
+
/**
|
|
50
|
+
* Mint the id of a batch about to be dispatched. It **is** the send Workflow's instance id, which is
|
|
51
|
+
* what lets {@link SchedulerDeps.batchIsAlive} ask the runtime about it later.
|
|
52
|
+
*/
|
|
53
|
+
newBatchId: () => string;
|
|
54
|
+
/**
|
|
55
|
+
* Is the send Workflow instance holding this batch still alive? (pithy-sh/pithy#342)
|
|
56
|
+
*
|
|
57
|
+
* The question a row cannot answer. A Workflow that exists and is scheduled to retry is alive, and its
|
|
58
|
+
* rows are as untouched as a dead dispatch's; a batch three quarters of the way down a long queue is
|
|
59
|
+
* alive, and the quarter it has not reached is as untouched again. Both used to read as stranded, and
|
|
60
|
+
* a re-drive of either is a second send Workflow over a job the first will reach — a double-send.
|
|
61
|
+
*
|
|
62
|
+
* **It may only ever veto a re-drive, never cause one.** A stale row with no batch, or one whose batch
|
|
63
|
+
* this cannot vouch for, is re-driven exactly as it was before this existed. That is what keeps the
|
|
64
|
+
* safety net intact and makes the new question incapable of sending an extra email: the worst an
|
|
65
|
+
* unavailable answer can do is decline to save one.
|
|
66
|
+
*/
|
|
67
|
+
batchIsAlive: (batchId: string) => Promise<boolean>;
|
|
68
|
+
/** Create a send Workflow for a batch of job ids, under the batch's id as the instance id. */
|
|
69
|
+
dispatch: (batchId: string, jobIds: string[]) => Promise<void>;
|
|
70
|
+
}
|
|
71
|
+
/** What one scheduler tick did. */
|
|
72
|
+
export interface SchedulerResult {
|
|
73
|
+
/** How many due jobs were claimed. */
|
|
74
|
+
due: number;
|
|
75
|
+
/** How many batches were dispatched (scales with volume). */
|
|
76
|
+
batches: number;
|
|
77
|
+
/** How many stale-looking jobs were left alone because the batch holding them is still alive. */
|
|
78
|
+
held: number;
|
|
79
|
+
}
|
|
80
|
+
/** Run one scheduler tick: find due rows, claim them, fan out batches. */
|
|
81
|
+
export declare function runScheduler(deps: SchedulerDeps): Promise<SchedulerResult>;
|
|
82
|
+
//# sourceMappingURL=scheduler.d.ts.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"scheduler.d.ts","sourceRoot":"","sources":["../../src/workflows/scheduler.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,gBAAgB,CAAC;AAEpD;;;;;;;;;;;;;;;;;GAiBG;AAEH,kFAAkF;AAClF,MAAM,WAAW,aAAa;IAC5B,EAAE,EAAE,aAAa,CAAC;IAClB,GAAG,EAAE,IAAI,CAAC;IACV,0GAA0G;IAC1G,OAAO,EAAE,MAAM,CAAC;IAChB;;;;;;;;;;;OAWG;IACH,OAAO,EAAE,MAAM,CAAC;IAChB;;;;;;OAMG;IACH,SAAS,EAAE,MAAM,CAAC;IAClB,0CAA0C;IAC1C,OAAO,EAAE,MAAM,CAAC;IAChB;;;OAGG;IACH,UAAU,EAAE,MAAM,MAAM,CAAC;IACzB;;;;;;;;;;;;OAYG;IACH,YAAY,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,OAAO,CAAC,OAAO,CAAC,CAAC;IACpD,8FAA8F;IAC9F,QAAQ,EAAE,CAAC,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;CAChE;AAED,mCAAmC;AACnC,MAAM,WAAW,eAAe;IAC9B,sCAAsC;IACtC,GAAG,EAAE,MAAM,CAAC;IACZ,6DAA6D;IAC7D,OAAO,EAAE,MAAM,CAAC;IAChB,iGAAiG;IACjG,IAAI,EAAE,MAAM,CAAC;CACd;AA4ED,0EAA0E;AAC1E,wBAAsB,YAAY,CAAC,IAAI,EAAE,aAAa,GAAG,OAAO,CAAC,eAAe,CAAC,CAwDhF"}
|
|
@@ -0,0 +1,111 @@
|
|
|
1
|
+
import { ValidationError } from "@pithy-sh/core/src/error/pithyError";
|
|
2
|
+
import { chunkByBoundParameters } from "@pithy-sh/core/src/data/boundParameters";
|
|
3
|
+
//#region src/workflows/scheduler.ts
|
|
4
|
+
/**
|
|
5
|
+
* How many parameters the claim statement binds besides the job ids: `status`, `updatedAt`, `batchId`.
|
|
6
|
+
*
|
|
7
|
+
* Named here so that adding a column to the `set` is a one-number edit beside it, rather than a silent
|
|
8
|
+
* re-break of a limit nobody re-derived.
|
|
9
|
+
*/
|
|
10
|
+
const CLAIM_FIXED_PARAMETERS = 3;
|
|
11
|
+
/**
|
|
12
|
+
* Refuse a batch size that is not a count at all — checked before the tick does any work.
|
|
13
|
+
*
|
|
14
|
+
* `Number(env.SCHEDULER_BATCH_SIZE)` yields `NaN` for a typo, and `NaN` used to produce exactly one
|
|
15
|
+
* empty batch: no job claimed, no job sent, no error, every minute. There is no safe number to clamp a
|
|
16
|
+
* typo to, so it is named and refused.
|
|
17
|
+
*
|
|
18
|
+
* What is *not* refused is a large one. It carries no platform limit any more — see
|
|
19
|
+
* {@link dispatchBatches}.
|
|
20
|
+
*/
|
|
21
|
+
function assertBatchSize(batchSize) {
|
|
22
|
+
if (!Number.isInteger(batchSize) || batchSize < 1) throw new ValidationError({
|
|
23
|
+
message: "The email scheduler is misconfigured.",
|
|
24
|
+
action: "Set SCHEDULER_BATCH_SIZE to a whole number of one or more, or unset it for the default of 50.",
|
|
25
|
+
detail: `SCHEDULER_BATCH_SIZE resolved to ${batchSize}; it must be a positive integer.`
|
|
26
|
+
});
|
|
27
|
+
}
|
|
28
|
+
/**
|
|
29
|
+
* Split the due jobs into the batches this tick will dispatch — the **fan-out** split, not the
|
|
30
|
+
* parameter one.
|
|
31
|
+
*
|
|
32
|
+
* The two used to be the same list, which is how `SCHEDULER_BATCH_SIZE` came to decide the width of a
|
|
33
|
+
* D1 statement. They are separated now: this decides how many send Workflows a tick starts, and
|
|
34
|
+
* {@link chunkByBoundParameters} decides how wide the claim that precedes each one may be. So the
|
|
35
|
+
* operator's number carries no platform limit, and the platform limit needs no operator.
|
|
36
|
+
*/
|
|
37
|
+
function dispatchBatches(ids, batchSize) {
|
|
38
|
+
const out = [];
|
|
39
|
+
for (let start = 0; start < ids.length; start += batchSize) out.push(ids.slice(start, start + batchSize));
|
|
40
|
+
return out;
|
|
41
|
+
}
|
|
42
|
+
/**
|
|
43
|
+
* Drop the candidates a live batch still holds, and return the rest (pithy-sh/pithy#342).
|
|
44
|
+
*
|
|
45
|
+
* A candidate is a row the timestamps say *might* be stranded. Deciding it actually is takes the batch,
|
|
46
|
+
* so every row naming one is settled by {@link SchedulerDeps.batchIsAlive} — asked **once per batch**,
|
|
47
|
+
* not once per row, because fifty rows of a stalled batch are one question about one Workflow.
|
|
48
|
+
*
|
|
49
|
+
* A row naming no batch is stranded by definition: nothing claimed it, or whatever did died before it
|
|
50
|
+
* could say so. That is the safety net, and it is deliberately untouched here.
|
|
51
|
+
*/
|
|
52
|
+
async function strandedIds(deps, rows) {
|
|
53
|
+
const answered = /* @__PURE__ */ new Map();
|
|
54
|
+
const stranded = [];
|
|
55
|
+
for (const row of rows) {
|
|
56
|
+
const batchId = row.batchId;
|
|
57
|
+
if (batchId) {
|
|
58
|
+
let alive = answered.get(batchId);
|
|
59
|
+
if (alive === void 0) {
|
|
60
|
+
alive = await deps.batchIsAlive(batchId);
|
|
61
|
+
answered.set(batchId, alive);
|
|
62
|
+
}
|
|
63
|
+
if (alive) continue;
|
|
64
|
+
}
|
|
65
|
+
stranded.push(row.id);
|
|
66
|
+
}
|
|
67
|
+
return stranded;
|
|
68
|
+
}
|
|
69
|
+
/** Run one scheduler tick: find due rows, claim them, fan out batches. */
|
|
70
|
+
async function runScheduler(deps) {
|
|
71
|
+
assertBatchSize(deps.batchSize);
|
|
72
|
+
const nowMs = deps.now.getTime();
|
|
73
|
+
const graceCutoff = nowMs - deps.graceMs;
|
|
74
|
+
const stuckCutoff = nowMs - deps.stuckMs;
|
|
75
|
+
const rows = await deps.db.selectFrom("pithyEmailJobs").select(["id", "batchId"]).where((eb) => eb.or([
|
|
76
|
+
eb.and([eb("status", "=", "scheduled"), eb("sendAt", "<=", nowMs)]),
|
|
77
|
+
eb.and([eb("status", "in", ["pending", "undispatched"]), eb("createdAt", "<=", graceCutoff)]),
|
|
78
|
+
eb.and([eb("status", "=", "sending"), eb("updatedAt", "<=", stuckCutoff)])
|
|
79
|
+
])).orderBy("sendAt", "asc").limit(deps.maxJobs).execute();
|
|
80
|
+
if (rows.length === 0) return {
|
|
81
|
+
due: 0,
|
|
82
|
+
batches: 0,
|
|
83
|
+
held: 0
|
|
84
|
+
};
|
|
85
|
+
const ids = await strandedIds(deps, rows);
|
|
86
|
+
const held = rows.length - ids.length;
|
|
87
|
+
if (ids.length === 0) return {
|
|
88
|
+
due: 0,
|
|
89
|
+
batches: 0,
|
|
90
|
+
held
|
|
91
|
+
};
|
|
92
|
+
const batches = dispatchBatches(ids, deps.batchSize);
|
|
93
|
+
let dispatched = 0;
|
|
94
|
+
for (const batch of batches) {
|
|
95
|
+
const batchId = deps.newBatchId();
|
|
96
|
+
for (const claim of chunkByBoundParameters(batch, CLAIM_FIXED_PARAMETERS)) await deps.db.updateTable("pithyEmailJobs").set({
|
|
97
|
+
status: "sending",
|
|
98
|
+
updatedAt: nowMs,
|
|
99
|
+
batchId
|
|
100
|
+
}).where("id", "in", claim).execute();
|
|
101
|
+
await deps.dispatch(batchId, batch);
|
|
102
|
+
dispatched += 1;
|
|
103
|
+
}
|
|
104
|
+
return {
|
|
105
|
+
due: ids.length,
|
|
106
|
+
batches: dispatched,
|
|
107
|
+
held
|
|
108
|
+
};
|
|
109
|
+
}
|
|
110
|
+
//#endregion
|
|
111
|
+
export { runScheduler };
|
|
@@ -0,0 +1,85 @@
|
|
|
1
|
+
import { type SendDeps, type SendOutcome } from "../send/runSend";
|
|
2
|
+
/**
|
|
3
|
+
* The send batch — the body `EmailSendWorkflow.run` hands its step runner to.
|
|
4
|
+
*
|
|
5
|
+
* **Why it is here and not in the Workflow class.** `worker.ts` imports `cloudflare:workers`, which
|
|
6
|
+
* resolves in workerd and nowhere else, so anything inside it can only be exercised by deploying it.
|
|
7
|
+
* Every property worth proving about this body is a property of a *resume* — a Workflow does not resume
|
|
8
|
+
* inside the step it died in, it re-executes this function from the top and serves every completed step
|
|
9
|
+
* from the journal — and the only way to know a resume behaves is to drive one.
|
|
10
|
+
*
|
|
11
|
+
* **One step per job.** Each is independently retried and backed off by the Workflow runtime, and a step
|
|
12
|
+
* whose retries are spent is contained here, so a single bad recipient never blocks the rest of the
|
|
13
|
+
* batch. That sentence has been in this docblock since the file was written and the code did not do it
|
|
14
|
+
* until #380: the throw came out of the loop and took every job behind it, on this attempt and on every
|
|
15
|
+
* replay of the body.
|
|
16
|
+
*
|
|
17
|
+
* **The batch is the unit of liveness, and it says so by existing.** The scheduler claims a whole batch
|
|
18
|
+
* up front, stamps every row with the batch's id — which is this Workflow instance's id — and dispatches
|
|
19
|
+
* one instance for it. So a job this body has not reached is queued, not stranded, and the scheduler
|
|
20
|
+
* establishes that by asking the runtime whether the instance is still running.
|
|
21
|
+
*
|
|
22
|
+
* That is why nothing here writes to a job it is not sending. The previous answer had each step renew the
|
|
23
|
+
* claim on every job behind it (pithy-sh/pithy#340), which is correct and costs N(N-1)/2 row updates for
|
|
24
|
+
* a batch of N — 1,225 at the shipped batch size of 50, on a setting with no ceiling — and still could
|
|
25
|
+
* not speak for a step waiting out its retry backoff, because a body that is not running renews nothing
|
|
26
|
+
* (pithy-sh/pithy#342). One question to the runtime answers both, and writes nothing.
|
|
27
|
+
*/
|
|
28
|
+
/** The durable step runner, structurally. Injected, so a test can drive an interrupt and a resume. */
|
|
29
|
+
export interface SendBatchStep {
|
|
30
|
+
/** Run a named step, or return its journaled result if this instance already completed it. */
|
|
31
|
+
do<T>(name: string, fn: () => Promise<T>): Promise<T>;
|
|
32
|
+
}
|
|
33
|
+
/**
|
|
34
|
+
* What a batch needs: everything one send needs, minus the pass instant it journals for itself.
|
|
35
|
+
*
|
|
36
|
+
* `heartbeatAt` is the clock, and it stays a thunk all the way down — `runSend` reads it afresh on every
|
|
37
|
+
* patch. The pass instant is *one journaled read of the same clock*, which is the whole design in a
|
|
38
|
+
* sentence: one source, two lifetimes, and neither of them able to answer for the other.
|
|
39
|
+
*/
|
|
40
|
+
export type SendBatchDeps = Omit<SendDeps, "passStartedAt">;
|
|
41
|
+
/**
|
|
42
|
+
* One job's place in the batch — **two states, and the outcome lives behind the one that has it**
|
|
43
|
+
* (#380).
|
|
44
|
+
*
|
|
45
|
+
* A step exhausts its retries and throws, and the docblock above promises that never blocks the rest of
|
|
46
|
+
* the batch. It did not: the throw propagated out of the loop and every job behind it went unsent, on
|
|
47
|
+
* this attempt and on every retry of the body, because a re-execution replays the journal and reaches
|
|
48
|
+
* the same failing step again. A batch of fifty lost forty-seven messages to one bad recipient.
|
|
49
|
+
*
|
|
50
|
+
* The two states share no field, so a caller cannot reach an outcome without narrowing, and a job the
|
|
51
|
+
* batch could not finish cannot be read as one that was skipped for a reason `runSend` names. What
|
|
52
|
+
* happens to that job next is the scheduler's: its row is still `sending` or `failed`, and the
|
|
53
|
+
* `stuckMs` re-drive is what picks it up.
|
|
54
|
+
*/
|
|
55
|
+
export type BatchJobResult = {
|
|
56
|
+
/** The send ran to a conclusion — sent, suppressed, canceled or terminally failed. */
|
|
57
|
+
state: "attempted";
|
|
58
|
+
/** The job this is about. */
|
|
59
|
+
jobId: string;
|
|
60
|
+
/** What the send concluded. Present here alone. */
|
|
61
|
+
outcome: SendOutcome;
|
|
62
|
+
} | {
|
|
63
|
+
/**
|
|
64
|
+
* The step did not finish: it threw, and its retries within this instance are spent. Nothing is
|
|
65
|
+
* claimed about the job beyond that — it may have been rendered, it may have been sent and the
|
|
66
|
+
* write lost.
|
|
67
|
+
*/
|
|
68
|
+
state: "unfinished";
|
|
69
|
+
/** The job this is about — the only fact this state carries. */
|
|
70
|
+
jobId: string;
|
|
71
|
+
};
|
|
72
|
+
/**
|
|
73
|
+
* What one batch did, one entry per job in dispatch order.
|
|
74
|
+
*
|
|
75
|
+
* Returned rather than logged because this capability has no logger seam and a Workflow's return value
|
|
76
|
+
* *is* its instance output — so the record lands where an operator already looks when a batch is in
|
|
77
|
+
* question, next to the step journal that shows which step failed.
|
|
78
|
+
*/
|
|
79
|
+
export interface BatchSendReport {
|
|
80
|
+
/** One entry per job id the batch was dispatched with, in that order. */
|
|
81
|
+
jobs: BatchJobResult[];
|
|
82
|
+
}
|
|
83
|
+
/** Send one batch of jobs, one durable step each. */
|
|
84
|
+
export declare function runSendBatch(deps: SendBatchDeps, step: SendBatchStep, jobIds: readonly string[]): Promise<BatchSendReport>;
|
|
85
|
+
//# sourceMappingURL=sendBatch.d.ts.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"sendBatch.d.ts","sourceRoot":"","sources":["../../src/workflows/sendBatch.ts"],"names":[],"mappings":"AAGA,OAAO,EAAW,KAAK,QAAQ,EAAE,KAAK,WAAW,EAAE,MAAM,iBAAiB,CAAC;AAE3E;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AAEH,sGAAsG;AACtG,MAAM,WAAW,aAAa;IAC5B,8FAA8F;IAC9F,EAAE,CAAC,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,CAAC;CACvD;AAED;;;;;;GAMG;AACH,MAAM,MAAM,aAAa,GAAG,IAAI,CAAC,QAAQ,EAAE,eAAe,CAAC,CAAC;AAE5D;;;;;;;;;;;;;GAaG;AACH,MAAM,MAAM,cAAc,GACtB;IACE,sFAAsF;IACtF,KAAK,EAAE,WAAW,CAAC;IACnB,6BAA6B;IAC7B,KAAK,EAAE,MAAM,CAAC;IACd,mDAAmD;IACnD,OAAO,EAAE,WAAW,CAAC;CACtB,GACD;IACE;;;;OAIG;IACH,KAAK,EAAE,YAAY,CAAC;IACpB,gEAAgE;IAChE,KAAK,EAAE,MAAM,CAAC;CACf,CAAC;AAEN;;;;;;GAMG;AACH,MAAM,WAAW,eAAe;IAC9B,yEAAyE;IACzE,IAAI,EAAE,cAAc,EAAE,CAAC;CACxB;AAED,qDAAqD;AACrD,wBAAsB,YAAY,CAChC,IAAI,EAAE,aAAa,EACnB,IAAI,EAAE,aAAa,EACnB,MAAM,EAAE,SAAS,MAAM,EAAE,GACxB,OAAO,CAAC,eAAe,CAAC,CAuD1B"}
|
|
@@ -0,0 +1,50 @@
|
|
|
1
|
+
import { runSend } from "../send/runSend.js";
|
|
2
|
+
//#region src/workflows/sendBatch.ts
|
|
3
|
+
/** Send one batch of jobs, one durable step each. */
|
|
4
|
+
async function runSendBatch(deps, step, jobIds) {
|
|
5
|
+
/**
|
|
6
|
+
* The pass instant, journaled (pithy-sh/pithy#327).
|
|
7
|
+
*
|
|
8
|
+
* One read of `heartbeatAt`, taken inside a step so a resume reads back the instant the batch began
|
|
9
|
+
* rather than the instant it came back. It dates the work — `sentAt`, the redaction stamp, the events,
|
|
10
|
+
* and every tracked link's expiry.
|
|
11
|
+
*
|
|
12
|
+
* **What is deliberately not journaled is the clock itself.** `deps.heartbeatAt` goes through to
|
|
13
|
+
* `runSend` as a thunk, because `updatedAt` is what decides a `sending` job is old enough to ask about
|
|
14
|
+
* at all, and a frozen one puts a job the batch is mid-flight on in front of that question every tick.
|
|
15
|
+
* The batch's own liveness answers it correctly either way; a clock that lies is still a clock that
|
|
16
|
+
* lies, and `sentAt` is not the only thing reading this.
|
|
17
|
+
*
|
|
18
|
+
* Epoch milliseconds rather than a `Date`, because a journal round-trips JSON: a `Date` would come back
|
|
19
|
+
* a string on the resume and an object on the first pass.
|
|
20
|
+
*/
|
|
21
|
+
const passStartedAtMs = await step.do("pass-instant", async () => deps.heartbeatAt().getTime());
|
|
22
|
+
const sendDeps = {
|
|
23
|
+
...deps,
|
|
24
|
+
passStartedAt: new Date(passStartedAtMs)
|
|
25
|
+
};
|
|
26
|
+
const jobs = [];
|
|
27
|
+
for (const jobId of jobIds) {
|
|
28
|
+
let began = false;
|
|
29
|
+
try {
|
|
30
|
+
const outcome = await step.do(`send-${jobId}`, async () => {
|
|
31
|
+
began = true;
|
|
32
|
+
return await runSend(sendDeps, jobId);
|
|
33
|
+
});
|
|
34
|
+
jobs.push({
|
|
35
|
+
state: "attempted",
|
|
36
|
+
jobId,
|
|
37
|
+
outcome
|
|
38
|
+
});
|
|
39
|
+
} catch (interrupted) {
|
|
40
|
+
if (!began) throw interrupted;
|
|
41
|
+
jobs.push({
|
|
42
|
+
state: "unfinished",
|
|
43
|
+
jobId
|
|
44
|
+
});
|
|
45
|
+
}
|
|
46
|
+
}
|
|
47
|
+
return { jobs };
|
|
48
|
+
}
|
|
49
|
+
//#endregion
|
|
50
|
+
export { runSendBatch };
|