@pithy-sh/email 0.1.5 → 0.1.7
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/provision/provisionEmail.d.ts +22 -4
- package/dist/provision/provisionEmail.d.ts.map +1 -1
- package/dist/provision/provisionEmail.js +40 -10
- package/dist/provision/settingsCheck.d.ts.map +1 -1
- package/dist/provision/settingsCheck.js +35 -0
- package/dist/version.generated.d.ts +1 -1
- package/dist/version.generated.js +1 -1
- package/dist/workflows/hostApp.d.ts.map +1 -1
- package/dist/workflows/hostApp.js +2 -2
- package/package.json +3 -3
- package/pithy.manifest.json +1 -1
- package/src/provision/provisionEmail.ts +42 -9
- package/src/provision/settingsCheck.ts +36 -0
- package/src/version.generated.ts +1 -1
- package/src/workflows/hostApp.ts +4 -3
|
@@ -26,6 +26,8 @@ import { type ManagedEnvironment } from "@pithy-sh/secrets/src/scope";
|
|
|
26
26
|
*/
|
|
27
27
|
/** The capability segment every email-owned name carries — the migration namespace and error domain too. */
|
|
28
28
|
export declare const EMAIL_CAPABILITY = "email";
|
|
29
|
+
/** The D1 binding the suppression database is bound to, in every Worker and every environment. */
|
|
30
|
+
export declare const EMAIL_SUPPRESSIONS_BINDING = "EMAIL_SUPPRESSIONS";
|
|
29
31
|
/**
|
|
30
32
|
* The shared, durable suppression database — **one per project, shared across that project's
|
|
31
33
|
* environments**: `<project>-global-email-suppressions`.
|
|
@@ -44,6 +46,17 @@ export declare const EMAIL_CAPABILITY = "email";
|
|
|
44
46
|
*
|
|
45
47
|
* Composed through core's naming facade under the **`d1`** namespace, so the name is measured against
|
|
46
48
|
* a D1 database name's limit rather than the single 63 the generic composer defaults to.
|
|
49
|
+
*
|
|
50
|
+
* **Through {@link bindingResourceName}, the same expression `pithy add` and `pithy provision` compose
|
|
51
|
+
* with — because until #513 it was a *different* expression, and that was the defect.** This function
|
|
52
|
+
* said `<project>-global-email-suppressions` while the two writers said `<project>-<env>-email-
|
|
53
|
+
* suppressions`, so `pithy add email` wrote three per-environment databases into `wrangler.jsonc` and
|
|
54
|
+
* `pithy email provision` created the one this names. The app Worker and the email Worker then read
|
|
55
|
+
* different suppression lists, and an unsubscribe recorded on either was invisible to the other. One
|
|
56
|
+
* expression, driven by one declaration, is what makes that unexpressible rather than merely fixed.
|
|
57
|
+
*
|
|
58
|
+
* The output is byte-identical to what it always was: `kebab("EMAIL_SUPPRESSIONS")` is
|
|
59
|
+
* `email-suppressions`, and the composer's `global` branch is the facade call this used to make directly.
|
|
47
60
|
*/
|
|
48
61
|
export declare function suppressionDatabaseName(project: string): string;
|
|
49
62
|
/**
|
|
@@ -108,12 +121,17 @@ export interface EmailProvisionResult {
|
|
|
108
121
|
}
|
|
109
122
|
/**
|
|
110
123
|
* Provision the email infrastructure: create + migrate the shared suppression DB once, then deploy the
|
|
111
|
-
* email worker for every
|
|
124
|
+
* email worker for every environment given. The order matters — the suppression DB exists and is
|
|
112
125
|
* migrated before any worker that binds it is deployed. Idempotent end to end (each step is).
|
|
113
126
|
*
|
|
114
|
-
* `environments` is the
|
|
115
|
-
*
|
|
116
|
-
*
|
|
127
|
+
* `environments` is **what the caller determined it can act on**, which the CLI narrows from the project's
|
|
128
|
+
* declaration (#241) to the environments whose app database exists (pithy-sh/pithy#512). Nothing is
|
|
129
|
+
* skipped here and nothing decides here: an environment reaching this list is provisioned, and one that
|
|
130
|
+
* did not was already reported to the operator by name, with why and with the command that fixes it.
|
|
131
|
+
*
|
|
132
|
+
* The suppression database is created **whatever the list holds, including nothing**. It is one per
|
|
133
|
+
* project, shared across every environment, and making it wait for the last environment to be provisioned
|
|
134
|
+
* is exactly the ordering this change exists to undo.
|
|
117
135
|
*/
|
|
118
136
|
export declare function provisionEmail(provisioner: EmailProvisioner, environments: DeclaredEnvironments | readonly string[]): Promise<EmailProvisionResult>;
|
|
119
137
|
/** The teardown seam — the inverse of {@link EmailProvisioner}. Every step idempotent (a missing resource is a no-op). */
|
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"provisionEmail.d.ts","sourceRoot":"","sources":["../../src/provision/provisionEmail.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,uCAAuC,CAAC;
|
|
1
|
+
{"version":3,"file":"provisionEmail.d.ts","sourceRoot":"","sources":["../../src/provision/provisionEmail.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,uCAAuC,CAAC;AAKlF,OAAO,EAAE,KAAK,kBAAkB,EAAuB,MAAM,6BAA6B,CAAC;AAE3F;;;;;;;;;;;;;;;;;;;;;GAqBG;AAEH,4GAA4G;AAC5G,eAAO,MAAM,gBAAgB,UAAU,CAAC;AAExC,kGAAkG;AAClG,eAAO,MAAM,0BAA0B,uBAAuB,CAAC;AAW/D;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH,wBAAgB,uBAAuB,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAE/D;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,qBAAqB,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAE7D;AAED;;;;;;GAMG;AACH,wBAAgB,eAAe,CAAC,OAAO,EAAE,MAAM,EAAE,GAAG,EAAE,kBAAkB,GAAG,MAAM,CAEhF;AAED,uEAAuE;AACvE,MAAM,WAAW,gBAAgB;IAC/B;;;;OAIG;IACH,SAAS,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;IAC3B,6GAA6G;IAC7G,yBAAyB,IAAI,OAAO,CAAC;QAAE,UAAU,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IAC7D,8GAA8G;IAC9G,kBAAkB,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACtD,sHAAsH;IACtH,YAAY,CAAC,GAAG,EAAE,kBAAkB,EAAE,qBAAqB,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACpF;;;;;OAKG;IACH,iBAAiB,IAAI,OAAO,CAAC;QAAE,OAAO,EAAE,OAAO,CAAC;QAAC,OAAO,EAAE,OAAO,CAAA;KAAE,CAAC,CAAC;CACtE;AAED,kCAAkC;AAClC,MAAM,WAAW,oBAAoB;IACnC,qBAAqB,EAAE,MAAM,CAAC;IAC9B,YAAY,EAAE,kBAAkB,EAAE,CAAC;IACnC,kGAAkG;IAClG,OAAO,EAAE;QAAE,OAAO,EAAE,OAAO,CAAC;QAAC,OAAO,EAAE,OAAO,CAAA;KAAE,CAAC;CACjD;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAsB,cAAc,CAClC,WAAW,EAAE,gBAAgB,EAC7B,YAAY,EAAE,oBAAoB,GAAG,SAAS,MAAM,EAAE,GACrD,OAAO,CAAC,oBAAoB,CAAC,CAc/B;AAED,0HAA0H;AAC1H,MAAM,WAAW,kBAAkB;IACjC,+EAA+E;IAC/E,YAAY,CAAC,GAAG,EAAE,kBAAkB,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACrD;;;;OAIG;IACH,yBAAyB,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CAC5C;AAED,+GAA+G;AAC/G,MAAM,WAAW,uBAAuB;IACtC,gGAAgG;IAChG,iBAAiB,CAAC,EAAE,OAAO,CAAC;CAC7B;AAED;;;;;;;;GAQG;AACH,wBAAsB,gBAAgB,CACpC,aAAa,EAAE,kBAAkB,EACjC,YAAY,EAAE,oBAAoB,GAAG,SAAS,MAAM,EAAE,EACtD,OAAO,GAAE,uBAA4B,GACpC,OAAO,CAAC,IAAI,CAAC,CAKf"}
|
|
@@ -1,6 +1,7 @@
|
|
|
1
1
|
// SPDX-FileCopyrightText: 2026 Pithy
|
|
2
2
|
// SPDX-License-Identifier: MIT
|
|
3
3
|
import { GLOBAL_SCOPE } from "@pithy-sh/core/src/naming/environment";
|
|
4
|
+
import { bindingResourceName } from "@pithy-sh/core/src/naming/provisionScope";
|
|
4
5
|
import { resourceName } from "@pithy-sh/core/src/naming/resource";
|
|
5
6
|
import { resourceNames } from "@pithy-sh/core/src/naming/resourceNames";
|
|
6
7
|
import { managedEnvironments } from "@pithy-sh/secrets/src/scope";
|
|
@@ -29,6 +30,16 @@ import { managedEnvironments } from "@pithy-sh/secrets/src/scope";
|
|
|
29
30
|
*/
|
|
30
31
|
/** The capability segment every email-owned name carries — the migration namespace and error domain too. */
|
|
31
32
|
const EMAIL_CAPABILITY = "email";
|
|
33
|
+
/** The D1 binding the suppression database is bound to, in every Worker and every environment. */
|
|
34
|
+
const EMAIL_SUPPRESSIONS_BINDING = "EMAIL_SUPPRESSIONS";
|
|
35
|
+
/**
|
|
36
|
+
* What `packages/email/pithy.manifest.json` declares about naming {@link EMAIL_SUPPRESSIONS_BINDING} —
|
|
37
|
+
* restated here because a bundled Worker package cannot read its own manifest, and **pinned to it by
|
|
38
|
+
* `cli/src/ci/bindingResourceNames.test.ts`**, which fails the moment the two answers differ.
|
|
39
|
+
*
|
|
40
|
+
* No `resource`: `email-suppressions` is the kebabbed binding, which is what the composer already uses.
|
|
41
|
+
*/
|
|
42
|
+
const EMAIL_SUPPRESSIONS_NAMING = { scope: GLOBAL_SCOPE };
|
|
32
43
|
/**
|
|
33
44
|
* The shared, durable suppression database — **one per project, shared across that project's
|
|
34
45
|
* environments**: `<project>-global-email-suppressions`.
|
|
@@ -47,9 +58,20 @@ const EMAIL_CAPABILITY = "email";
|
|
|
47
58
|
*
|
|
48
59
|
* Composed through core's naming facade under the **`d1`** namespace, so the name is measured against
|
|
49
60
|
* a D1 database name's limit rather than the single 63 the generic composer defaults to.
|
|
61
|
+
*
|
|
62
|
+
* **Through {@link bindingResourceName}, the same expression `pithy add` and `pithy provision` compose
|
|
63
|
+
* with — because until #513 it was a *different* expression, and that was the defect.** This function
|
|
64
|
+
* said `<project>-global-email-suppressions` while the two writers said `<project>-<env>-email-
|
|
65
|
+
* suppressions`, so `pithy add email` wrote three per-environment databases into `wrangler.jsonc` and
|
|
66
|
+
* `pithy email provision` created the one this names. The app Worker and the email Worker then read
|
|
67
|
+
* different suppression lists, and an unsubscribe recorded on either was invisible to the other. One
|
|
68
|
+
* expression, driven by one declaration, is what makes that unexpressible rather than merely fixed.
|
|
69
|
+
*
|
|
70
|
+
* The output is byte-identical to what it always was: `kebab("EMAIL_SUPPRESSIONS")` is
|
|
71
|
+
* `email-suppressions`, and the composer's `global` branch is the facade call this used to make directly.
|
|
50
72
|
*/
|
|
51
73
|
function suppressionDatabaseName(project) {
|
|
52
|
-
return
|
|
74
|
+
return bindingResourceName(project, EMAIL_SUPPRESSIONS_BINDING, "d1", EMAIL_SUPPRESSIONS_NAMING);
|
|
53
75
|
}
|
|
54
76
|
/**
|
|
55
77
|
* The name of the inbound Email Routing rule that delivers bounce and complaint mail to the app worker.
|
|
@@ -84,23 +106,31 @@ function emailWorkerName(project, env) {
|
|
|
84
106
|
}
|
|
85
107
|
/**
|
|
86
108
|
* Provision the email infrastructure: create + migrate the shared suppression DB once, then deploy the
|
|
87
|
-
* email worker for every
|
|
109
|
+
* email worker for every environment given. The order matters — the suppression DB exists and is
|
|
88
110
|
* migrated before any worker that binds it is deployed. Idempotent end to end (each step is).
|
|
89
111
|
*
|
|
90
|
-
* `environments` is the
|
|
91
|
-
*
|
|
92
|
-
*
|
|
112
|
+
* `environments` is **what the caller determined it can act on**, which the CLI narrows from the project's
|
|
113
|
+
* declaration (#241) to the environments whose app database exists (pithy-sh/pithy#512). Nothing is
|
|
114
|
+
* skipped here and nothing decides here: an environment reaching this list is provisioned, and one that
|
|
115
|
+
* did not was already reported to the operator by name, with why and with the command that fixes it.
|
|
116
|
+
*
|
|
117
|
+
* The suppression database is created **whatever the list holds, including nothing**. It is one per
|
|
118
|
+
* project, shared across every environment, and making it wait for the last environment to be provisioned
|
|
119
|
+
* is exactly the ordering this change exists to undo.
|
|
93
120
|
*/
|
|
94
121
|
async function provisionEmail(provisioner, environments) {
|
|
95
122
|
await provisioner.preflight();
|
|
96
123
|
const { databaseId } = await provisioner.ensureSuppressionDatabase();
|
|
97
124
|
await provisioner.migrateSuppression(databaseId);
|
|
98
|
-
|
|
99
|
-
const
|
|
125
|
+
const deployed = managedEnvironments(environments);
|
|
126
|
+
for (const env of deployed) await provisioner.deployWorker(env, databaseId);
|
|
100
127
|
return {
|
|
101
128
|
suppressionDatabaseId: databaseId,
|
|
102
|
-
environments:
|
|
103
|
-
routing
|
|
129
|
+
environments: deployed,
|
|
130
|
+
routing: deployed.length > 0 ? await provisioner.ensureRoutingRule() : {
|
|
131
|
+
created: false,
|
|
132
|
+
skipped: true
|
|
133
|
+
}
|
|
104
134
|
};
|
|
105
135
|
}
|
|
106
136
|
/**
|
|
@@ -117,4 +147,4 @@ async function deprovisionEmail(deprovisioner, environments, options = {}) {
|
|
|
117
147
|
if (options.deleteSuppression) await deprovisioner.deleteSuppressionDatabase();
|
|
118
148
|
}
|
|
119
149
|
//#endregion
|
|
120
|
-
export { EMAIL_CAPABILITY, bounceRoutingRuleName, deprovisionEmail, emailWorkerName, provisionEmail, suppressionDatabaseName };
|
|
150
|
+
export { EMAIL_CAPABILITY, EMAIL_SUPPRESSIONS_BINDING, bounceRoutingRuleName, deprovisionEmail, emailWorkerName, provisionEmail, suppressionDatabaseName };
|
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"settingsCheck.d.ts","sourceRoot":"","sources":["../../src/provision/settingsCheck.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EACV,kBAAkB,EAInB,MAAM,wCAAwC,CAAC;
|
|
1
|
+
{"version":3,"file":"settingsCheck.d.ts","sourceRoot":"","sources":["../../src/provision/settingsCheck.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EACV,kBAAkB,EAInB,MAAM,wCAAwC,CAAC;AAKhD,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,oBAAoB,CAAC;AAIrD;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AAEH,uGAAuG;AACvG,MAAM,WAAW,kBAAkB;IACjC,qFAAqF;IACrF,WAAW,EAAE,MAAM,CAAC;IACpB,oEAAoE;IACpE,OAAO,EAAE,MAAM,CAAC;IAChB,iEAAiE;IACjE,KAAK,CAAC,EAAE,UAAU,CAAC;CACpB;AA4LD,wGAAwG;AACxG,wBAAgB,aAAa,CAAC,MAAM,EAAE,kBAAkB,GAAG,kBAAkB,CAK5E"}
|
|
@@ -4,6 +4,7 @@ import { EMAIL_LINK_SIGNING_KEY } from "../crypto/signingKey.js";
|
|
|
4
4
|
import { emailHostEnv } from "../workflows/hostEnv.js";
|
|
5
5
|
import { suppressionDatabaseName } from "./provisionEmail.js";
|
|
6
6
|
import { hostEnvFindings } from "@pithy-sh/core/src/capability/settings";
|
|
7
|
+
import "@pithy-sh/core/src/naming/domains";
|
|
7
8
|
import { checkHostEnv } from "@pithy-sh/core/src/workflow/hostEnv";
|
|
8
9
|
//#region src/provision/settingsCheck.ts
|
|
9
10
|
/**
|
|
@@ -60,6 +61,21 @@ function localHostEnv(config) {
|
|
|
60
61
|
return hostEnvFindings(checkHostEnv(emailHostEnv, candidate), null);
|
|
61
62
|
}
|
|
62
63
|
/**
|
|
64
|
+
* Whether a URL points at this machine — {@link LOCAL_ORIGIN} and every spelling of it, port or none.
|
|
65
|
+
*
|
|
66
|
+
* Matched on the host rather than the whole origin because the derived value carries no port and a
|
|
67
|
+
* hand-written one usually does (`http://localhost:8787`), and the two are the same claim: a loopback
|
|
68
|
+
* address is not an origin anything is deployed on, so it can only ever be the local answer.
|
|
69
|
+
*/
|
|
70
|
+
function isLoopback(url) {
|
|
71
|
+
try {
|
|
72
|
+
const host = new URL(url).hostname.replace(/^\[|\]$/g, "");
|
|
73
|
+
return host === "localhost" || host === "127.0.0.1" || host === "::1";
|
|
74
|
+
} catch {
|
|
75
|
+
return false;
|
|
76
|
+
}
|
|
77
|
+
}
|
|
78
|
+
/**
|
|
63
79
|
* Whether the configured base URL is an origin this project actually answers on.
|
|
64
80
|
*
|
|
65
81
|
* `pithy email provision` stamps each host's `BASE_URL` from that environment's *resolved worker address*,
|
|
@@ -67,10 +83,29 @@ function localHostEnv(config) {
|
|
|
67
83
|
* against and what the repository states its intent with, and a value matching no declared origin is a
|
|
68
84
|
* link to a host nothing serves. Asked only when some environment declares one: a project before its first
|
|
69
85
|
* domain has nothing to compare against, and `Origins:` already reports that.
|
|
86
|
+
*
|
|
87
|
+
* **{@link LOCAL_ORIGIN} is passed over, and that is the whole of #510.** The recommended shape is
|
|
88
|
+
* `email({ baseUrl: PUBLIC_ORIGIN })` over `originFor(compositionEnvironment(), DOMAINS)`, and every
|
|
89
|
+
* caller of this loads the config **once, under `dev`** — an environment `domains` declares by design
|
|
90
|
+
* (`docs/NAMING.md`), so `resolveOrigin` correctly answers `http://localhost`. That value is then compared
|
|
91
|
+
* against staging's and prod's origins, matches neither, and the project is told to set `baseUrl` to one
|
|
92
|
+
* of them **by name**.
|
|
93
|
+
*
|
|
94
|
+
* Which is the mistake `docs/CLI.md` exists to prevent, offered to the projects that got it right: write
|
|
95
|
+
* one environment's origin into that key and a staging deploy mails real users links into production. A
|
|
96
|
+
* report that is easy to follow and wrong is worse than none, and this one named two specific origins.
|
|
97
|
+
*
|
|
98
|
+
* A hardcoded `http://localhost` is genuinely indistinguishable from a derived one here — same string,
|
|
99
|
+
* same key, and no environment in hand to tell them apart. So the question is left to where it can be
|
|
100
|
+
* answered: `resolveOrigin`'s own contract puts it on `pithy deploy --env <name>`, which refuses an
|
|
101
|
+
* environment whose origin its config does not declare (#253), and on `Origins:`, which reports the
|
|
102
|
+
* placeholder before a deploy is attempted. Two checks already own it; this one was the third and the
|
|
103
|
+
* only one without the environment it needed.
|
|
70
104
|
*/
|
|
71
105
|
function localBaseUrlOrigin(config, context) {
|
|
72
106
|
const declared = context.environments.map((environment) => environment.origin === null ? null : originOf(environment.origin)).filter((origin) => origin !== null);
|
|
73
107
|
const configured = originOf(config.baseUrl);
|
|
108
|
+
if (isLoopback(config.baseUrl)) return [];
|
|
74
109
|
if (declared.length === 0 || configured === null || declared.includes(configured)) return [];
|
|
75
110
|
return [{
|
|
76
111
|
setting: "BASE_URL",
|
|
@@ -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.1.
|
|
6
|
+
export declare const PACKAGE_VERSION = "0.1.7";
|
|
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.1.
|
|
7
|
+
const PACKAGE_VERSION = "0.1.7";
|
|
8
8
|
//#endregion
|
|
9
9
|
export { PACKAGE_NAME, PACKAGE_VERSION };
|
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"hostApp.d.ts","sourceRoot":"","sources":["../../src/workflows/hostApp.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,0CAA0C,CAAC;AAC7E,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,gCAAgC,CAAC;AAGjE,OAAO,EAAE,IAAI,EAAE,MAAM,MAAM,CAAC;AAI5B;;;;;;;;;;;;;;;;;;GAkBG;AAEH,2EAA2E;AAC3E,MAAM,WAAW,mBAAmB;IAClC;;;OAGG;IACH,GAAG,CAAC,EAAE,UAAU,CAAC;CAClB;AAED,mGAAmG;AACnG,wBAAgB,kBAAkB,CAAC,OAAO,GAAE,mBAAwB,GAAG,IAAI,CAAC,YAAY,CAAC,
|
|
1
|
+
{"version":3,"file":"hostApp.d.ts","sourceRoot":"","sources":["../../src/workflows/hostApp.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,0CAA0C,CAAC;AAC7E,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,gCAAgC,CAAC;AAGjE,OAAO,EAAE,IAAI,EAAE,MAAM,MAAM,CAAC;AAI5B;;;;;;;;;;;;;;;;;;GAkBG;AAEH,2EAA2E;AAC3E,MAAM,WAAW,mBAAmB;IAClC;;;OAGG;IACH,GAAG,CAAC,EAAE,UAAU,CAAC;CAClB;AAED,mGAAmG;AACnG,wBAAgB,kBAAkB,CAAC,OAAO,GAAE,mBAAwB,GAAG,IAAI,CAAC,YAAY,CAAC,CAaxF"}
|
|
@@ -2,14 +2,14 @@
|
|
|
2
2
|
// SPDX-License-Identifier: MIT
|
|
3
3
|
import { EMAIL_CAPABILITY } from "../provision/provisionEmail.js";
|
|
4
4
|
import { emailWorkflowRegistry } from "../provision/resolveEmailConfig.js";
|
|
5
|
-
import {
|
|
5
|
+
import { loggingErrorHandler } from "@pithy-sh/core/src/logger/errorHandler";
|
|
6
6
|
import { registerWorkflowDispatchRoute } from "@pithy-sh/core/src/workflow/dispatchRoute";
|
|
7
7
|
import { Hono } from "hono";
|
|
8
8
|
//#region src/workflows/hostApp.ts
|
|
9
9
|
/** Build the email host worker's app: the Pithy error handler, and the workflow dispatch route. */
|
|
10
10
|
function createEmailHostApp(options = {}) {
|
|
11
11
|
const app = new Hono();
|
|
12
|
-
app.onError(
|
|
12
|
+
app.onError(loggingErrorHandler);
|
|
13
13
|
registerWorkflowDispatchRoute(app, {
|
|
14
14
|
capability: EMAIL_CAPABILITY,
|
|
15
15
|
registry: emailWorkflowRegistry,
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@pithy-sh/email",
|
|
3
|
-
"version": "0.1.
|
|
3
|
+
"version": "0.1.7",
|
|
4
4
|
"license": "MIT",
|
|
5
5
|
"repository": {
|
|
6
6
|
"type": "git",
|
|
@@ -38,8 +38,8 @@
|
|
|
38
38
|
"dependencies": {
|
|
39
39
|
"@cloudflare/workers-types": "^5.20260729.1",
|
|
40
40
|
"@hono/zod-validator": "^0.9.0",
|
|
41
|
-
"@pithy-sh/core": "^0.
|
|
42
|
-
"@pithy-sh/secrets": "^0.1.
|
|
41
|
+
"@pithy-sh/core": "^0.3.0",
|
|
42
|
+
"@pithy-sh/secrets": "^0.1.6",
|
|
43
43
|
"handlebars": "^4.7.9",
|
|
44
44
|
"postal-mime": "^3.0.0"
|
|
45
45
|
},
|
package/pithy.manifest.json
CHANGED
|
@@ -3,7 +3,7 @@
|
|
|
3
3
|
"package": "@pithy-sh/email",
|
|
4
4
|
"requiredBindings": [
|
|
5
5
|
{ "type": "d1", "name": "DB" },
|
|
6
|
-
{ "type": "d1", "name": "EMAIL_SUPPRESSIONS" },
|
|
6
|
+
{ "type": "d1", "name": "EMAIL_SUPPRESSIONS", "scope": "global" },
|
|
7
7
|
{ "type": "workflow", "name": "EMAIL_SENDER", "job": "send", "className": "EmailSendWorkflow" }
|
|
8
8
|
],
|
|
9
9
|
"peerCapabilities": ["secrets"],
|
|
@@ -3,6 +3,7 @@
|
|
|
3
3
|
|
|
4
4
|
import type { DeclaredEnvironments } from "@pithy-sh/core/src/naming/environment";
|
|
5
5
|
import { GLOBAL_SCOPE } from "@pithy-sh/core/src/naming/environment";
|
|
6
|
+
import { bindingResourceName, type ProjectGlobalNaming } from "@pithy-sh/core/src/naming/provisionScope";
|
|
6
7
|
import { resourceName } from "@pithy-sh/core/src/naming/resource";
|
|
7
8
|
import { resourceNames } from "@pithy-sh/core/src/naming/resourceNames";
|
|
8
9
|
import { type ManagedEnvironment, managedEnvironments } from "@pithy-sh/secrets/src/scope";
|
|
@@ -33,6 +34,18 @@ import { type ManagedEnvironment, managedEnvironments } from "@pithy-sh/secrets/
|
|
|
33
34
|
/** The capability segment every email-owned name carries — the migration namespace and error domain too. */
|
|
34
35
|
export const EMAIL_CAPABILITY = "email";
|
|
35
36
|
|
|
37
|
+
/** The D1 binding the suppression database is bound to, in every Worker and every environment. */
|
|
38
|
+
export const EMAIL_SUPPRESSIONS_BINDING = "EMAIL_SUPPRESSIONS";
|
|
39
|
+
|
|
40
|
+
/**
|
|
41
|
+
* What `packages/email/pithy.manifest.json` declares about naming {@link EMAIL_SUPPRESSIONS_BINDING} —
|
|
42
|
+
* restated here because a bundled Worker package cannot read its own manifest, and **pinned to it by
|
|
43
|
+
* `cli/src/ci/bindingResourceNames.test.ts`**, which fails the moment the two answers differ.
|
|
44
|
+
*
|
|
45
|
+
* No `resource`: `email-suppressions` is the kebabbed binding, which is what the composer already uses.
|
|
46
|
+
*/
|
|
47
|
+
const EMAIL_SUPPRESSIONS_NAMING: ProjectGlobalNaming = { scope: GLOBAL_SCOPE };
|
|
48
|
+
|
|
36
49
|
/**
|
|
37
50
|
* The shared, durable suppression database — **one per project, shared across that project's
|
|
38
51
|
* environments**: `<project>-global-email-suppressions`.
|
|
@@ -51,9 +64,20 @@ export const EMAIL_CAPABILITY = "email";
|
|
|
51
64
|
*
|
|
52
65
|
* Composed through core's naming facade under the **`d1`** namespace, so the name is measured against
|
|
53
66
|
* a D1 database name's limit rather than the single 63 the generic composer defaults to.
|
|
67
|
+
*
|
|
68
|
+
* **Through {@link bindingResourceName}, the same expression `pithy add` and `pithy provision` compose
|
|
69
|
+
* with — because until #513 it was a *different* expression, and that was the defect.** This function
|
|
70
|
+
* said `<project>-global-email-suppressions` while the two writers said `<project>-<env>-email-
|
|
71
|
+
* suppressions`, so `pithy add email` wrote three per-environment databases into `wrangler.jsonc` and
|
|
72
|
+
* `pithy email provision` created the one this names. The app Worker and the email Worker then read
|
|
73
|
+
* different suppression lists, and an unsubscribe recorded on either was invisible to the other. One
|
|
74
|
+
* expression, driven by one declaration, is what makes that unexpressible rather than merely fixed.
|
|
75
|
+
*
|
|
76
|
+
* The output is byte-identical to what it always was: `kebab("EMAIL_SUPPRESSIONS")` is
|
|
77
|
+
* `email-suppressions`, and the composer's `global` branch is the facade call this used to make directly.
|
|
54
78
|
*/
|
|
55
79
|
export function suppressionDatabaseName(project: string): string {
|
|
56
|
-
return
|
|
80
|
+
return bindingResourceName(project, EMAIL_SUPPRESSIONS_BINDING, "d1", EMAIL_SUPPRESSIONS_NAMING);
|
|
57
81
|
}
|
|
58
82
|
|
|
59
83
|
/**
|
|
@@ -118,12 +142,17 @@ export interface EmailProvisionResult {
|
|
|
118
142
|
|
|
119
143
|
/**
|
|
120
144
|
* Provision the email infrastructure: create + migrate the shared suppression DB once, then deploy the
|
|
121
|
-
* email worker for every
|
|
145
|
+
* email worker for every environment given. The order matters — the suppression DB exists and is
|
|
122
146
|
* migrated before any worker that binds it is deployed. Idempotent end to end (each step is).
|
|
123
147
|
*
|
|
124
|
-
* `environments` is the
|
|
125
|
-
*
|
|
126
|
-
*
|
|
148
|
+
* `environments` is **what the caller determined it can act on**, which the CLI narrows from the project's
|
|
149
|
+
* declaration (#241) to the environments whose app database exists (pithy-sh/pithy#512). Nothing is
|
|
150
|
+
* skipped here and nothing decides here: an environment reaching this list is provisioned, and one that
|
|
151
|
+
* did not was already reported to the operator by name, with why and with the command that fixes it.
|
|
152
|
+
*
|
|
153
|
+
* The suppression database is created **whatever the list holds, including nothing**. It is one per
|
|
154
|
+
* project, shared across every environment, and making it wait for the last environment to be provisioned
|
|
155
|
+
* is exactly the ordering this change exists to undo.
|
|
127
156
|
*/
|
|
128
157
|
export async function provisionEmail(
|
|
129
158
|
provisioner: EmailProvisioner,
|
|
@@ -132,12 +161,16 @@ export async function provisionEmail(
|
|
|
132
161
|
await provisioner.preflight();
|
|
133
162
|
const { databaseId } = await provisioner.ensureSuppressionDatabase();
|
|
134
163
|
await provisioner.migrateSuppression(databaseId);
|
|
135
|
-
|
|
164
|
+
const deployed = managedEnvironments(environments);
|
|
165
|
+
for (const env of deployed) {
|
|
136
166
|
await provisioner.deployWorker(env, databaseId);
|
|
137
167
|
}
|
|
138
|
-
// One inbound routing rule per domain (production app worker), after the workers are up
|
|
139
|
-
|
|
140
|
-
|
|
168
|
+
// One inbound routing rule per domain (production app worker), after the workers are up — and only when
|
|
169
|
+
// at least one is. A rule created over an empty run starts delivering real bounce mail to a handler that
|
|
170
|
+
// was never deployed, which is the window this ordering exists to close.
|
|
171
|
+
const routing =
|
|
172
|
+
deployed.length > 0 ? await provisioner.ensureRoutingRule() : { created: false, skipped: true as const };
|
|
173
|
+
return { suppressionDatabaseId: databaseId, environments: deployed, routing };
|
|
141
174
|
}
|
|
142
175
|
|
|
143
176
|
/** The teardown seam — the inverse of {@link EmailProvisioner}. Every step idempotent (a missing resource is a no-op). */
|
|
@@ -9,6 +9,7 @@ import type {
|
|
|
9
9
|
SettingsFinding,
|
|
10
10
|
} from "@pithy-sh/core/src/capability/settings";
|
|
11
11
|
import { hostEnvFindings } from "@pithy-sh/core/src/capability/settings";
|
|
12
|
+
import { LOCAL_ORIGIN } from "@pithy-sh/core/src/naming/domains";
|
|
12
13
|
import { checkHostEnv } from "@pithy-sh/core/src/workflow/hostEnv";
|
|
13
14
|
import { EMAIL_LINK_SIGNING_KEY } from "../crypto/signingKey";
|
|
14
15
|
import type { EmailTheme } from "../templates/theme";
|
|
@@ -112,6 +113,22 @@ function localHostEnv(config: EmailSettingsInput): SettingsFinding[] {
|
|
|
112
113
|
return hostEnvFindings(checkHostEnv(emailHostEnv, candidate), null);
|
|
113
114
|
}
|
|
114
115
|
|
|
116
|
+
/**
|
|
117
|
+
* Whether a URL points at this machine — {@link LOCAL_ORIGIN} and every spelling of it, port or none.
|
|
118
|
+
*
|
|
119
|
+
* Matched on the host rather than the whole origin because the derived value carries no port and a
|
|
120
|
+
* hand-written one usually does (`http://localhost:8787`), and the two are the same claim: a loopback
|
|
121
|
+
* address is not an origin anything is deployed on, so it can only ever be the local answer.
|
|
122
|
+
*/
|
|
123
|
+
function isLoopback(url: string): boolean {
|
|
124
|
+
try {
|
|
125
|
+
const host = new URL(url).hostname.replace(/^\[|\]$/g, "");
|
|
126
|
+
return host === "localhost" || host === "127.0.0.1" || host === "::1";
|
|
127
|
+
} catch {
|
|
128
|
+
return false;
|
|
129
|
+
}
|
|
130
|
+
}
|
|
131
|
+
|
|
115
132
|
/**
|
|
116
133
|
* Whether the configured base URL is an origin this project actually answers on.
|
|
117
134
|
*
|
|
@@ -120,12 +137,31 @@ function localHostEnv(config: EmailSettingsInput): SettingsFinding[] {
|
|
|
120
137
|
* against and what the repository states its intent with, and a value matching no declared origin is a
|
|
121
138
|
* link to a host nothing serves. Asked only when some environment declares one: a project before its first
|
|
122
139
|
* domain has nothing to compare against, and `Origins:` already reports that.
|
|
140
|
+
*
|
|
141
|
+
* **{@link LOCAL_ORIGIN} is passed over, and that is the whole of #510.** The recommended shape is
|
|
142
|
+
* `email({ baseUrl: PUBLIC_ORIGIN })` over `originFor(compositionEnvironment(), DOMAINS)`, and every
|
|
143
|
+
* caller of this loads the config **once, under `dev`** — an environment `domains` declares by design
|
|
144
|
+
* (`docs/NAMING.md`), so `resolveOrigin` correctly answers `http://localhost`. That value is then compared
|
|
145
|
+
* against staging's and prod's origins, matches neither, and the project is told to set `baseUrl` to one
|
|
146
|
+
* of them **by name**.
|
|
147
|
+
*
|
|
148
|
+
* Which is the mistake `docs/CLI.md` exists to prevent, offered to the projects that got it right: write
|
|
149
|
+
* one environment's origin into that key and a staging deploy mails real users links into production. A
|
|
150
|
+
* report that is easy to follow and wrong is worse than none, and this one named two specific origins.
|
|
151
|
+
*
|
|
152
|
+
* A hardcoded `http://localhost` is genuinely indistinguishable from a derived one here — same string,
|
|
153
|
+
* same key, and no environment in hand to tell them apart. So the question is left to where it can be
|
|
154
|
+
* answered: `resolveOrigin`'s own contract puts it on `pithy deploy --env <name>`, which refuses an
|
|
155
|
+
* environment whose origin its config does not declare (#253), and on `Origins:`, which reports the
|
|
156
|
+
* placeholder before a deploy is attempted. Two checks already own it; this one was the third and the
|
|
157
|
+
* only one without the environment it needed.
|
|
123
158
|
*/
|
|
124
159
|
function localBaseUrlOrigin(config: EmailSettingsInput, context: SettingsCheckContext): SettingsFinding[] {
|
|
125
160
|
const declared = context.environments
|
|
126
161
|
.map((environment) => (environment.origin === null ? null : originOf(environment.origin)))
|
|
127
162
|
.filter((origin): origin is string => origin !== null);
|
|
128
163
|
const configured = originOf(config.baseUrl);
|
|
164
|
+
if (isLoopback(config.baseUrl)) return [];
|
|
129
165
|
if (declared.length === 0 || configured === null || declared.includes(configured)) return [];
|
|
130
166
|
return [
|
|
131
167
|
{
|
package/src/version.generated.ts
CHANGED
package/src/workflows/hostApp.ts
CHANGED
|
@@ -3,7 +3,7 @@
|
|
|
3
3
|
|
|
4
4
|
import type { PithyHonoEnv } from "@pithy-sh/core/src/capability/capability";
|
|
5
5
|
import type { AmbientEnv } from "@pithy-sh/core/src/env/ambient";
|
|
6
|
-
import {
|
|
6
|
+
import { loggingErrorHandler } from "@pithy-sh/core/src/logger/errorHandler";
|
|
7
7
|
import { registerWorkflowDispatchRoute } from "@pithy-sh/core/src/workflow/dispatchRoute";
|
|
8
8
|
import { Hono } from "hono";
|
|
9
9
|
import { EMAIL_CAPABILITY } from "../provision/provisionEmail";
|
|
@@ -43,8 +43,9 @@ export function createEmailHostApp(options: EmailHostAppOptions = {}): Hono<Pith
|
|
|
43
43
|
const app = new Hono<PithyHonoEnv>();
|
|
44
44
|
// The same handler every composed Pithy app mounts, so a refusal on this door renders as a
|
|
45
45
|
// `PithyError` on the wire rather than as a stack trace the loopback dispatcher would report as an
|
|
46
|
-
// unreadable body.
|
|
47
|
-
app.
|
|
46
|
+
// unreadable body — and lands in Workers Logs with its `action`, which the wire body strips. This
|
|
47
|
+
// app has no base middleware binding `c.var.log`, so the handler's own CF-native fallback writes it.
|
|
48
|
+
app.onError(loggingErrorHandler);
|
|
48
49
|
registerWorkflowDispatchRoute(app, {
|
|
49
50
|
capability: EMAIL_CAPABILITY,
|
|
50
51
|
registry: emailWorkflowRegistry,
|