@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 478 lines 16.4 KB
Raw
1 import * as kendra from "@distilled.cloud/aws/kendra";
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, diffTags, hasAlchemyTags, type Tags } 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 EffectStream from "effect/Stream";
12 import { AWSEnvironment } from "../Environment.ts";
13 import type { Providers } from "../Providers.ts";
14
15 export class KendraSearchIndexInvalidProps extends Data.TaggedError(
16 "KendraSearchIndexInvalidProps",
17 )<{
18 readonly message: string;
19 readonly cause?: unknown;
20 }> {}
21
22 export class KendraSearchIndexUnexpectedResponse extends Data.TaggedError(
23 "KendraSearchIndexUnexpectedResponse",
24 )<{
25 readonly message: string;
26 readonly cause?: unknown;
27 }> {}
28
29 export type IndexStatus = kendra.IndexStatus;
30 export type IndexEdition = kendra.IndexEdition;
31
32 /**
33 * Server-side encryption settings for a Kendra index.
34 */
35 export interface IndexServerSideEncryption {
36 /**
37 * The identifier of the customer-managed KMS key. Kendra does not support
38 * asymmetric keys.
39 */
40 kmsKeyId?: string;
41 }
42
43 /**
44 * Provisioned capacity for an `ENTERPRISE_EDITION` index.
45 */
46 export interface IndexCapacityUnits {
47 /**
48 * Extra storage capacity units. Each unit adds 30 GB / 500k documents.
49 */
50 storageCapacityUnits: number;
51 /**
52 * Extra query capacity units. Each unit adds 0.1 queries/sec.
53 */
54 queryCapacityUnits: number;
55 }
56
57 export interface IndexProps {
58 /**
59 * Name of the index.
60 * @default ${app}-${stage}-${id}
61 */
62 name?: string;
63 /**
64 * The Kendra edition to provision.
65 *
66 * `GEN_AI_ENTERPRISE_EDITION` is the recommended edition for new
67 * deployments. Changing the edition replaces the index.
68 * @default "DEVELOPER_EDITION"
69 */
70 edition?: IndexEdition;
71 /**
72 * ARN of the IAM role that grants Kendra permission to write CloudWatch
73 * log and metric data.
74 */
75 roleArn: string;
76 /**
77 * A description of the index.
78 */
79 description?: string;
80 /**
81 * Encryption-at-rest configuration. Changing it replaces the index.
82 */
83 serverSideEncryption?: IndexServerSideEncryption;
84 /**
85 * How to filter query results on user context (`ATTRIBUTE_FILTER` or
86 * `USER_TOKEN`).
87 */
88 userContextPolicy?: kendra.UserContextPolicy;
89 /**
90 * JWT / JSON token configurations used to authorize queries.
91 */
92 userTokenConfigurations?: kendra.UserTokenConfiguration[];
93 /**
94 * Fetch user-group information from IAM Identity Center.
95 */
96 userGroupResolutionConfiguration?: kendra.UserGroupResolutionConfiguration;
97 /**
98 * Extra provisioned storage and query capacity (only meaningful for
99 * `ENTERPRISE_EDITION` indexes).
100 */
101 capacityUnits?: IndexCapacityUnits;
102 /**
103 * Tags to associate with the index.
104 */
105 tags?: Record<string, string>;
106 }
107
108 export interface Index extends Resource<
109 "AWS.Kendra.Index",
110 IndexProps,
111 {
112 /**
113 * Service-assigned unique identifier of the index.
114 */
115 id: string;
116 /**
117 * ARN of the index.
118 */
119 arn: string;
120 /**
121 * The index's name.
122 */
123 name: string;
124 /**
125 * The provisioned edition.
126 */
127 edition: IndexEdition | undefined;
128 /**
129 * Current lifecycle status of the index.
130 */
131 status: IndexStatus | undefined;
132 /**
133 * ARN of the IAM role used for CloudWatch logs/metrics.
134 */
135 roleArn: string;
136 /**
137 * Current tags reported for the index.
138 */
139 tags: Record<string, string>;
140 },
141 never,
142 Providers
143 > {}
144
145 /**
146 * An Amazon Kendra index — a machine-learning powered enterprise search
147 * index that data sources (S3, SharePoint, databases, ...) sync documents
148 * into and that applications query with natural language.
149 *
150 * :::caution
151 * Provisioning an index takes ~20–30 minutes and bills hourly from the
152 * moment the index becomes `ACTIVE` (including the Developer edition's
153 * free-tier-exhausted rate). Destroy indexes promptly.
154 * :::
155 * ### Creating Indexes
156 * **Example:** Developer-Edition Index
157 * ```typescript
158 * import * as AWS from "@alchemy.run/aws";
159 *
160 * const role = yield* AWS.IAM.Role("KendraRole", {
161 * assumeRolePolicy: {
162 * Version: "2012-10-17",
163 * Statement: [{
164 * Effect: "Allow",
165 * Principal: { Service: "kendra.amazonaws.com" },
166 * Action: "sts:AssumeRole",
167 * }],
168 * },
169 * policies: [{
170 * policyName: "logs",
171 * policyDocument: {
172 * Version: "2012-10-17",
173 * Statement: [{
174 * Effect: "Allow",
175 * Action: ["logs:*", "cloudwatch:PutMetricData"],
176 * Resource: "*",
177 * }],
178 * },
179 * }],
180 * });
181 *
182 * const index = yield* AWS.Kendra.Index("Search", {
183 * edition: "DEVELOPER_EDITION",
184 * roleArn: role.roleArn,
185 * });
186 * ```
187 *
188 * @resource
189 */
190 export const Index = Resource<Index>("AWS.Kendra.Index");
191
192 const createIndexName = (id: string, props: { name?: string | undefined }) =>
193 props.name ? Effect.succeed(props.name) : createPhysicalName({ id, maxLength: 100 });
194
195 const fetchTags = Effect.fn(function* (arn: string) {
196 const response = yield* kendra
197 .listTagsForResource({ ResourceARN: arn })
198 .pipe(
199 Effect.catchTag(
200 ["ResourceNotFoundException", "ResourceUnavailableException"],
201 () => Effect.undefined,
202 ),
203 );
204 return Object.fromEntries((response?.Tags ?? []).map((tag) => [tag.Key, tag.Value]));
205 });
206
207 interface IndexState {
208 attrs: Index["Attributes"];
209 described: kendra.DescribeIndexResponse;
210 }
211
212 const readIndexById = Effect.fn(function* (id: string, arnOf: (indexId: string) => string) {
213 const described = yield* kendra
214 .describeIndex({ Id: id })
215 .pipe(Effect.catchTag("ResourceNotFoundException", () => Effect.undefined));
216 if (!described || described.Status === "DELETING") return undefined;
217 const arn = arnOf(described.Id ?? id);
218 const state: IndexState = {
219 described,
220 attrs: {
221 id: described.Id ?? id,
222 arn,
223 name: described.Name ?? "",
224 edition: described.Edition,
225 status: described.Status,
226 roleArn: described.RoleArn ?? "",
227 tags: yield* fetchTags(arn),
228 },
229 };
230 return state;
231 });
232
233 const findIndexByName = Effect.fn(function* (name: string, arnOf: (indexId: string) => string) {
234 const summaries = yield* kendra.listIndices.pages({}).pipe(
235 EffectStream.runCollect,
236 Effect.map((chunk) =>
237 Array.from(chunk).flatMap((page) => page.IndexConfigurationSummaryItems ?? []),
238 ),
239 );
240 const match = summaries.find((summary) => summary.Name === name && summary.Status !== "DELETING");
241 if (!match?.Id) return undefined;
242 return yield* readIndexById(match.Id, arnOf);
243 });
244
245 /**
246 * An index still transitioning toward the awaited status — retried by
247 * {@link waitForIndexStatus}'s bounded schedule.
248 */
249 class IndexNotReady extends Data.TaggedError("IndexNotReady")<{
250 readonly id: string;
251 readonly status: string | undefined;
252 }> {}
253
254 /**
255 * An index whose asynchronous provisioning converged to the terminal
256 * `FAILED` status.
257 */
258 export class IndexProvisioningFailed extends Data.TaggedError("IndexProvisioningFailed")<{
259 readonly id: string;
260 readonly message: string | undefined;
261 }> {}
262
263 // Explicitly-typed retry wrapper — an inline `Effect.retry` in provider
264 // lifecycle code leaks `Retry.Return`'s conditional type into declaration
265 // emit and widens the provider layer to `unknown` for every consumer of
266 // `AWS.providers()`.
267 const retryWhileNotReady = <A, E extends { readonly _tag: string }, R>(
268 self: Effect.Effect<A, E, R>,
269 ): Effect.Effect<A, E, R> =>
270 Effect.retry(self, {
271 while: (e) => e._tag === "IndexNotReady",
272 // Index provisioning is slow (~20–30 min); poll every 20s up to ~40 min.
273 schedule: Schedule.max([Schedule.spaced("20 seconds"), Schedule.recurs(120)]),
274 });
275
276 // CreateIndex validates the IAM role up front; a freshly-created role may
277 // not have propagated yet and surfaces as ValidationException. Bounded retry
278 // through the propagation window (~60s). Explicitly typed for the same
279 // declaration-emit reason as retryWhileNotReady.
280 const retryThroughIamPropagation = <A, E extends { readonly _tag: string }, R>(
281 self: Effect.Effect<A, E, R>,
282 ): Effect.Effect<A, E, R> =>
283 Effect.retry(self, {
284 while: (e) => e._tag === "ValidationException",
285 schedule: Schedule.max([Schedule.spaced("5 seconds"), Schedule.recurs(12)]),
286 });
287
288 const waitForIndexStatus = (id: string, target: "ACTIVE" | "DELETED") =>
289 retryWhileNotReady(
290 Effect.gen(function* () {
291 const described = yield* kendra
292 .describeIndex({ Id: id })
293 .pipe(Effect.catchTag("ResourceNotFoundException", () => Effect.undefined));
294 if (target === "DELETED") {
295 if (described === undefined) return;
296 return yield* new IndexNotReady({ id, status: described.Status });
297 }
298 if (described?.Status === "ACTIVE") return;
299 if (described?.Status === "FAILED") {
300 return yield* new IndexProvisioningFailed({ id, message: described.ErrorMessage });
301 }
302 return yield* new IndexNotReady({ id, status: described?.Status });
303 }),
304 );
305
306 const currentArnOf = Effect.gen(function* () {
307 const { accountId, region } = yield* AWSEnvironment.current;
308 return (indexId: string) => `arn:aws:kendra:${region}:${accountId}:index/${indexId}`;
309 });
310
311 export const IndexProvider = () =>
312 Provider.effect(
313 Index,
314 Effect.gen(function* () {
315 return {
316 stables: ["id", "arn"],
317 list: () =>
318 Effect.gen(function* () {
319 const arnOf = yield* currentArnOf;
320 const summaries = yield* kendra.listIndices.pages({}).pipe(
321 EffectStream.runCollect,
322 Effect.map((chunk) =>
323 Array.from(chunk).flatMap((page) => page.IndexConfigurationSummaryItems ?? []),
324 ),
325 );
326 const hydrated = yield* Effect.forEach(
327 summaries.flatMap((s) => (s.Id ? [s.Id] : [])),
328 (indexId) => readIndexById(indexId, arnOf),
329 { concurrency: 5 },
330 );
331 return hydrated.flatMap((state) => (state === undefined ? [] : [state.attrs]));
332 }),
333 read: Effect.fn(function* ({ id, olds, output }) {
334 const arnOf = yield* currentArnOf;
335 const state = output?.id
336 ? yield* readIndexById(output.id, arnOf)
337 : yield* findIndexByName(yield* createIndexName(id, olds ?? {}), arnOf);
338 if (!state) return undefined;
339 return (yield* hasAlchemyTags(id, state.attrs.tags as Tags))
340 ? state.attrs
341 : Unowned(state.attrs);
342 }),
343 diff: Effect.fn(function* ({ news, olds }) {
344 if (!isResolved(news)) return;
345 if (olds === undefined) return;
346 // Edition and encryption-at-rest are fixed at creation.
347 if (
348 (olds.edition ?? "DEVELOPER_EDITION") !== (news.edition ?? "DEVELOPER_EDITION") ||
349 olds.serverSideEncryption?.kmsKeyId !== news.serverSideEncryption?.kmsKeyId
350 ) {
351 return { action: "replace" } as const;
352 }
353 }),
354 reconcile: Effect.fn(function* ({ id, news, output, session }) {
355 if (!news) {
356 return yield* new KendraSearchIndexInvalidProps({
357 message: "Kendra Index requires props",
358 });
359 }
360 const arnOf = yield* currentArnOf;
361 const name = yield* createIndexName(id, news);
362 const internalTags = yield* createInternalTags(id);
363 const desiredTags = { ...internalTags, ...news.tags };
364
365 // Observe — prefer the cached id; fall back to a name lookup so a
366 // create whose state failed to persist is adopted, not duplicated.
367 let state = output?.id
368 ? yield* readIndexById(output.id, arnOf)
369 : yield* findIndexByName(name, arnOf);
370
371 // Ensure — create if missing, then wait for ACTIVE.
372 if (state === undefined) {
373 const created = yield* retryThroughIamPropagation(
374 kendra.createIndex({
375 Name: name,
376 Edition: news.edition ?? "DEVELOPER_EDITION",
377 RoleArn: news.roleArn,
378 Description: news.description,
379 ServerSideEncryptionConfiguration: news.serverSideEncryption
380 ? { KmsKeyId: news.serverSideEncryption.kmsKeyId }
381 : undefined,
382 UserContextPolicy: news.userContextPolicy,
383 UserTokenConfigurations: news.userTokenConfigurations,
384 UserGroupResolutionConfiguration: news.userGroupResolutionConfiguration,
385 Tags: Object.entries(desiredTags).map(([Key, Value]) => ({
386 Key,
387 Value,
388 })),
389 }),
390 );
391 if (!created.Id) {
392 return yield* new KendraSearchIndexUnexpectedResponse({
393 message: `CreateIndex for '${name}' returned no Id`,
394 });
395 }
396 yield* session.note(`Creating index ${name} (${created.Id})...`);
397 yield* waitForIndexStatus(created.Id, "ACTIVE");
398 state = yield* readIndexById(created.Id, arnOf);
399 if (state === undefined) {
400 return yield* new KendraSearchIndexUnexpectedResponse({
401 message: `failed to read created index ${name}`,
402 });
403 }
404 }
405
406 // Sync mutable settings via UpdateIndex — only send drifted fields.
407 const described = state.described;
408 const desiredCapacity = news.capacityUnits
409 ? {
410 StorageCapacityUnits: news.capacityUnits.storageCapacityUnits,
411 QueryCapacityUnits: news.capacityUnits.queryCapacityUnits,
412 }
413 : undefined;
414 const capacityDrifted =
415 desiredCapacity !== undefined &&
416 (desiredCapacity.StorageCapacityUnits !==
417 described.CapacityUnits?.StorageCapacityUnits ||
418 desiredCapacity.QueryCapacityUnits !== described.CapacityUnits?.QueryCapacityUnits);
419 const needsUpdate =
420 name !== described.Name ||
421 news.roleArn !== described.RoleArn ||
422 (news.description ?? "") !== (described.Description ?? "") ||
423 (news.userContextPolicy !== undefined &&
424 news.userContextPolicy !== described.UserContextPolicy) ||
425 (news.userGroupResolutionConfiguration !== undefined &&
426 news.userGroupResolutionConfiguration.UserGroupResolutionMode !==
427 described.UserGroupResolutionConfiguration?.UserGroupResolutionMode) ||
428 news.userTokenConfigurations !== undefined ||
429 capacityDrifted;
430 if (needsUpdate) {
431 yield* kendra.updateIndex({
432 Id: state.attrs.id,
433 Name: name,
434 RoleArn: news.roleArn,
435 Description: news.description,
436 UserContextPolicy: news.userContextPolicy,
437 UserTokenConfigurations: news.userTokenConfigurations,
438 UserGroupResolutionConfiguration: news.userGroupResolutionConfiguration,
439 CapacityUnits: desiredCapacity,
440 });
441 yield* waitForIndexStatus(state.attrs.id, "ACTIVE");
442 yield* session.note(`Updated index ${name}`);
443 }
444
445 // Sync tags — diff against observed cloud tags.
446 const { removed, upsert } = diffTags(state.attrs.tags, desiredTags);
447 if (removed.length > 0) {
448 yield* kendra.untagResource({
449 ResourceARN: state.attrs.arn,
450 TagKeys: removed,
451 });
452 }
453 if (upsert.length > 0) {
454 yield* kendra.tagResource({
455 ResourceARN: state.attrs.arn,
456 Tags: upsert.map(({ Key, Value }) => ({ Key, Value })),
457 });
458 }
459
460 yield* session.note(state.attrs.arn);
461
462 const final = yield* readIndexById(state.attrs.id, arnOf);
463 if (!final) {
464 return yield* new KendraSearchIndexUnexpectedResponse({
465 message: `failed to read reconciled index ${name}`,
466 });
467 }
468 return final.attrs;
469 }),
470 delete: Effect.fn(function* ({ output }) {
471 yield* kendra
472 .deleteIndex({ Id: output.id })
473 .pipe(Effect.catchTag("ResourceNotFoundException", () => Effect.void));
474 yield* waitForIndexStatus(output.id, "DELETED");
475 }),
476 };
477 }),
478 );