@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, 04:45 UTC

main
ts 324 lines 11.2 KB
Raw
1 import * as aoss from "@distilled.cloud/aws/opensearchserverless";
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 } from "alchemy/Tags";
8 import * as Effect from "effect/Effect";
9 import * as Stream from "effect/Stream";
10 import type { Providers } from "../Providers.ts";
11 import {
12 awaitCollectionActive,
13 recordToTagList,
14 retryWhileConflict,
15 tagsToRecord,
16 } from "./internal.ts";
17
18 /**
19 * The collection type, which determines the OpenSearch features available:
20 * - `SEARCH` — full-text search and analytics.
21 * - `TIMESERIES` — log analytics over time-ordered data.
22 * - `VECTORSEARCH` — vector (k-NN) similarity search — the type required to
23 * back an Amazon Bedrock Knowledge Base.
24 */
25 export type CollectionType = "SEARCH" | "TIMESERIES" | "VECTORSEARCH";
26
27 export interface CollectionProps {
28 /**
29 * Name of the collection (3-32 characters, lowercase; must start with a
30 * lowercase letter). Must be matched by an encryption
31 * {@link SecurityPolicy | security policy} before it can be created. Changing
32 * the name replaces the collection.
33 * @default a generated physical name
34 */
35 collectionName?: string;
36 /**
37 * The collection type. Changing the type replaces the collection.
38 * @default "SEARCH"
39 */
40 type?: CollectionType;
41 /**
42 * A human-readable description of the collection.
43 */
44 description?: string;
45 /**
46 * Whether to deploy redundant standby replicas (`ENABLED` doubles the OCU
47 * floor but provides higher availability). Set at creation time.
48 * @default "ENABLED"
49 */
50 standbyReplicas?: "ENABLED" | "DISABLED";
51 /**
52 * Whether deletion protection is enabled. When `ENABLED`, the collection
53 * cannot be deleted until protection is turned off.
54 * @default "DISABLED"
55 */
56 deletionProtection?: "ENABLED" | "DISABLED";
57 /**
58 * Tags to apply to the collection. Merged with the internal Alchemy tags.
59 */
60 tags?: Record<string, string>;
61 }
62
63 export interface Collection extends Resource<
64 "AWS.OpenSearchServerless.Collection",
65 CollectionProps,
66 {
67 /**
68 * Unique identifier of the collection.
69 */
70 collectionId: string;
71 /**
72 * Name of the collection.
73 */
74 collectionName: string;
75 /**
76 * ARN of the collection.
77 */
78 collectionArn: string;
79 /**
80 * Collection type (`SEARCH`, `TIMESERIES`, or `VECTORSEARCH`).
81 */
82 type?: string;
83 /**
84 * Collection status (e.g. `ACTIVE`, `CREATING`, `DELETING`).
85 */
86 status?: string;
87 /**
88 * ARN of the KMS key encrypting the collection.
89 */
90 kmsKeyArn?: string;
91 /**
92 * OpenSearch endpoint for data-plane requests.
93 */
94 collectionEndpoint?: string;
95 /**
96 * OpenSearch Dashboards endpoint for the collection.
97 */
98 dashboardEndpoint?: string;
99 },
100 {},
101 Providers
102 > {}
103
104 /**
105 * An Amazon OpenSearch Serverless collection — a group of OpenSearch indexes
106 * that scales OpenSearch Compute Units (OCUs) automatically. A collection of
107 * type `VECTORSEARCH` is the vector store required to back an Amazon Bedrock
108 * Knowledge Base.
109 *
110 * A collection requires a matching encryption {@link SecurityPolicy} to exist
111 * before creation, plus a network security policy and a data
112 * {@link AccessPolicy} to be reachable and usable. Creation is asynchronous —
113 * the provider polls (bounded, ~5 minutes) until the collection reaches
114 * `ACTIVE`.
115 *
116 * ### Creating Collections
117 * **Example:** Vector Search Collection for a Bedrock Knowledge Base
118 * ```typescript
119 * import * as AWS from "@alchemy.run/aws";
120 *
121 * const encryption = yield* AWS.OpenSearchServerless.SecurityPolicy("Enc", {
122 * policyName: "kb-enc",
123 * type: "encryption",
124 * policy: {
125 * Rules: [{ ResourceType: "collection", Resource: ["collection/kb"] }],
126 * AWSOwnedKey: true,
127 * },
128 * });
129 * const network = yield* AWS.OpenSearchServerless.SecurityPolicy("Net", {
130 * policyName: "kb-net",
131 * type: "network",
132 * policy: [
133 * {
134 * Rules: [
135 * { ResourceType: "collection", Resource: ["collection/kb"] },
136 * { ResourceType: "dashboard", Resource: ["collection/kb"] },
137 * ],
138 * AllowFromPublic: true,
139 * },
140 * ],
141 * });
142 * const collection = yield* AWS.OpenSearchServerless.Collection("KB", {
143 * collectionName: "kb",
144 * type: "VECTORSEARCH",
145 * });
146 * // collection.collectionEndpoint is the aoss data-plane endpoint
147 * ```
148 *
149 * ### Search Collections
150 * **Example:** Simple Search Collection
151 * ```typescript
152 * const collection = yield* AWS.OpenSearchServerless.Collection("Search", {
153 * collectionName: "logs",
154 * type: "SEARCH",
155 * description: "application logs",
156 * });
157 * ```
158 *
159 * @resource
160 */
161 export const Collection = Resource<Collection>("AWS.OpenSearchServerless.Collection");
162
163 export const CollectionProvider = () =>
164 Provider.effect(
165 Collection,
166 Effect.gen(function* () {
167 const createName = Effect.fn(function* (
168 id: string,
169 props: { collectionName?: string | undefined },
170 ) {
171 return (
172 props.collectionName ??
173 (yield* createPhysicalName({ id, maxLength: 32, lowercase: true }))
174 );
175 });
176
177 const toAttributes = (detail: aoss.CollectionDetail) => ({
178 collectionId: detail.id!,
179 collectionName: detail.name!,
180 collectionArn: detail.arn!,
181 type: detail.type,
182 status: detail.status,
183 kmsKeyArn: detail.kmsKeyArn,
184 collectionEndpoint: detail.collectionEndpoint,
185 dashboardEndpoint: detail.dashboardEndpoint,
186 });
187
188 const observeByName = Effect.fn(function* (name: string) {
189 const response = yield* aoss.batchGetCollection({ names: [name] });
190 return response.collectionDetails?.[0];
191 });
192
193 const syncTags = Effect.fn(function* (arn: string, desired: Record<string, string>) {
194 const observed = yield* aoss
195 .listTagsForResource({ resourceArn: arn })
196 .pipe(Effect.map((r) => tagsToRecord(r.tags)));
197 const { upsert, removed } = diffTags(observed, desired);
198 if (upsert.length > 0) {
199 yield* aoss.tagResource({
200 resourceArn: arn,
201 tags: recordToTagList(Object.fromEntries(upsert.map((t) => [t.Key, t.Value]))),
202 });
203 }
204 if (removed.length > 0) {
205 yield* aoss.untagResource({ resourceArn: arn, tagKeys: removed });
206 }
207 });
208
209 return Collection.Provider.of({
210 stables: ["collectionId", "collectionName", "collectionArn"],
211
212 list: () =>
213 Effect.gen(function* () {
214 const pages = yield* aoss.listCollections.pages({}).pipe(Stream.runCollect);
215 return Array.from(pages)
216 .flatMap((page) => page.collectionSummaries ?? [])
217 .filter((s) => s.id !== undefined && s.name !== undefined && s.arn !== undefined)
218 .map((s) => ({
219 collectionId: s.id!,
220 collectionName: s.name!,
221 collectionArn: s.arn!,
222 status: s.status,
223 kmsKeyArn: s.kmsKeyArn,
224 }));
225 }),
226
227 read: Effect.fn(function* ({ id, olds, output }) {
228 const name = output?.collectionName ?? (yield* createName(id, olds ?? {}));
229 const detail = yield* observeByName(name);
230 if (detail?.id === undefined || detail.arn === undefined) {
231 return undefined;
232 }
233 const attrs = toAttributes(detail);
234 const tags = yield* aoss.listTagsForResource({ resourceArn: detail.arn }).pipe(
235 Effect.map((r) => r.tags),
236 Effect.orElseSucceed(() => undefined),
237 );
238 return (yield* hasAlchemyTags(
239 id,
240 (tags ?? []).map((t) => ({ Key: t.key, Value: t.value })),
241 ))
242 ? attrs
243 : Unowned(attrs);
244 }),
245
246 diff: Effect.fn(function* ({ id, news, olds }) {
247 if (!isResolved(news)) return undefined;
248 const oldName = yield* createName(id, olds);
249 const newName = yield* createName(id, news);
250 if (oldName !== newName) {
251 return { action: "replace" } as const;
252 }
253 if ((olds.type ?? "SEARCH") !== (news.type ?? "SEARCH")) {
254 return { action: "replace" } as const;
255 }
256 // description/deletionProtection/tags fall through to update
257 }),
258
259 reconcile: Effect.fn(function* ({ id, news, output, session }) {
260 const name = output?.collectionName ?? (yield* createName(id, news));
261 const type = news.type ?? "SEARCH";
262 const internalTags = yield* createInternalTags(id);
263 const desiredTags = { ...news.tags, ...internalTags };
264
265 // 1. OBSERVE — cloud state is authoritative
266 let detail = yield* observeByName(name);
267
268 // 2. ENSURE — create if missing; wait for ACTIVE (async provisioning)
269 if (detail === undefined) {
270 const created = yield* aoss
271 .createCollection({
272 name,
273 type,
274 description: news.description,
275 standbyReplicas: news.standbyReplicas,
276 deletionProtection: news.deletionProtection,
277 tags: recordToTagList(desiredTags),
278 })
279 .pipe(
280 Effect.map((r) => r.createCollectionDetail),
281 // a concurrent reconciler already created it — fall through
282 Effect.catchTag("ConflictException", () => Effect.undefined),
283 );
284 const collectionId = created?.id ?? (yield* observeByName(name))?.id;
285 if (collectionId === undefined) {
286 return yield* aoss.ResourceNotFoundException.make({
287 message: `collection ${name} not visible after create`,
288 });
289 }
290 yield* session.note(`creating collection ${name} (async)...`);
291 detail = yield* awaitCollectionActive(collectionId);
292 } else if (detail.status !== "ACTIVE") {
293 detail = yield* awaitCollectionActive(detail.id!);
294 }
295
296 // 3. SYNC — description (deletionProtection updates alongside)
297 const descriptionDrift =
298 news.description !== undefined && news.description !== detail.description;
299 const protectionDrift =
300 news.deletionProtection !== undefined &&
301 news.deletionProtection !== detail.deletionProtection;
302 if (descriptionDrift || protectionDrift) {
303 yield* aoss.updateCollection({
304 id: detail.id!,
305 description: descriptionDrift ? news.description : undefined,
306 deletionProtection: protectionDrift ? news.deletionProtection : undefined,
307 });
308 }
309
310 // 3b. SYNC TAGS — diff against observed cloud tags
311 yield* syncTags(detail.arn!, desiredTags);
312
313 yield* session.note(detail.id!);
314 return toAttributes(detail);
315 }),
316
317 delete: Effect.fn(function* ({ output }) {
318 yield* retryWhileConflict(aoss.deleteCollection({ id: output.collectionId })).pipe(
319 Effect.catchTag("ResourceNotFoundException", () => Effect.void),
320 );
321 }),
322 });
323 }),
324 );