@geekmidas/cloud 10.0.0-alpha.140 → 10.0.0-alpha.142

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/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@geekmidas/cloud",
3
- "version": "10.0.0-alpha.140",
3
+ "version": "10.0.0-alpha.142",
4
4
  "type": "module",
5
5
  "files": [
6
6
  "dist",
@@ -41,8 +41,8 @@
41
41
  },
42
42
  "dependencies": {
43
43
  "lodash.snakecase": "~4.1.1",
44
- "@geekmidas/envkit": "10.0.0-alpha.140",
45
- "@geekmidas/manifest": "10.0.0-alpha.140"
44
+ "@geekmidas/envkit": "10.0.0-alpha.142",
45
+ "@geekmidas/manifest": "10.0.0-alpha.142"
46
46
  },
47
47
  "devDependencies": {
48
48
  "@types/lodash.get": "~4.4.9",
@@ -58,10 +58,10 @@
58
58
  "@pulumi/aws": ">=7.47.0",
59
59
  "@pulumi/random": ">=4.21.2",
60
60
  "@pulumi/pulumi": ">=3.263.0",
61
- "@geekmidas/manifest": "^10.0.0-alpha.140",
62
- "@geekmidas/storage": "^10.0.0-alpha.140",
63
- "@geekmidas/events": "^10.0.0-alpha.140",
64
- "@geekmidas/db": "^10.0.0-alpha.140"
61
+ "@geekmidas/manifest": "^10.0.0-alpha.142",
62
+ "@geekmidas/storage": "^10.0.0-alpha.142",
63
+ "@geekmidas/events": "^10.0.0-alpha.142",
64
+ "@geekmidas/db": "^10.0.0-alpha.142"
65
65
  },
