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

main
ts 299 lines 11.5 KB
Raw
1 import * as translate from "@distilled.cloud/aws/translate";
2 import { Unowned } from "alchemy/AdoptPolicy";
3 import { 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 Data from "effect/Data";
9 import * as Effect from "effect/Effect";
10 import * as Schedule from "effect/Schedule";
11 import * as Stream from "effect/Stream";
12 import type { Providers } from "../Providers.ts";
13 import { readTranslateTags, syncTranslateTags } from "./internal.ts";
14
15 /**
16 * The parallel data import failed server-side (`Status: FAILED`) — usually a
17 * malformed input file or an S3 URI the caller cannot read.
18 */
19 export class ParallelDataFailed extends Data.TaggedError("ParallelDataFailed")<{
20 readonly resourceName: string;
21 readonly message: string | undefined;
22 }> {}
23
24 /**
25 * The parallel data did not reach a terminal status within the bounded
26 * polling window.
27 */
28 export class ParallelDataNotConverged extends Data.TaggedError("ParallelDataNotConverged")<{
29 readonly resourceName: string;
30 readonly status: string | undefined;
31 }> {}
32
33 export interface ParallelDataProps {
34 /**
35 * Name of the parallel data — up to 256 characters of letters, digits, and
36 * hyphens (`^([A-Za-z0-9-]_?)+$`). If omitted, a unique name is generated
37 * from the app, stage, and logical ID. Changing the name replaces the
38 * parallel data.
39 */
40 parallelDataName?: string;
41 /**
42 * Description of the parallel data.
43 */
44 description?: string;
45 /**
46 * S3 URI of the parallel data input file (e.g.
47 * `s3://my-bucket/examples.csv`). The caller must be able to read the
48 * object. Updatable in place — a new import runs on change.
49 */
50 s3Uri: string;
51 /**
52 * Format of the input file: `TSV`, `CSV`, or `TMX`.
53 */
54 format?: "TSV" | "CSV" | "TMX";
55 /**
56 * Id of the customer-managed KMS key used to encrypt the parallel data.
57 * If omitted, Translate uses an AWS-owned key.
58 */
59 encryptionKeyId?: string;
60 /**
61 * User-defined tags for the parallel data.
62 */
63 tags?: Record<string, string>;
64 }
65
66 export interface ParallelData extends Resource<
67 "AWS.Translate.ParallelData",
68 ParallelDataProps,
69 {
70 /**
71 * Name of the parallel data — pass it as `ParallelDataNames` to
72 * `StartTextTranslationJob` for Active Custom Translation.
73 */
74 parallelDataName: string;
75 /**
76 * ARN of the parallel data, e.g.
77 * `arn:aws:translate:us-east-1:123456789012:parallel-data/style-examples`.
78 */
79 parallelDataArn: string;
80 /** Status of the parallel data (`ACTIVE` once import succeeds). */
81 status: string | undefined;
82 /** Source language code detected from the input file, e.g. `en`. */
83 sourceLanguageCode: string | undefined;
84 /** Target language codes detected from the input file. */
85 targetLanguageCodes: string[] | undefined;
86 /** Number of records imported. */
87 importedRecordCount: number | undefined;
88 /** Number of records that failed to import. */
89 failedRecordCount: number | undefined;
90 },
91 never,
92 Providers
93 > {}
94
95 /**
96 * Amazon Translate parallel data — segment-aligned translation examples
97 * imported from S3 that steer the style, tone, and word choice of batch
98 * translation jobs (Active Custom Translation). The import is asynchronous:
99 * the resource waits for the parallel data to become `ACTIVE`.
100 *
101 * ### Managing Parallel Data
102 * **Example:** Import parallel data from S3
103 * ```typescript
104 * const examples = yield* AWS.Translate.ParallelData("StyleExamples", {
105 * s3Uri: "s3://my-bucket/style-examples.csv",
106 * format: "CSV",
107 * });
108 * ```
109 *
110 * **Example:** Use parallel data in a batch translation job
111 * ```typescript
112 * const startJob = yield* AWS.Translate.StartTextTranslationJob(dataAccessRole);
113 * yield* startJob({
114 * InputDataConfig: { S3Uri: "s3://my-bucket/input/", ContentType: "text/plain" },
115 * OutputDataConfig: { S3Uri: "s3://my-bucket/output/" },
116 * SourceLanguageCode: "en",
117 * TargetLanguageCodes: ["es"],
118 * ParallelDataNames: [examples.parallelDataName],
119 * });
120 * ```
121 *
122 * @resource
123 */
124 export const ParallelData = Resource<ParallelData>("AWS.Translate.ParallelData");
125
126 const toAttributes = (props: translate.ParallelDataProperties) => ({
127 parallelDataName: props.Name!,
128 parallelDataArn: props.Arn!,
129 status: props.Status,
130 sourceLanguageCode: props.SourceLanguageCode,
131 targetLanguageCodes: props.TargetLanguageCodes ? [...props.TargetLanguageCodes] : undefined,
132 importedRecordCount: props.ImportedRecordCount,
133 failedRecordCount: props.FailedRecordCount,
134 });
135
136 export const ParallelDataProvider = () =>
137 Provider.effect(
138 ParallelData,
139 Effect.gen(function* () {
140 const createName = Effect.fn(function* (id: string, props: ParallelDataProps) {
141 return props.parallelDataName ?? (yield* createPhysicalName({ id, maxLength: 256 }));
142 });
143
144 const getOne = Effect.fn(function* (name: string) {
145 return yield* translate
146 .getParallelData({ Name: name })
147 .pipe(Effect.catchTag("ResourceNotFoundException", () => Effect.undefined));
148 });
149
150 // The import runs asynchronously (CREATING/UPDATING → ACTIVE|FAILED);
151 // poll bounded (~10 min ceiling — small files typically converge in a
152 // few minutes).
153 const waitForStable = Effect.fn(function* (name: string) {
154 const final = yield* getOne(name).pipe(
155 Effect.repeat({
156 schedule: Schedule.spaced("10 seconds"),
157 until: (r): boolean => {
158 const status = r?.ParallelDataProperties?.Status;
159 return r === undefined || status === "ACTIVE" || status === "FAILED";
160 },
161 times: 60,
162 }),
163 );
164 const props = final?.ParallelDataProperties;
165 if (props?.Status === "FAILED") {
166 return yield* new ParallelDataFailed({ resourceName: name, message: props.Message });
167 }
168 if (props?.Status !== "ACTIVE") {
169 return yield* new ParallelDataNotConverged({ resourceName: name, status: props?.Status });
170 }
171 return props;
172 });
173
174 return {
175 stables: ["parallelDataName", "parallelDataArn"],
176
177 diff: Effect.fn(function* ({ id, olds, news }) {
178 if (!isResolved(news)) return undefined;
179 if ((yield* createName(id, olds)) !== (yield* createName(id, news))) {
180 return { action: "replace" } as const;
181 }
182 }),
183
184 read: Effect.fn(function* ({ id, olds, output }) {
185 const name = output?.parallelDataName ?? (yield* createName(id, olds ?? { s3Uri: "" }));
186 const found = yield* getOne(name);
187 if (found?.ParallelDataProperties === undefined) return undefined;
188 const attrs = toAttributes(found.ParallelDataProperties);
189 const tags = yield* readTranslateTags(attrs.parallelDataArn);
190 return (yield* hasAlchemyTags(id, tags)) ? attrs : Unowned(attrs);
191 }),
192
193 reconcile: Effect.fn(function* ({ id, news, output, session }) {
194 const name = output?.parallelDataName ?? (yield* createName(id, news));
195 const internalTags = yield* createInternalTags(id);
196 const desiredTags = { ...internalTags, ...news.tags };
197
198 // Observe — cloud state is authoritative.
199 const observed = yield* getOne(name);
200 const observedProps = observed?.ParallelDataProperties;
201
202 if (observedProps === undefined) {
203 // Ensure — greenfield import. ConflictException is a race with a
204 // concurrent create of the same name; fall through to observe.
205 // The client token only needs to be unique per submission;
206 // idempotency across crashed runs comes from observing first.
207 const clientToken = yield* Effect.sync(() => crypto.randomUUID());
208 yield* translate
209 .createParallelData({
210 Name: name,
211 ClientToken: clientToken,
212 Description: news.description,
213 ParallelDataConfig: { S3Uri: news.s3Uri, Format: news.format },
214 EncryptionKey: news.encryptionKeyId
215 ? { Type: "KMS", Id: news.encryptionKeyId }
216 : undefined,
217 Tags: Object.entries(desiredTags).map(([Key, Value]) => ({
218 Key,
219 Value,
220 })),
221 })
222 .pipe(Effect.catchTag("ConflictException", () => Effect.void));
223 } else {
224 // Sync — diff the observed import config against the desired one
225 // and re-import only on drift.
226 const config = observedProps.ParallelDataConfig;
227 const drift =
228 config?.S3Uri !== news.s3Uri ||
229 (news.format !== undefined && config?.Format !== news.format) ||
230 (observedProps.Description ?? undefined) !== (news.description ?? undefined);
231 if (drift) {
232 // Computed outside the retry so replays of the same submission
233 // reuse one idempotency token.
234 const clientToken = yield* Effect.sync(() => crypto.randomUUID());
235 yield* translate
236 .updateParallelData({
237 Name: name,
238 ClientToken: clientToken,
239 Description: news.description,
240 ParallelDataConfig: {
241 S3Uri: news.s3Uri,
242 Format: news.format,
243 },
244 })
245 .pipe(
246 // A concurrent import may still be settling — retry bounded.
247 Effect.retry({
248 while: (e): boolean =>
249 e._tag === "ConcurrentModificationException" ||
250 e._tag === "ConflictException",
251 schedule: Schedule.spaced("10 seconds"),
252 times: 8,
253 }),
254 );
255 }
256 }
257
258 yield* session.note(name);
259 const props = yield* waitForStable(name);
260 yield* syncTranslateTags(props.Arn!, desiredTags);
261 return toAttributes(props);
262 }),
263
264 delete: Effect.fn(function* ({ output }) {
265 // Idempotent — the parallel data may already be gone. A delete
266 // during CREATING/UPDATING conflicts; retry bounded.
267 yield* translate.deleteParallelData({ Name: output.parallelDataName }).pipe(
268 Effect.retry({
269 while: (e): boolean => e._tag === "ConcurrentModificationException",
270 schedule: Schedule.spaced("10 seconds"),
271 times: 8,
272 }),
273 Effect.catchTag("ResourceNotFoundException", () => Effect.void),
274 );
275 // Deletion is asynchronous (DELETING) — wait until gone so a
276 // replacement can immediately reuse the name.
277 yield* translate.getParallelData({ Name: output.parallelDataName }).pipe(
278 Effect.catchTag("ResourceNotFoundException", () => Effect.undefined),
279 Effect.repeat({
280 schedule: Schedule.spaced("5 seconds"),
281 until: (r): boolean => r === undefined,
282 times: 36,
283 }),
284 );
285 }),
286
287 list: () =>
288 translate.listParallelData.pages({}).pipe(
289 Stream.runCollect,
290 Effect.map((chunk) =>
291 Array.from(chunk)
292 .flatMap((page) => page.ParallelDataPropertiesList ?? [])
293 .filter((props) => props.Name && props.Arn)
294 .map(toAttributes),
295 ),
296 ),
297 };
298 }),
299 );