The best way to control Claude Code, Codex and more from any computer or phone

main
ts 259 lines 9.72 KB
Raw
1 import * as entityresolution from "@distilled.cloud/aws/entityresolution";
2 import { Unowned } from "alchemy/AdoptPolicy";
3 import { deepEqual, isResolved } from "alchemy/Diff";
4 import { createPhysicalName } from "alchemy/PhysicalName";
5 import * as Provider from "alchemy/Provider";
6 import { Resource } from "alchemy/Resource";
7 import { createInternalTags, hasAlchemyTags } from "alchemy/Tags";
8 import * as Effect from "effect/Effect";
9 import * as Schedule from "effect/Schedule";
10 import * as Stream from "effect/Stream";
11 import type { Providers } from "../Providers.ts";
12 import { retryRolePropagation, syncEntityResolutionTags, toTagRecord } from "./internal.ts";
13
14 export interface IdNamespaceProps {
15 /**
16 * Name of the ID namespace. Must be unique per account/region and match
17 * `[a-zA-Z_0-9-]*`. If omitted, a unique name is generated from the app,
18 * stage, and logical ID. Changing the name replaces the ID namespace.
19 */
20 idNamespaceName?: string;
21 /**
22 * A description of the ID namespace.
23 */
24 description?: string;
25 /**
26 * The kind of data this namespace holds: `SOURCE` namespaces contain the
27 * records to be mapped, `TARGET` namespaces contain the dataset (and, for
28 * rule-based mapping, the matching rules) the sources are mapped onto.
29 * Changing the type replaces the ID namespace.
30 */
31 type: entityresolution.IdNamespaceType;
32 /**
33 * The input records of the namespace: each entry names a Glue table
34 * (`inputSourceARN`) and optionally the schema mapping (`schemaName`) that
35 * describes its columns.
36 */
37 inputSourceConfig?: entityresolution.IdNamespaceInputSource[];
38 /**
39 * How this namespace participates in ID mapping workflows: `RULE_BASED`
40 * with `ruleBasedProperties` (rules live on the `TARGET` namespace) or a
41 * `PROVIDER` service.
42 */
43 idMappingWorkflowProperties?: entityresolution.IdNamespaceIdMappingWorkflowProperties[];
44 /**
45 * The ARN of the IAM role Entity Resolution assumes to read the namespace's
46 * input Glue tables on your behalf. Required when `inputSourceConfig`
47 * references Glue tables.
48 */
49 roleArn?: string;
50 /**
51 * Tags to apply to the ID namespace. Merged with internal Alchemy tags.
52 */
53 tags?: Record<string, string>;
54 }
55
56 export interface IdNamespace extends Resource<
57 "AWS.EntityResolution.IdNamespace",
58 IdNamespaceProps,
59 {
60 /**
61 * The name of the ID namespace.
62 */
63 idNamespaceName: string;
64 /**
65 * The ARN of the ID namespace.
66 */
67 idNamespaceArn: string;
68 },
69 never,
70 Providers
71 > {}
72
73 /**
74 * An AWS Entity Resolution ID namespace — a wrapper around an input dataset
75 * used by ID mapping workflows. A `SOURCE` namespace holds the records to be
76 * translated; a `TARGET` namespace holds the dataset (and the rule-based
77 * matching configuration) they are mapped onto.
78 *
79 * ### Creating ID Namespaces
80 * **Example:** Source namespace over a Glue table
81 * ```typescript
82 * import * as AWS from "@alchemy.run/aws";
83 *
84 * const source = yield* AWS.EntityResolution.IdNamespace("Source", {
85 * type: "SOURCE",
86 * inputSourceConfig: [
87 * { inputSourceARN: table.tableArn, schemaName: schema.schemaName },
88 * ],
89 * idMappingWorkflowProperties: [{ idMappingType: "RULE_BASED" }],
90 * roleArn: role.roleArn,
91 * });
92 * ```
93 *
94 * **Example:** Target namespace with matching rules
95 * ```typescript
96 * const target = yield* AWS.EntityResolution.IdNamespace("Target", {
97 * type: "TARGET",
98 * inputSourceConfig: [
99 * { inputSourceARN: table.tableArn, schemaName: schema.schemaName },
100 * ],
101 * idMappingWorkflowProperties: [
102 * {
103 * idMappingType: "RULE_BASED",
104 * ruleBasedProperties: {
105 * rules: [{ ruleName: "ByEmail", matchingKeys: ["email"] }],
106 * ruleDefinitionTypes: ["TARGET"],
107 * attributeMatchingModel: "ONE_TO_ONE",
108 * recordMatchingModels: ["ONE_SOURCE_TO_ONE_TARGET"],
109 * },
110 * },
111 * ],
112 * roleArn: role.roleArn,
113 * });
114 * ```
115 *
116 * @resource
117 */
118 export const IdNamespace = Resource<IdNamespace>("AWS.EntityResolution.IdNamespace");
119
120 export const IdNamespaceProvider = () =>
121 Provider.effect(
122 IdNamespace,
123 Effect.gen(function* () {
124 const createName = Effect.fn(function* (
125 id: string,
126 props: { idNamespaceName?: string | undefined },
127 ) {
128 return props.idNamespaceName ?? (yield* createPhysicalName({ id, maxLength: 255 }));
129 });
130
131 /** Get an ID namespace by name; typed not-found → undefined. */
132 const getByName = Effect.fn(function* (idNamespaceName: string) {
133 return yield* entityresolution
134 .getIdNamespace({ idNamespaceName })
135 .pipe(Effect.catchTag("ResourceNotFoundException", () => Effect.undefined));
136 });
137
138 return {
139 stables: ["idNamespaceName", "idNamespaceArn"],
140
141 read: Effect.fn(function* ({ id, olds, output }) {
142 const name = output?.idNamespaceName ?? (yield* createName(id, olds ?? {}));
143 const namespace = yield* getByName(name);
144 if (namespace === undefined) return undefined;
145 const attrs = {
146 idNamespaceName: namespace.idNamespaceName,
147 idNamespaceArn: namespace.idNamespaceArn,
148 };
149 // getIdNamespace returns tags — use the observed tags for the
150 // ownership check.
151 const tags = toTagRecord(namespace.tags);
152 return (yield* hasAlchemyTags(id, tags)) ? attrs : Unowned(attrs);
153 }),
154
155 diff: Effect.fn(function* ({ id, news, olds }) {
156 if (!isResolved(news)) return undefined;
157 const oldName = yield* createName(id, olds);
158 const newName = yield* createName(id, news);
159 // The name is the identity, and `type` is create-only —
160 // updateIdNamespace does not accept it.
161 if (oldName !== newName || olds.type !== news.type) {
162 return { action: "replace" } as const;
163 }
164 }),
165
166 reconcile: Effect.fn(function* ({ id, news, output, session }) {
167 const name = output?.idNamespaceName ?? (yield* createName(id, news));
168 const internalTags = yield* createInternalTags(id);
169 const desiredTags = { ...news.tags, ...internalTags };
170
171 // 1. Observe — names are unique, so the name IS the identity.
172 let namespace = yield* getByName(name);
173
174 // 2. Ensure — create when missing. A freshly-created IAM role is
175 // transiently rejected while IAM propagates; tolerate the
176 // concurrent-create race, then re-observe.
177 if (namespace === undefined) {
178 yield* entityresolution
179 .createIdNamespace({
180 idNamespaceName: name,
181 description: news.description,
182 type: news.type,
183 inputSourceConfig: news.inputSourceConfig,
184 idMappingWorkflowProperties: news.idMappingWorkflowProperties,
185 roleArn: news.roleArn,
186 tags: desiredTags,
187 })
188 .pipe(
189 retryRolePropagation,
190 Effect.catchTag("ConflictException", () => Effect.void),
191 );
192 namespace = yield* entityresolution.getIdNamespace({
193 idNamespaceName: name,
194 });
195 }
196
197 // 3. Sync — everything except name/type updates in place via a
198 // full-PUT update. Only call the API on an actual delta between
199 // OBSERVED and desired configuration.
200 const desired = {
201 description: news.description ?? undefined,
202 inputSourceConfig: news.inputSourceConfig ?? undefined,
203 idMappingWorkflowProperties: news.idMappingWorkflowProperties ?? undefined,
204 roleArn: news.roleArn ?? undefined,
205 };
206 const observed = {
207 description: namespace.description ?? undefined,
208 inputSourceConfig: namespace.inputSourceConfig ?? undefined,
209 idMappingWorkflowProperties: namespace.idMappingWorkflowProperties ?? undefined,
210 roleArn: namespace.roleArn ?? undefined,
211 };
212 if (!deepEqual(observed, desired)) {
213 yield* entityresolution
214 .updateIdNamespace({
215 idNamespaceName: name,
216 description: news.description,
217 inputSourceConfig: news.inputSourceConfig,
218 idMappingWorkflowProperties: news.idMappingWorkflowProperties,
219 roleArn: news.roleArn,
220 })
221 .pipe(retryRolePropagation);
222 }
223
224 const idNamespaceArn = namespace.idNamespaceArn;
225
226 // 3b. Sync tags against OBSERVED cloud tags (adoption-safe).
227 yield* syncEntityResolutionTags(idNamespaceArn, desiredTags);
228
229 yield* session.note(idNamespaceArn);
230 return { idNamespaceName: name, idNamespaceArn };
231 }),
232
233 delete: Effect.fn(function* ({ output }) {
234 // deleteIdNamespace succeeds even when the namespace is already
235 // gone; it conflicts while an ID mapping workflow still references
236 // it (the engine deletes dependents first — retry the
237 // eventual-consistency window).
238 yield* entityresolution
239 .deleteIdNamespace({ idNamespaceName: output.idNamespaceName })
240 .pipe(
241 Effect.retry({
242 while: (e) => e._tag === "ConflictException",
243 schedule: Schedule.max([Schedule.fixed("2 seconds"), Schedule.recurs(10)]),
244 }),
245 );
246 }),
247
248 list: () =>
249 entityresolution.listIdNamespaces.items({}).pipe(
250 Stream.map((summary) => ({
251 idNamespaceName: summary.idNamespaceName,
252 idNamespaceArn: summary.idNamespaceArn,
253 })),
254 Stream.runCollect,
255 Effect.map((chunk) => Array.from(chunk)),
256 ),
257 };
258 }),
259 );