66
66
  "peerDependenciesMeta": {
67
67
  "@geekmidas/manifest": {
@@ -0,0 +1,160 @@
1
+ import { resolveEnvKeys } from '@geekmidas/envkit/sst';
2
+ import * as snsUrl from '@geekmidas/events/sns/url';
3
+ import {
4
+ type ConstructManifest,
5
+ providedKeyFor,
6
+ provideKey,
7
+ } from '@geekmidas/manifest';
8
+ import { beforeEach, describe, expect, it } from 'vitest';
9
+ import { type Inbox, InboxNotProvisioned, InboxTopic } from '../aws/Inbox';
10
+ import { Topic } from '../aws/Topic';
11
+ import { fromManifest } from '../fromManifest';
12
+
13
+ /**
14
+ * An inbox on SST: what receives the mail is its provider's, made before SST
15
+ * runs — so SST creates no topic for it, subscribes the inbox's Lambda to the
16
+ * provider's topic, and links the inbox's values the deploy handed it.
17
+ */
18
+
19
+ const stack = {} as never;
20
+ const TOPIC_ARN =
21
+ 'arn:aws:sns:eu-west-1:123456789012:gkm-shop-production-requests';
22
+ const URL = 's3://AKIA:secret@shop-production-requests-mail?region=eu-west-1';
23
+
24
+ const external = (
25
+ globalThis as unknown as {
26
+ sst: {
27
+ aws: {
28
+ SnsTopic: {
29
+ external: {
30
+ name: string;
31
+ topicArn: unknown;
32
+ subscriber: { handler: string; link: unknown[] };
33
+ args: unknown;
34
+ }[];
35
+ };
36
+ };
37
+ };
38
+ }
39
+ ).sst.aws.SnsTopic.external;
40
+
41
+ function manifest(): ConstructManifest {
42
+ return {
43
+ Requests: {
44
+ kind: 'inbox',
45
+ id: 'Requests',
46
+ addresses: ['requests'],
47
+ subdomains: true,
48
+ topic: 'RequestsMail',
49
+ provides: ['REQUESTS_URL', 'REQUESTS_DOMAIN'],
50
+ },
51
+ RequestsMail: {
52
+ kind: 'topic',
53
+ id: 'RequestsMail',
54
+ events: ['email.received'],
55
+ provides: [
56
+ providedKeyFor('RequestsMail', 'topic', 'publisherConnectionString'),
57
+ ],
58
+ subscribers: [
59
+ {
60
+ id: 'OnRequest',
61
+ handler: '.gkm/aws-lambda/subscribers/onRequest.handler',
62
+ dependencies: [{ target: 'Requests', kind: 'inbox' }],
63
+ events: [],
64
+ },
65
+ ],
66
+ },
67
+ // A topic of the app's own, beside it: still SST's to create.
68
+ Users: {
69
+ kind: 'topic',
70
+ id: 'Users',
71
+ events: ['user.created'],
72
+ provides: [providedKeyFor('Users', 'topic', 'publisherConnectionString')],
73
+ subscribers: [],
74
+ },
75
+ } as unknown as ConstructManifest;
76
+ }
77
+
78
+ const env = {
79
+ REQUESTS_URL: URL,
80
+ REQUESTS_DOMAIN: 'shop.example',
81
+ [provideKey('RequestsMail', 'publisherConnectionString')]: snsUrl.build({
82
+ topicArn: TOPIC_ARN,
83
+ region: 'eu-west-1',
84
+ }),
85
+ };
86
+
87
+ beforeEach(() => {
88
+ external.length = 0;
89
+ });
90
+
91
+ describe('an inbox on SST', () => {
92
+ it('references the provider’s topic instead of creating one', () => {
93
+ const provisioned = fromManifest(stack, manifest(), {
94
+ Requests: { env },
95
+ } as never);
96
+
97
+ expect(provisioned.RequestsMail).toBeInstanceOf(InboxTopic);
98
+ expect((provisioned.RequestsMail as unknown as InboxTopic).arn).toBe(
99
+ TOPIC_ARN,
100
+ );
101
+ expect(provisioned.Users).toBeInstanceOf(Topic);
102
+ });
103
+
104
+ it('subscribes the inbox’s Lambda to that topic, unfiltered, linked to its inbox', () => {
105
+ const provisioned = fromManifest(stack, manifest(), {
106
+ Requests: { env },
107
+ } as never);
108
+
109
+ expect(external).toHaveLength(1);
110
+ const [subscription] = external;
111
+ expect(subscription).toMatchObject({
112
+ name: 'OnRequestSubscription',
113
+ topicArn: TOPIC_ARN,
114
+ subscriber: {
115
+ handler: '.gkm/aws-lambda/subscribers/onRequest.handler',
116
+ },
117
+ });
118
+ // No filter policy: SES's notification has no `type` to filter on.
119
+ expect(subscription!.args).toBeUndefined();
120
+ expect(subscription!.subscriber.link).toEqual([provisioned.Requests]);
121
+ });
122
+
123
+ it('hands the Lambda the inbox’s keys, with the deploy’s values', () => {
124
+ const provisioned = fromManifest(stack, manifest(), {
125
+ Requests: { env },
126
+ } as never);
127
+ const inbox = provisioned.Requests as unknown as Inbox;
128
+
129
+ expect(inbox.getSSTLink().properties).toEqual({
130
+ url: URL,
131
+ domain: 'shop.example',
132
+ });
133
+ expect(
134
+ resolveEnvKeys({ Requests: { type: inbox._type as string } }),
135
+ ).toEqual(['REQUESTS_URL', 'REQUESTS_DOMAIN']);
136
+ });
137
+
138
+ it('takes the values passed to it over the deploy’s', () => {
139
+ const provisioned = fromManifest(stack, manifest(), {
140
+ Requests: { env, domain: 'mail.shop.example' },
141
+ } as never);
142
+
143
+ expect((provisioned.Requests as unknown as Inbox).provides().domain).toBe(
144
+ 'mail.shop.example',
145
+ );
146
+ });
147
+
148
+ it('fails naming the key when the provider has not made it', () => {
149
+ const partial = { ...env, REQUESTS_URL: undefined };
150
+
151
+ expect(() =>
152
+ fromManifest(stack, manifest(), { Requests: { env: partial } } as never),
153
+ ).toThrow(InboxNotProvisioned);
154
+ try {
155
+ fromManifest(stack, manifest(), { Requests: { env: partial } } as never);
156
+ } catch (error) {
157
+ expect((error as InboxNotProvisioned).key).toBe('REQUESTS_URL');
158
+ }
159
+ });
160
+ });
@@ -0,0 +1,138 @@
1
+ // The codec alone — see the note in `Queue.ts`.
2
+ import * as snsUrl from '@geekmidas/events/sns/url';
3
+ import { provideKey } from '@geekmidas/manifest';
4
+ import { type GkmLinkable, ResourceType } from '../Linkable';
5
+ import { regionOfArn } from '../naming';
6
+ import type { StackType } from '../Stack';
7
+
8
+ /**
9
+ * `Inbox` — mail received, as SST links it. It provisions nothing.
10
+ *
11
+ * What receives the mail is the inbox's provider's, created by `gkm deploy`
12
+ * before SST runs, as it is on a compose stage: the SES receipt rule, the
13
+ * bucket the raw messages are stored in, the topic each is announced on, the
14
+ * domain's MX and DKIM records. The deploy hands SST what that made, read
15
+ * from the stage's secrets by the rule every target reads it by, as env:
16
+ *
17
+ * - `<ID>_URL` — where the raw messages are read, with the provider's key;
18
+ * - `<ID>_DOMAIN` — the stage's domain, which mail is addressed to;
19
+ * - `<TOPIC>_PUBLISHER_CONNECTION_STRING` — the topic, whose ARN its
20
+ * subscribers are subscribed to.
21
+ *
22
+ * Each can be passed instead (`fromManifest(…, { Requests: { url, domain,
23
+ * topic } })`), which is what a test does.
24
+ */
25
+ export class Inbox<
26
+ TStage extends string = string,
27
+ TDomain extends string = string,
28
+ > implements GkmLinkable
29
+ {
30
+ readonly _id: string;
31
+
32
+ /** The ARN of the topic the provider publishes each receipt on. */
33
+ readonly topicArn: string;
34
+
35
+ private readonly url: string;
36
+
37
+ private readonly domain: string;
38
+
39
+ get _type() {
40
+ return ResourceType.Inbox;
41
+ }
42
+
43
+ constructor(
44
+ _stack: StackType<TStage, TDomain>,
45
+ name: string,
46
+ props: InboxProps,
47
+ ) {
48
+ this._id = name;
49
+ const env = props.env ?? process.env;
50
+ const read = (given: string | undefined, key: string): string => {
51
+ const value = given ?? env[key];
52
+ if (!value) throw new InboxNotProvisioned(name, key);
53
+ return value;
54
+ };
55
+
56
+ this.url = read(props.url, provideKey(name, 'url'));
57
+ this.domain = read(props.domain, provideKey(name, 'domain'));
58
+ this.topicArn = snsUrl.parse(
59
+ read(props.topic, provideKey(props.topicId, 'publisherConnectionString')),
60
+ ).topicArn;
61
+ }
62
+
63
+ provides(): Record<string, $util.Input<string>> {
64
+ return { url: this.url, domain: this.domain };
65
+ }
66
+
67
+ getSSTLink() {
68
+ return { properties: { ...this.provides() } };
69
+ }
70
+ }
71
+
72
+ export interface InboxProps {
73
+ /** The id of the topic the inbox declared — the provider's, by name. */
74
+ topicId: string;
75
+ /** Where the raw messages are read. `<ID>_URL` from the deploy otherwise. */
76
+ url?: string;
77
+ /** The domain mail is addressed to. `<ID>_DOMAIN` from the deploy otherwise. */
78
+ domain?: string;
79
+ /** The topic's `sns://` string. `<TOPIC>_PUBLISHER_CONNECTION_STRING` otherwise. */
80
+ topic?: string;
81
+ /** Where the deploy's values are read; `process.env` by default. */
82
+ env?: Readonly<Record<string, string | undefined>>;
83
+ }
84
+
85
+ /**
86
+ * The topic an inbox declared, as its provider made it: referenced, never
87
+ * created, so SST cannot make a second topic SES never publishes to.
88
+ *
89
+ * Nothing depends on it — only SES publishes to it — so what it provides is
90
+ * there for the declaration's contract, not for any producer.
91
+ */
92
+ export class InboxTopic implements GkmLinkable {
93
+ readonly _id: string;
94
+
95
+ get _type() {
96
+ return ResourceType.SnsTopic;
97
+ }
98
+
99
+ constructor(
100
+ name: string,
101
+ private readonly inbox: Inbox,
102
+ ) {
103
+ this._id = name;
104
+ }
105
+
106
+ get arn(): string {
107
+ return this.inbox.topicArn;
108
+ }
109
+
110
+ provides(): Record<string, $util.Input<string>> {
111
+ return {
112
+ publisherConnectionString: snsUrl.build({
113
+ topicArn: this.arn,
114
+ region: regionOfArn(this.arn),
115
+ }),
116
+ };
117
+ }
118
+
119
+ getSSTLink() {
120
+ return { properties: { arn: this.arn, ...this.provides() } };
121
+ }
122
+ }
123
+
124
+ /** An inbox's value is neither passed nor in the deploy's env. */
125
+ export class InboxNotProvisioned extends Error {
126
+ constructor(
127
+ readonly id: string,
128
+ readonly key: string,
129
+ ) {
130
+ super(
131
+ `'${id}' receives mail, and ${key} is not set. Its provider makes it: ` +
132
+ `deploy with \`gkm deploy --target sst\`, which runs the stage's ` +
133
+ `inbox provider (deploy.inbox.<stage> = { provider: 'ses' }) and ` +
134
+ `hands SST what it made — or pass it to fromManifest.`,
135
+ );
136
+ this.name = 'InboxNotProvisioned';
137
+ }
138
+ }
@@ -56,6 +56,7 @@ import { Encryption, type EncryptionProps } from './aws/Encryption';
56
56
  import { ExternalApi, type ExternalApiProps } from './aws/ExternalApi';
57
57
  import { FileServer } from './aws/FileServer';
58
58
  import { Function } from './aws/Function';
59
+ import { Inbox, InboxTopic } from './aws/Inbox';
59
60
  import { ObjectStorage } from './aws/ObjectStorage';
60
61
  import { Queue } from './aws/Queue';
61
62
  import { RestApiSurface } from './aws/RestApiSurface';
@@ -214,6 +215,12 @@ const PROVISIONERS: Partial<Record<DeclarationKind, Provisioner>> = {
214
215
  // producer's and subscribers' business, and SNS has no per-event
215
216
  // configuration to map it onto.
216
217
  topic: (stack, d, props) => new Topic(stack, d.id, props),
218
+ // What receives the mail is its provider's, made before SST runs; the
219
+ // inbox is the values that made, linked. See `aws/Inbox`.
220
+ inbox: (stack, d, props) => {
221
+ if (d.kind !== 'inbox') throw new UnknownDeclarationKind(d.kind, []);
222
+ return new Inbox(stack, d.id, { ...props, topicId: d.topic });
223
+ },
217
224
 
218
225
  database: (stack, d, props, context) => {
219
226
  if (d.kind !== 'database') throw new UnknownDeclarationKind(d.kind, []);
@@ -1007,6 +1014,76 @@ export function subscribeConsumers(
1007
1014
  }
1008
1015
  }
1009
1016
 
1017
+ /** The topics inboxes declared: their provider's, never SST's to create. */
1018
+ export function inboxTopicIds(manifest: ConstructManifest): Set<string> {
1019
+ return new Set(
1020
+ Object.values(manifest).flatMap((declaration) =>
1021
+ declaration.kind === 'inbox' ? [declaration.topic] : [],
1022
+ ),
1023
+ );
1024
+ }
1025
+
1026
+ /**
1027
+ * Each inbox's topic, as the provider made it — the ARN the inbox read from
1028
+ * the deploy — under the topic's own id, so its declaration's contract is
1029
+ * checked like any other.
1030
+ */
1031
+ export function referenceInboxTopics(
1032
+ manifest: ConstructManifest,
1033
+ provisioned: ProvisionedManifest,
1034
+ ): void {
1035
+ for (const declaration of Object.values(manifest)) {
1036
+ if (declaration.kind !== 'inbox') continue;
1037
+ const inbox = provisioned[declaration.id];
1038
+ if (!(inbox instanceof Inbox)) continue;
1039
+
1040
+ const topic = new InboxTopic(declaration.topic, inbox);
1041
+ const topicDeclaration = manifest[declaration.topic];
1042
+ assertProvides(
1043
+ declaration.topic,
1044
+ topicDeclaration?.provides,
1045
+ Object.keys(topic.provides()).map((role) =>
1046
+ providedKeyFor(declaration.topic, 'topic', role),
1047
+ ),
1048
+ );
1049
+ provisioned[declaration.topic] = topic as unknown as Provisioned;
1050
+ }
1051
+ }
1052
+
1053
+ /**
1054
+ * Subscribe each inbox subscriber's Lambda to its inbox's topic — the
1055
+ * provider's, by ARN — linked to what it depends on, its inbox included.
1056
+ *
1057
+ * Unfiltered: SES publishes its receipt notification with no `type` attribute
1058
+ * to filter on, and every message on an inbox's topic is for its subscribers.
1059
+ * The subscriber's adaptor reads the notification as `email.received`.
1060
+ */
1061
+ export function subscribeInboxes(
1062
+ manifest: ConstructManifest,
1063
+ provisioned: ProvisionedManifest,
1064
+ ): void {
1065
+ for (const declaration of Object.values(manifest)) {
1066
+ if (declaration.kind !== 'inbox') continue;
1067
+ const inbox = provisioned[declaration.id];
1068
+ const topic = manifest[declaration.topic];
1069
+ if (!(inbox instanceof Inbox) || topic?.kind !== 'topic') continue;
1070
+
1071
+ for (const subscriber of topic.subscribers) {
1072
+ const { link } = resolveEdges(subscriber.dependencies, provisioned);
1073
+ const vpc = vpcFor(link);
1074
+ sst.aws.SnsTopic.subscribe(
1075
+ `${subscriber.id}Subscription`,
1076
+ inbox.topicArn,
1077
+ {
1078
+ handler: subscriber.handler,
1079
+ link,
1080
+ ...(vpc ? { vpc } : {}),
1081
+ },
1082
+ );
1083
+ }
1084
+ }
1085
+ }
1086
+
1010
1087
  /** The provisioner for a kind. Pure — the lookup is testable without Pulumi. */
1011
1088
  export function provisionerFor(kind: DeclarationKind): Provisioner {
1012
1089
  const provisioner = PROVISIONERS[kind];
@@ -1109,10 +1186,14 @@ export function fromManifest<
1109
1186
  : {}),
1110
1187
  };
1111
1188
 
1189
+ const inboxTopics = inboxTopicIds(manifest);
1190
+
1112
1191
  for (const id of [...rest, ...sites]) {
1113
1192
  const declaration = manifest[id];
1114
1193
  if (!declaration) continue;
1115
1194
  if (PROVISIONED_ELSEWHERE.has(declaration.kind)) continue;
1195
+ // Its provider made it: referenced once its inbox is, below.
1196
+ if (inboxTopics.has(id)) continue;
1116
1197
 
1117
1198
  const component = provisionerFor(declaration.kind)(
1118
1199
  stack,
@@ -1136,9 +1217,12 @@ export function fromManifest<
1136
1217
  provisioned[id] = component;
1137
1218
  }
1138
1219
 
1220
+ referenceInboxTopics(manifest, provisioned);
1221
+
1139
1222
  // The functions and crons, each queue's one consumer and each surface's
1140
1223
  // endpoints, once everything they link to exists.
1141
1224
  provisionCompute(stack, manifest, provisioned);
1225
+ subscribeInboxes(manifest, provisioned);
1142
1226
  provisionProcessors(stack, manifest, provisioned);
1143
1227
  subscribeConsumers(manifest, provisioned);
1144
1228
  mountRoutes(manifest, provisioned);
package/src/sst/index.ts CHANGED
@@ -37,6 +37,12 @@ export { Email, EmailNeedsUrl, type EmailProps } from './aws/Email';
37
37
  export { Encryption, type EncryptionProps } from './aws/Encryption';
38
38
  export { FileServer, type FileServerProps } from './aws/FileServer';
39
39
  export { Function, type FunctionProps } from './aws/Function';
40
+ export {
41
+ Inbox,
42
+ InboxNotProvisioned,
43
+ type InboxProps,
44
+ InboxTopic,
45
+ } from './aws/Inbox';
40
46
  export {
41
47
  ObjectStorage,
42
48
  type ObjectStorageProps,
@@ -22,6 +22,7 @@ import type { DatabaseProps } from './aws/Database';
22
22
  import type { EncryptionProps } from './aws/Encryption';
23
23
  import type { ExternalApiProps } from './aws/ExternalApi';
24
24
  import type { FileServerProps } from './aws/FileServer';
25
+ import type { InboxProps } from './aws/Inbox';
25
26
  import type { ObjectStorageProps } from './aws/ObjectStorage';
26
27
  import type { QueueProps } from './aws/Queue';
27
28
  import type { SecretProps } from './aws/Secret';
@@ -105,8 +106,11 @@ export type OverrideFor<D, B extends ManifestBackends = {}> = D extends {
105
106
  ? Partial<EncryptionProps>
106
107
  : K extends 'external-api'
107
108
  ? Omit<ExternalApiProps, 'url'>
108
- : // Derived databases, compute, mobile apps, OIDC.
109
- never
109
+ : K extends 'inbox'
110
+ ? // Its provider's values; the deploy's env otherwise.
111
+ Partial<Omit<InboxProps, 'topicId'>>
112
+ : // Derived databases, compute, mobile apps, OIDC.
113
+ never
110
114
  : never;
111
115
 
112
116
  /** Whether `{}` satisfies an override — whether the id can be left out. */