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

main
ts 263 lines 10.1 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 IdMappingWorkflowProps {
15 /**
16 * Name of the ID mapping workflow. Must be unique per account/region and
17 * match `[a-zA-Z_0-9-]*`. If omitted, a unique name is generated from the
18 * app, stage, and logical ID. Changing the name replaces the workflow.
19 */
20 workflowName?: string;
21 /**
22 * A description of the workflow.
23 */
24 description?: string;
25 /**
26 * The input records to map: for rule-based mapping, entries reference ID
27 * namespace ARNs (`inputSourceARN`) with their role (`type: "SOURCE"` or
28 * `"TARGET"`); for provider-based mapping, entries may reference Glue
29 * tables with a `schemaName`.
30 */
31 inputSourceConfig: entityresolution.IdMappingWorkflowInputSource[];
32 /**
33 * Where mapped output records are written: an S3 path (`outputS3Path`) and
34 * an optional KMS key (`KMSArn`). Optional — rule-based workflows can also
35 * receive per-job output configuration on `StartIdMappingJob`.
36 */
37 outputSourceConfig?: entityresolution.IdMappingWorkflowOutputSource[];
38 /**
39 * How records are mapped: `RULE_BASED` with `ruleBasedProperties`
40 * (definition type, attribute/record matching models) or a `PROVIDER`
41 * service (e.g. LiveRamp).
42 */
43 idMappingTechniques: entityresolution.IdMappingTechniques;
44 /**
45 * Incremental-run configuration. Note the service currently rejects
46 * incremental processing for ID mapping workflows.
47 */
48 incrementalRunConfig?: entityresolution.IdMappingIncrementalRunConfig;
49 /**
50 * The ARN of the IAM role Entity Resolution assumes to read Glue-table
51 * input sources and write the S3 output on your behalf. Optional when all
52 * input sources are ID namespaces that carry their own roles.
53 */
54 roleArn?: string;
55 /**
56 * Tags to apply to the workflow. Merged with internal Alchemy tags.
57 */
58 tags?: Record<string, string>;
59 }
60
61 export interface IdMappingWorkflow extends Resource<
62 "AWS.EntityResolution.IdMappingWorkflow",
63 IdMappingWorkflowProps,
64 {
65 /**
66 * The name of the ID mapping workflow.
67 */
68 workflowName: string;
69 /**
70 * The ARN of the ID mapping workflow.
71 */
72 workflowArn: string;
73 },
74 never,
75 Providers
76 > {}
77
78 /**
79 * An AWS Entity Resolution ID mapping workflow — a data-processing job
80 * definition that translates record identifiers between a `SOURCE` and a
81 * `TARGET` ID namespace, using rule-based matching or a provider service.
82 *
83 * The workflow definition itself is cheap and instant; a mapping RUN
84 * (`StartIdMappingJob`) processes the full input and takes many minutes.
85 *
86 * ### Creating ID Mapping Workflows
87 * **Example:** Rule-based ID mapping between two namespaces
88 * ```typescript
89 * import * as AWS from "@alchemy.run/aws";
90 *
91 * const workflow = yield* AWS.EntityResolution.IdMappingWorkflow("Map", {
92 * inputSourceConfig: [
93 * { inputSourceARN: source.idNamespaceArn, type: "SOURCE" },
94 * { inputSourceARN: target.idNamespaceArn, type: "TARGET" },
95 * ],
96 * idMappingTechniques: {
97 * idMappingType: "RULE_BASED",
98 * ruleBasedProperties: {
99 * ruleDefinitionType: "TARGET",
100 * attributeMatchingModel: "ONE_TO_ONE",
101 * recordMatchingModel: "ONE_SOURCE_TO_ONE_TARGET",
102 * },
103 * },
104 * outputSourceConfig: [
105 * { outputS3Path: `s3://${bucket.bucketName}/idmapping/` },
106 * ],
107 * roleArn: role.roleArn,
108 * });
109 * ```
110 *
111 * @resource
112 */
113 export const IdMappingWorkflow = Resource<IdMappingWorkflow>(
114 "AWS.EntityResolution.IdMappingWorkflow",
115 );
116
117 export const IdMappingWorkflowProvider = () =>
118 Provider.effect(
119 IdMappingWorkflow,
120 Effect.gen(function* () {
121 const createName = Effect.fn(function* (
122 id: string,
123 props: { workflowName?: string | undefined },
124 ) {
125 return props.workflowName ?? (yield* createPhysicalName({ id, maxLength: 255 }));
126 });
127
128 /** Get an ID mapping workflow by name; typed not-found → undefined. */
129 const getByName = Effect.fn(function* (workflowName: string) {
130 return yield* entityresolution
131 .getIdMappingWorkflow({ workflowName })
132 .pipe(Effect.catchTag("ResourceNotFoundException", () => Effect.undefined));
133 });
134
135 return {
136 stables: ["workflowName", "workflowArn"],
137
138 read: Effect.fn(function* ({ id, olds, output }) {
139 const name = output?.workflowName ?? (yield* createName(id, olds ?? {}));
140 const workflow = yield* getByName(name);
141 if (workflow === undefined) return undefined;
142 const attrs = {
143 workflowName: workflow.workflowName,
144 workflowArn: workflow.workflowArn,
145 };
146 // getIdMappingWorkflow returns tags — use the observed tags for
147 // the ownership check.
148 const tags = toTagRecord(workflow.tags);
149 return (yield* hasAlchemyTags(id, tags)) ? attrs : Unowned(attrs);
150 }),
151
152 diff: Effect.fn(function* ({ id, news, olds }) {
153 if (!isResolved(news)) return undefined;
154 const oldName = yield* createName(id, olds);
155 const newName = yield* createName(id, news);
156 if (oldName !== newName) {
157 return { action: "replace" } as const;
158 }
159 }),
160
161 reconcile: Effect.fn(function* ({ id, news, output, session }) {
162 const name = output?.workflowName ?? (yield* createName(id, news));
163 const internalTags = yield* createInternalTags(id);
164 const desiredTags = { ...news.tags, ...internalTags };
165
166 // 1. Observe — names are unique, so the name IS the identity.
167 let workflow = yield* getByName(name);
168
169 // 2. Ensure — create when missing. A freshly-created IAM role is
170 // transiently rejected while IAM propagates; tolerate the
171 // concurrent-create race, then re-observe: the create response
172 // is a structural subset of the Get shape (it omits
173 // createdAt/updatedAt/tags).
174 if (workflow === undefined) {
175 yield* entityresolution
176 .createIdMappingWorkflow({
177 workflowName: name,
178 description: news.description,
179 inputSourceConfig: news.inputSourceConfig,
180 outputSourceConfig: news.outputSourceConfig,
181 idMappingTechniques: news.idMappingTechniques,
182 incrementalRunConfig: news.incrementalRunConfig,
183 roleArn: news.roleArn,
184 tags: desiredTags,
185 })
186 .pipe(
187 retryRolePropagation,
188 Effect.catchTag("ConflictException", () => Effect.void),
189 );
190 workflow = yield* entityresolution.getIdMappingWorkflow({
191 workflowName: name,
192 });
193 }
194
195 // 3. Sync — everything except the name updates in place via a
196 // full-PUT update. Only call the API on an actual delta between
197 // OBSERVED and desired configuration.
198 const desired = {
199 description: news.description ?? undefined,
200 inputSourceConfig: news.inputSourceConfig,
201 outputSourceConfig: news.outputSourceConfig ?? undefined,
202 idMappingTechniques: news.idMappingTechniques,
203 incrementalRunConfig: news.incrementalRunConfig ?? undefined,
204 roleArn: news.roleArn ?? undefined,
205 };
206 const observed = {
207 description: workflow.description ?? undefined,
208 inputSourceConfig: workflow.inputSourceConfig,
209 outputSourceConfig: workflow.outputSourceConfig ?? undefined,
210 idMappingTechniques: workflow.idMappingTechniques,
211 incrementalRunConfig: workflow.incrementalRunConfig ?? undefined,
212 roleArn: workflow.roleArn ?? undefined,
213 };
214 if (!deepEqual(observed, desired)) {
215 // The update response omits createdAt/updatedAt/tags; the ARN is
216 // stable, so keep the observed Get shape.
217 yield* entityresolution
218 .updateIdMappingWorkflow({
219 workflowName: name,
220 description: news.description,
221 inputSourceConfig: news.inputSourceConfig,
222 outputSourceConfig: news.outputSourceConfig,
223 idMappingTechniques: news.idMappingTechniques,
224 incrementalRunConfig: news.incrementalRunConfig,
225 roleArn: news.roleArn,
226 })
227 .pipe(retryRolePropagation);
228 }
229
230 const workflowArn = workflow.workflowArn;
231
232 // 3b. Sync tags against OBSERVED cloud tags (adoption-safe).
233 yield* syncEntityResolutionTags(workflowArn, desiredTags);
234
235 yield* session.note(workflowArn);
236 return { workflowName: name, workflowArn };
237 }),
238
239 delete: Effect.fn(function* ({ output }) {
240 // deleteIdMappingWorkflow succeeds even when the workflow is
241 // already gone; a running mapping job conflicts — retry briefly.
242 yield* entityresolution
243 .deleteIdMappingWorkflow({ workflowName: output.workflowName })
244 .pipe(
245 Effect.retry({
246 while: (e) => e._tag === "ConflictException",
247 schedule: Schedule.max([Schedule.fixed("2 seconds"), Schedule.recurs(10)]),
248 }),
249 );
250 }),
251
252 list: () =>
253 entityresolution.listIdMappingWorkflows.items({}).pipe(
254 Stream.map((summary) => ({
255 workflowName: summary.workflowName,
256 workflowArn: summary.workflowArn,
257 })),
258 Stream.runCollect,
259 Effect.map((chunk) => Array.from(chunk)),
260 ),
261 };
262 }),
263 );