@devries-cameron20 / t3code Mirror · read-only
Fork 0

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

Mirrored from https://github.com/Camo67/t3code.git

Synced Nov 21, 06:00 UTC

main
ts 311 lines 11.9 KB
Raw
1 import * as polly from "@distilled.cloud/aws/polly";
2 import { isResolved } from "alchemy/Diff";
3 import { createPhysicalName } from "alchemy/PhysicalName";
4 import * as Provider from "alchemy/Provider";
5 import { Resource } from "alchemy/Resource";
6 import * as Data from "effect/Data";
7 import * as Effect from "effect/Effect";
8 import * as Redacted from "effect/Redacted";
9 import * as Schedule from "effect/Schedule";
10 import { AWSEnvironment } from "../Environment.ts";
11 import type { Providers } from "../Providers.ts";
12
13 export class LexiconNotReady extends Data.TaggedError("LexiconNotReady")<{
14 readonly message: string;
15 readonly cause?: unknown;
16 }> {}
17
18 export interface LexiconProps {
19 /**
20 * Name of the lexicon — an alphanumeric string up to 20 characters
21 * (`[0-9A-Za-z]{1,20}`). If omitted, a unique name is generated. Changing
22 * this replaces the lexicon.
23 */
24 lexiconName?: string;
25 /**
26 * The lexicon content, a W3C Pronunciation Lexicon Specification (PLS)
27 * XML document. Updatable in place — `PutLexicon` is a true upsert.
28 */
29 content: string;
30 }
31
32 export interface Lexicon extends Resource<
33 "AWS.Polly.Lexicon",
34 LexiconProps,
35 {
36 /**
37 * Name of the lexicon (its identity within the region). Pass it as
38 * `LexiconNames` to `SynthesizeSpeech` / `StartSpeechSynthesisTask`.
39 */
40 lexiconName: string;
41 /**
42 * ARN of the lexicon, e.g. `arn:aws:polly:us-east-1:123456789012:lexicon/casing`.
43 */
44 lexiconArn: string;
45 /**
46 * Phonetic alphabet declared by the PLS document (`ipa` or `x-sampa`).
47 */
48 alphabet: string | undefined;
49 /**
50 * Language code declared by the PLS document, e.g. `en-US`.
51 */
52 languageCode: string | undefined;
53 /**
54 * Number of lexemes in the lexicon.
55 */
56 lexemesCount: number | undefined;
57 },
58 never,
59 Providers
60 > {}
61
62 /**
63 * An Amazon Polly pronunciation lexicon — a W3C PLS document stored in a
64 * region that customizes how `SynthesizeSpeech` pronounces specific words.
65 * Identity is the region-scoped `lexiconName`; the PLS `content` is
66 * updatable in place.
67 *
68 * ### Managing Lexicons
69 * **Example:** Store a pronunciation lexicon
70 * ```typescript
71 * const lexicon = yield* AWS.Polly.Lexicon("Acronyms", {
72 * lexiconName: "acronyms",
73 * content: `<?xml version="1.0" encoding="UTF-8"?>
74 * <lexicon version="1.0" xmlns="http://www.w3.org/2005/01/pronunciation-lexicon"
75 * alphabet="ipa" xml:lang="en-US">
76 * <lexeme><grapheme>W3C</grapheme><alias>World Wide Web Consortium</alias></lexeme>
77 * </lexicon>`,
78 * });
79 * ```
80 *
81 * **Example:** Synthesize speech with the lexicon applied
82 * ```typescript
83 * const synthesizeSpeech = yield* AWS.Polly.SynthesizeSpeech();
84 * const result = yield* synthesizeSpeech({
85 * OutputFormat: "mp3",
86 * VoiceId: "Joanna",
87 * Text: "The W3C maintains the PLS standard.",
88 * LexiconNames: [lexicon.lexiconName],
89 * });
90 * ```
91 *
92 * @resource
93 */
94 export const Lexicon = Resource<Lexicon>("AWS.Polly.Lexicon");
95
96 /**
97 * Unwrap the lexicon `Content` (distilled types it as a `SensitiveString`,
98 * which decodes to `Redacted`) to its plain PLS XML string.
99 */
100 const contentOf = (lexicon: polly.Lexicon | undefined): string | undefined => {
101 const content = lexicon?.Content;
102 return content === undefined
103 ? undefined
104 : Redacted.isRedacted(content)
105 ? Redacted.value(content)
106 : content;
107 };
108
109 const toAttributes = (
110 name: string,
111 arn: string,
112 attributes: polly.LexiconAttributes | undefined,
113 ) => ({
114 lexiconName: name,
115 lexiconArn: arn,
116 alphabet: attributes?.Alphabet,
117 languageCode: attributes?.LanguageCode,
118 lexemesCount: attributes?.LexemesCount,
119 });
120
121 export const LexiconProvider = () =>
122 Provider.effect(
123 Lexicon,
124 Effect.gen(function* () {
125 // Lexicon names must match [0-9A-Za-z]{1,20} — generate the engine
126 // name, drop every non-alphanumeric character, and keep the trailing
127 // 20 characters so the unique suffix survives truncation. The
128 // `typeof === "string"` guard (rather than truthiness) keeps this
129 // callable from `precreate`, whose props may still hold unresolved
130 // Output expressions.
131 const toName = (id: string, props: LexiconProps) =>
132 typeof props.lexiconName === "string"
133 ? Effect.succeed(props.lexiconName)
134 : createPhysicalName({ id, maxLength: 26, suffixLength: 10 }).pipe(
135 Effect.map((n) => n.replace(/[^0-9A-Za-z]/g, "").slice(-20)),
136 );
137
138 // Bounded retry for transient Polly control-plane failures. Under a
139 // full concurrent suite, GetLexicon/PutLexicon can answer with
140 // throttling or a transient 5xx; failing reconcile between PutLexicon
141 // and returning Attributes is exactly the window that orphans a
142 // lexicon, so ride these out instead of failing fast.
143 const retryTransient = <A, E extends { _tag: string }, R>(
144 effect: Effect.Effect<A, E, R>,
145 ): Effect.Effect<A, E, R> =>
146 Effect.retry(effect, {
147 while: (e) =>
148 e._tag === "ThrottlingException" ||
149 e._tag === "ServiceUnavailable" ||
150 e._tag === "ServiceFailureException",
151 schedule: Schedule.exponential("500 millis"),
152 times: 5,
153 });
154
155 const lexiconArn = (name: string) =>
156 Effect.gen(function* () {
157 const { accountId, region } = yield* AWSEnvironment.current;
158 return `arn:aws:polly:${region}:${accountId}:lexicon/${name}`;
159 });
160
161 const getOne = (name: string) =>
162 retryTransient(polly.getLexicon({ Name: name })).pipe(
163 Effect.catchTag("LexiconNotFoundException", () => Effect.undefined),
164 );
165
166 const waitForContent = (name: string, desired: string) =>
167 Effect.gen(function* () {
168 let found: polly.GetLexiconOutput | undefined;
169 let consecutiveMatches = 0;
170 for (let attempt = 0; attempt < 20; attempt++) {
171 found = yield* getOne(name);
172 if (contentOf(found?.Lexicon) === desired) {
173 // Polly can transiently return a response whose Lexicon payload
174 // is absent immediately after PutLexicon. Require two stable
175 // reads before exposing the updated resource to dependants.
176 consecutiveMatches++;
177 if (consecutiveMatches === 2) return found;
178 } else {
179 consecutiveMatches = 0;
180 }
181 yield* Effect.sleep("500 millis");
182 }
183 return yield* new LexiconNotReady({
184 message: `Polly lexicon '${name}' did not converge to the desired content`,
185 });
186 });
187
188 const waitUntilGone = (name: string) =>
189 Effect.gen(function* () {
190 let consecutiveMisses = 0;
191 for (let attempt = 0; attempt < 20; attempt++) {
192 const found = yield* getOne(name);
193 if (found === undefined) {
194 consecutiveMisses++;
195 if (consecutiveMisses === 2) return;
196 } else {
197 consecutiveMisses = 0;
198 }
199 yield* Effect.sleep("500 millis");
200 }
201 return yield* new LexiconNotReady({
202 message: `Polly lexicon '${name}' is still observable after deletion`,
203 });
204 });
205
206 return {
207 stables: ["lexiconName", "lexiconArn"],
208 diff: Effect.fn(function* ({ id, olds, news }) {
209 if (!isResolved(news)) return;
210 if ((yield* toName(id, olds ?? { content: "" })) !== (yield* toName(id, news))) {
211 return { action: "replace" } as const;
212 }
213 }),
214 read: Effect.fn(function* ({ id, olds, output }) {
215 const name = output?.lexiconName ?? (yield* toName(id, olds ?? { content: "" }));
216 const found = yield* getOne(name);
217 if (!found) return undefined;
218 return toAttributes(
219 name,
220 found.LexiconAttributes?.LexiconArn ?? (yield* lexiconArn(name)),
221 found.LexiconAttributes,
222 );
223 }),
224 list: () =>
225 Effect.gen(function* () {
226 const attrs: {
227 lexiconName: string;
228 lexiconArn: string;
229 alphabet: string | undefined;
230 languageCode: string | undefined;
231 lexemesCount: number | undefined;
232 }[] = [];
233 let nextToken: string | undefined;
234 // ListLexicons is not modeled as paginated by distilled; walk
235 // NextToken manually with a hard page bound.
236 for (let page = 0; page < 25; page++) {
237 const res = yield* polly.listLexicons({
238 NextToken: nextToken,
239 });
240 for (const lexicon of res.Lexicons ?? []) {
241 if (lexicon.Name) {
242 attrs.push(
243 toAttributes(
244 lexicon.Name,
245 lexicon.Attributes?.LexiconArn ?? (yield* lexiconArn(lexicon.Name)),
246 lexicon.Attributes,
247 ),
248 );
249 }
250 }
251 nextToken = res.NextToken;
252 if (!nextToken) break;
253 }
254 return attrs;
255 }),
256 // Persist the lexicon's deterministic identity BEFORE reconcile runs.
257 // The engine commits precreate's Attributes to state ahead of any
258 // API call, so if reconcile fails (or is interrupted) after
259 // PutLexicon succeeded, destroy still has `output.lexiconName` and
260 // deletes the lexicon instead of orphaning it — the engine skips
261 // provider.delete entirely for rows whose attr was never persisted.
262 // No API call is made here; delete tolerates the not-yet-created case.
263 precreate: Effect.fn(function* ({ id, news }) {
264 const name = yield* toName(id, news);
265 return toAttributes(name, yield* lexiconArn(name), undefined);
266 }),
267 reconcile: Effect.fn(function* ({ id, news, output, session }) {
268 // Prefer the resolved user-supplied name; fall back to the cached
269 // output identity (which for a fresh create is the precreate stub),
270 // then to the generated name.
271 const name =
272 typeof news.lexiconName === "string"
273 ? news.lexiconName
274 : (output?.lexiconName ?? (yield* toName(id, news)));
275
276 // Observe — cloud state is authoritative.
277 const observed = yield* getOne(name);
278
279 // Ensure + sync in one step: PutLexicon is a true upsert, so a
280 // single call converges both the missing and the content-drift
281 // cases. Skip the API entirely when the observed content matches.
282 if (contentOf(observed?.Lexicon) !== news.content) {
283 yield* retryTransient(polly.putLexicon({ Name: name, Content: news.content }));
284 }
285
286 yield* session.note(name);
287 // PutLexicon can return before GetLexicon exposes the new document.
288 // Wait briefly for the exact desired content so callers never observe
289 // stale state immediately after a successful deploy.
290 const final = yield* waitForContent(name, news.content);
291 return toAttributes(
292 name,
293 final?.LexiconAttributes?.LexiconArn ?? (yield* lexiconArn(name)),
294 final?.LexiconAttributes,
295 );
296 }),
297 delete: Effect.fn(function* ({ output }) {
298 // Idempotent — the lexicon may already be gone (including the case
299 // where only the precreate stub was persisted and PutLexicon never
300 // ran).
301 yield* retryTransient(polly.deleteLexicon({ Name: output.lexiconName })).pipe(
302 Effect.catchTag("LexiconNotFoundException", () => Effect.void),
303 );
304 // DeleteLexicon may return before the control plane consistently
305 // reports absence. Confirm deletion so nuke cannot leave a lexicon
306 // behind and lose the only state that identifies it.
307 yield* waitUntilGone(output.lexiconName);
308 }),
309 };
310 }),
311 );