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

main
ts 436 lines 15.2 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 KendraDataSourceInvalidProps extends Data.TaggedError("KendraDataSourceInvalidProps")<{
16 readonly message: string;
17 readonly cause?: unknown;
18 }> {}
19
20 export class KendraDataSourceUnexpectedResponse extends Data.TaggedError(
21 "KendraDataSourceUnexpectedResponse",
22 )<{
23 readonly message: string;
24 readonly cause?: unknown;
25 }> {}
26
27 export type DataSourceStatus = kendra.DataSourceStatus;
28 export type DataSourceType = kendra.DataSourceType;
29
30 export interface DataSourceProps {
31 /**
32 * The identifier of the Kendra index the data source connects to.
33 * Changing it replaces the data source.
34 */
35 indexId: string;
36 /**
37 * Name of the data source.
38 * @default ${app}-${stage}-${id}
39 */
40 name?: string;
41 /**
42 * The connector type (e.g. `S3`, `TEMPLATE`, `WEBCRAWLER`, `CUSTOM`).
43 * Changing it replaces the data source.
44 */
45 type: DataSourceType;
46 /**
47 * Connector-specific configuration (e.g. `S3Configuration` or
48 * `TemplateConfiguration`). Required for all types except `CUSTOM`.
49 */
50 configuration?: kendra.DataSourceConfiguration;
51 /**
52 * VPC configuration for connectors that reach into a VPC.
53 */
54 vpcConfiguration?: kendra.DataSourceVpcConfiguration;
55 /**
56 * A description of the data source.
57 */
58 description?: string;
59 /**
60 * Sync schedule as a cron expression (e.g. `cron(0 12 * * ? *)`). When
61 * omitted, syncs run only on demand.
62 */
63 schedule?: string;
64 /**
65 * ARN of the IAM role Kendra assumes to access the source content.
66 * Required for all types except `CUSTOM`.
67 */
68 roleArn?: string;
69 /**
70 * The code for a language the source documents are in.
71 * @default "en"
72 */
73 languageCode?: string;
74 /**
75 * Alter document metadata/content during ingestion.
76 */
77 customDocumentEnrichmentConfiguration?: kendra.CustomDocumentEnrichmentConfiguration;
78 /**
79 * Tags to associate with the data source.
80 */
81 tags?: Record<string, string>;
82 }
83
84 export interface DataSource extends Resource<
85 "AWS.Kendra.DataSource",
86 DataSourceProps,
87 {
88 /**
89 * Service-assigned unique identifier of the data source (unique within
90 * its index).
91 */
92 id: string;
93 /**
94 * The identifier of the index the data source belongs to.
95 */
96 indexId: string;
97 /**
98 * ARN of the data source.
99 */
100 arn: string;
101 /**
102 * The data source's name.
103 */
104 name: string;
105 /**
106 * The connector type.
107 */
108 type: DataSourceType | undefined;
109 /**
110 * Current lifecycle status of the data source.
111 */
112 status: DataSourceStatus | undefined;
113 /**
114 * Current tags reported for the data source.
115 */
116 tags: Record<string, string>;
117 },
118 never,
119 Providers
120 > {}
121
122 /**
123 * An Amazon Kendra data source — a connector that syncs documents from a
124 * repository (S3 bucket, SharePoint, website, ...) into a Kendra index.
125 *
126 * ### Creating Data Sources
127 * **Example:** S3 Data Source
128 * ```typescript
129 * import * as AWS from "@alchemy.run/aws";
130 *
131 * const source = yield* AWS.Kendra.DataSource("Docs", {
132 * indexId: index.id,
133 * type: "S3",
134 * roleArn: dataSourceRole.roleArn,
135 * configuration: {
136 * S3Configuration: {
137 * BucketName: bucket.bucketName,
138 * },
139 * },
140 * });
141 * ```
142 *
143 * **Example:** Scheduled Sync
144 * ```typescript
145 * const source = yield* AWS.Kendra.DataSource("Docs", {
146 * indexId: index.id,
147 * type: "S3",
148 * roleArn: dataSourceRole.roleArn,
149 * schedule: "cron(0 12 * * ? *)",
150 * configuration: {
151 * S3Configuration: { BucketName: bucket.bucketName },
152 * },
153 * });
154 * ```
155 *
156 * @resource
157 */
158 export const DataSource = Resource<DataSource>("AWS.Kendra.DataSource");
159
160 const createDataSourceName = (id: string, props: { name?: string | undefined }) =>
161 props.name ? Effect.succeed(props.name) : createPhysicalName({ id, maxLength: 100 });
162
163 const fetchTags = Effect.fn(function* (arn: string) {
164 const response = yield* kendra
165 .listTagsForResource({ ResourceARN: arn })
166 .pipe(
167 Effect.catchTag(
168 ["ResourceNotFoundException", "ResourceUnavailableException"],
169 () => Effect.undefined,
170 ),
171 );
172 return Object.fromEntries((response?.Tags ?? []).map((tag) => [tag.Key, tag.Value]));
173 });
174
175 const currentArnOf = Effect.gen(function* () {
176 const { accountId, region } = yield* AWSEnvironment.current;
177 return (indexId: string, dataSourceId: string) =>
178 `arn:aws:kendra:${region}:${accountId}:index/${indexId}/data-source/${dataSourceId}`;
179 });
180
181 interface DataSourceState {
182 attrs: DataSource["Attributes"];
183 described: kendra.DescribeDataSourceResponse;
184 }
185
186 const readDataSourceById = Effect.fn(function* (
187 indexId: string,
188 dataSourceId: string,
189 arnOf: (indexId: string, dataSourceId: string) => string,
190 ) {
191 const described = yield* kendra
192 .describeDataSource({ IndexId: indexId, Id: dataSourceId })
193 .pipe(Effect.catchTag("ResourceNotFoundException", () => Effect.undefined));
194 if (!described || described.Status === "DELETING") return undefined;
195 const arn = arnOf(described.IndexId ?? indexId, described.Id ?? dataSourceId);
196 const state: DataSourceState = {
197 described,
198 attrs: {
199 id: described.Id ?? dataSourceId,
200 indexId: described.IndexId ?? indexId,
201 arn,
202 name: described.Name ?? "",
203 type: described.Type,
204 status: described.Status,
205 tags: yield* fetchTags(arn),
206 },
207 };
208 return state;
209 });
210
211 const findDataSourceByName = Effect.fn(function* (
212 indexId: string,
213 name: string,
214 arnOf: (indexId: string, dataSourceId: string) => string,
215 ) {
216 const summaries = yield* kendra.listDataSources.pages({ IndexId: indexId }).pipe(
217 EffectStream.runCollect,
218 Effect.map((chunk) => Array.from(chunk).flatMap((page) => page.SummaryItems ?? [])),
219 // The parent index may itself be gone.
220 Effect.catchTag("ResourceNotFoundException", () =>
221 Effect.succeed([] as kendra.DataSourceSummary[]),
222 ),
223 );
224 const match = summaries.find((summary) => summary.Name === name && summary.Status !== "DELETING");
225 if (!match?.Id) return undefined;
226 return yield* readDataSourceById(indexId, match.Id, arnOf);
227 });
228
229 /**
230 * A data source still transitioning toward the awaited status — retried by
231 * {@link waitForDataSourceStatus}'s bounded schedule.
232 */
233 class DataSourceNotReady extends Data.TaggedError("DataSourceNotReady")<{
234 readonly id: string;
235 readonly status: string | undefined;
236 }> {}
237
238 /**
239 * A data source whose asynchronous provisioning converged to the terminal
240 * `FAILED` status.
241 */
242 export class DataSourceProvisioningFailed extends Data.TaggedError("DataSourceProvisioningFailed")<{
243 readonly id: string;
244 readonly message: string | undefined;
245 }> {}
246
247 // Explicitly-typed retry wrapper — an inline `Effect.retry` in provider
248 // lifecycle code leaks `Retry.Return`'s conditional type into declaration
249 // emit and widens the provider layer to `unknown` for every consumer of
250 // `AWS.providers()`.
251 const retryWhileNotReady = <A, E extends { readonly _tag: string }, R>(
252 self: Effect.Effect<A, E, R>,
253 ): Effect.Effect<A, E, R> =>
254 Effect.retry(self, {
255 while: (e) => e._tag === "DataSourceNotReady",
256 // Data source provisioning is usually well under a minute; budget ~5 min.
257 schedule: Schedule.max([Schedule.spaced("5 seconds"), Schedule.recurs(60)]),
258 });
259
260 // CreateDataSource validates the IAM role up front; a freshly-created role
261 // may not have propagated yet and surfaces as ValidationException. Bounded
262 // retry through the propagation window (~60s). Explicitly typed for the same
263 // declaration-emit reason as retryWhileNotReady.
264 const retryThroughIamPropagation = <A, E extends { readonly _tag: string }, R>(
265 self: Effect.Effect<A, E, R>,
266 ): Effect.Effect<A, E, R> =>
267 Effect.retry(self, {
268 while: (e) => e._tag === "ValidationException",
269 schedule: Schedule.max([Schedule.spaced("5 seconds"), Schedule.recurs(12)]),
270 });
271
272 const waitForDataSourceStatus = (indexId: string, id: string, target: "ACTIVE" | "DELETED") =>
273 retryWhileNotReady(
274 Effect.gen(function* () {
275 const described = yield* kendra
276 .describeDataSource({ IndexId: indexId, Id: id })
277 .pipe(Effect.catchTag("ResourceNotFoundException", () => Effect.undefined));
278 if (target === "DELETED") {
279 if (described === undefined) return;
280 return yield* new DataSourceNotReady({ id, status: described.Status });
281 }
282 if (described?.Status === "ACTIVE") return;
283 if (described?.Status === "FAILED") {
284 return yield* new DataSourceProvisioningFailed({
285 id,
286 message: described.ErrorMessage,
287 });
288 }
289 return yield* new DataSourceNotReady({ id, status: described?.Status });
290 }),
291 );
292
293 export const DataSourceProvider = () =>
294 Provider.effect(
295 DataSource,
296 Effect.gen(function* () {
297 return {
298 stables: ["id", "indexId", "arn"],
299 // Keyed by a parent index; cannot be enumerated account-wide without
300 // iterating every index — treated as a sub-resource per the factory
301 // list() convention.
302 list: () => Effect.succeed([]),
303 read: Effect.fn(function* ({ id, olds, output }) {
304 const arnOf = yield* currentArnOf;
305 const indexId = output?.indexId ?? olds?.indexId;
306 if (indexId === undefined) return undefined;
307 const state = output?.id
308 ? yield* readDataSourceById(indexId, output.id, arnOf)
309 : yield* findDataSourceByName(
310 indexId,
311 yield* createDataSourceName(id, olds ?? {}),
312 arnOf,
313 );
314 if (!state) return undefined;
315 return (yield* hasAlchemyTags(id, state.attrs.tags as Tags))
316 ? state.attrs
317 : Unowned(state.attrs);
318 }),
319 diff: Effect.fn(function* ({ news, olds }) {
320 if (!isResolved(news)) return;
321 if (olds === undefined) return;
322 // The parent index and connector type are fixed at creation.
323 if (olds.indexId !== news.indexId || olds.type !== news.type) {
324 return { action: "replace" } as const;
325 }
326 }),
327 reconcile: Effect.fn(function* ({ id, news, output, session }) {
328 if (!news) {
329 return yield* new KendraDataSourceInvalidProps({
330 message: "Kendra DataSource requires props",
331 });
332 }
333 const arnOf = yield* currentArnOf;
334 const indexId = news.indexId;
335 const name = yield* createDataSourceName(id, news);
336 const internalTags = yield* createInternalTags(id);
337 const desiredTags = { ...internalTags, ...news.tags };
338
339 // Observe — prefer the cached id; fall back to a name lookup so a
340 // create whose state failed to persist is adopted, not duplicated.
341 let state = output?.id
342 ? yield* readDataSourceById(indexId, output.id, arnOf)
343 : yield* findDataSourceByName(indexId, name, arnOf);
344
345 // Ensure — create if missing, then wait for ACTIVE.
346 if (state === undefined) {
347 const created = yield* retryThroughIamPropagation(
348 kendra.createDataSource({
349 IndexId: indexId,
350 Name: name,
351 Type: news.type,
352 Configuration: news.configuration,
353 VpcConfiguration: news.vpcConfiguration,
354 Description: news.description,
355 Schedule: news.schedule,
356 RoleArn: news.roleArn,
357 LanguageCode: news.languageCode,
358 CustomDocumentEnrichmentConfiguration: news.customDocumentEnrichmentConfiguration,
359 Tags: Object.entries(desiredTags).map(([Key, Value]) => ({
360 Key,
361 Value,
362 })),
363 }),
364 );
365 yield* session.note(`Creating data source ${name} (${created.Id})...`);
366 yield* waitForDataSourceStatus(indexId, created.Id, "ACTIVE");
367 state = yield* readDataSourceById(indexId, created.Id, arnOf);
368 if (state === undefined) {
369 return yield* new KendraDataSourceUnexpectedResponse({
370 message: `failed to read created data source ${name}`,
371 });
372 }
373 }
374
375 // Sync mutable settings via UpdateDataSource — only when drifted.
376 const described = state.described;
377 const needsUpdate =
378 name !== described.Name ||
379 (news.description ?? "") !== (described.Description ?? "") ||
380 (news.schedule ?? "") !== (described.Schedule ?? "") ||
381 (news.roleArn !== undefined && news.roleArn !== described.RoleArn) ||
382 (news.languageCode !== undefined && news.languageCode !== described.LanguageCode) ||
383 news.configuration !== undefined ||
384 news.vpcConfiguration !== undefined ||
385 news.customDocumentEnrichmentConfiguration !== undefined;
386 if (needsUpdate) {
387 yield* kendra.updateDataSource({
388 Id: state.attrs.id,
389 IndexId: indexId,
390 Name: name,
391 Configuration: news.configuration,
392 VpcConfiguration: news.vpcConfiguration,
393 Description: news.description,
394 Schedule: news.schedule,
395 RoleArn: news.roleArn,
396 LanguageCode: news.languageCode,
397 CustomDocumentEnrichmentConfiguration: news.customDocumentEnrichmentConfiguration,
398 });
399 yield* waitForDataSourceStatus(indexId, state.attrs.id, "ACTIVE");
400 yield* session.note(`Updated data source ${name}`);
401 }
402
403 // Sync tags — diff against observed cloud tags.
404 const { removed, upsert } = diffTags(state.attrs.tags, desiredTags);
405 if (removed.length > 0) {
406 yield* kendra.untagResource({
407 ResourceARN: state.attrs.arn,
408 TagKeys: removed,
409 });
410 }
411 if (upsert.length > 0) {
412 yield* kendra.tagResource({
413 ResourceARN: state.attrs.arn,
414 Tags: upsert.map(({ Key, Value }) => ({ Key, Value })),
415 });
416 }
417
418 yield* session.note(state.attrs.arn);
419
420 const final = yield* readDataSourceById(indexId, state.attrs.id, arnOf);
421 if (!final) {
422 return yield* new KendraDataSourceUnexpectedResponse({
423 message: `failed to read reconciled data source ${name}`,
424 });
425 }
426 return final.attrs;
427 }),
428 delete: Effect.fn(function* ({ output }) {
429 yield* kendra
430 .deleteDataSource({ IndexId: output.indexId, Id: output.id })
431 .pipe(Effect.catchTag("ResourceNotFoundException", () => Effect.void));
432 yield* waitForDataSourceStatus(output.indexId, output.id, "DELETED");
433 }),
434 };
435 }),
436 );