@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 320 lines 11.7 KB
Raw
1 import * as s3vectors from "@distilled.cloud/aws/s3vectors";
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 Schedule from "effect/Schedule";
10 import * as Stream from "effect/Stream";
11 import type { PolicyStatement } from "../IAM/Policy.ts";
12 import type { Providers } from "../Providers.ts";
13
14 /**
15 * Server-side encryption configuration for a vector bucket. Immutable —
16 * changing it replaces the bucket.
17 */
18 export interface VectorBucketEncryption {
19 /**
20 * The SSE algorithm. `AES256` uses S3-managed keys; `aws:kms` uses a KMS
21 * key (supply `kmsKeyArn`).
22 * @default "AES256"
23 */
24 sseType?: "AES256" | "aws:kms";
25 /**
26 * ARN of the KMS key to use when `sseType` is `aws:kms`.
27 */
28 kmsKeyArn?: string;
29 }
30
31 export interface VectorBucketProps {
32 /**
33 * Name of the vector bucket (3-63 chars, lowercase). If omitted, a unique
34 * name is generated from the app, stage, and logical id.
35 *
36 * Changing the name replaces the bucket.
37 * @default ${app}-${stage}-${id}
38 */
39 vectorBucketName?: string;
40 /**
41 * Server-side encryption configuration. Immutable — changing it replaces
42 * the bucket.
43 */
44 encryption?: VectorBucketEncryption;
45 /**
46 * Resource policy statements for the vector bucket, granting or denying
47 * cross-account/principal access to it and the indexes inside it
48 * (`arn:…:bucket/<name>/index/*`). Rendered as a standard
49 * `2012-10-17` policy document via `PutVectorBucketPolicy`; omitting the
50 * prop removes any existing policy.
51 */
52 policy?: PolicyStatement[];
53 /**
54 * Tags to apply to the bucket. Merged with internal Alchemy tags.
55 */
56 tags?: Record<string, string>;
57 }
58
59 export interface VectorBucket extends Resource<
60 "AWS.S3Vectors.VectorBucket",
61 VectorBucketProps,
62 {
63 /**
64 * Name of the vector bucket.
65 */
66 vectorBucketName: string;
67 /**
68 * ARN of the vector bucket.
69 */
70 vectorBucketArn: string;
71 },
72 never,
73 Providers
74 > {}
75
76 /**
77 * An Amazon S3 Vectors bucket — durable storage for vector embeddings,
78 * queryable by similarity. Create one or more {@link Index}es inside it to
79 * store and query vectors.
80 *
81 * S3 Vectors is in preview; availability varies by region.
82 *
83 * ### Creating a Vector Bucket
84 * **Example:** Basic Vector Bucket
85 * ```typescript
86 * import * as S3Vectors from "@alchemy.run/aws/S3Vectors";
87 *
88 * const bucket = yield* S3Vectors.VectorBucket("Embeddings", {});
89 * ```
90 *
91 * **Example:** Vector Bucket with KMS Encryption
92 * ```typescript
93 * const bucket = yield* S3Vectors.VectorBucket("Embeddings", {
94 * encryption: { sseType: "aws:kms", kmsKeyArn: key.keyArn },
95 * });
96 * ```
97 *
98 * ### Bucket Policy
99 * **Example:** Grant Another Account Read Access
100 * ```typescript
101 * const bucket = yield* S3Vectors.VectorBucket("Embeddings", {
102 * vectorBucketName: "shared-embeddings",
103 * policy: [
104 * {
105 * Effect: "Allow",
106 * Principal: { AWS: "arn:aws:iam::123456789012:root" },
107 * Action: ["s3vectors:GetVectors", "s3vectors:QueryVectors"],
108 * Resource:
109 * "arn:aws:s3vectors:us-east-1:999999999999:bucket/shared-embeddings/index/*",
110 * },
111 * ],
112 * });
113 * ```
114 *
115 * @resource
116 */
117 export const VectorBucket = Resource<VectorBucket>("AWS.S3Vectors.VectorBucket");
118
119 const encryptionKey = (e: VectorBucketEncryption | undefined) =>
120 JSON.stringify({ sseType: e?.sseType, kmsKeyArn: e?.kmsKeyArn });
121
122 export const VectorBucketProvider = () =>
123 Provider.effect(
124 VectorBucket,
125 Effect.gen(function* () {
126 const createName = Effect.fn(function* (
127 id: string,
128 props: Pick<VectorBucketProps, "vectorBucketName">,
129 ) {
130 // The service rejects bucket names starting with `aws` as reserved.
131 return (
132 props.vectorBucketName ??
133 (yield* createPhysicalName({
134 id,
135 maxLength: 63,
136 forbiddenPrefixes: ["aws"],
137 })).toLowerCase()
138 );
139 });
140
141 const observe = (vectorBucketName: string) =>
142 s3vectors.getVectorBucket({ vectorBucketName }).pipe(
143 Effect.map((r) => r.vectorBucket),
144 Effect.catchTag("NotFoundException", () => Effect.undefined),
145 );
146
147 const observedTags = (resourceArn: string) =>
148 s3vectors.listTagsForResource({ resourceArn }).pipe(
149 Effect.map(
150 (r) =>
151 Object.fromEntries(
152 Object.entries(r.tags ?? {}).filter(([, v]) => v !== undefined),
153 ) as Record<string, string>,
154 ),
155 Effect.catchTag("NotFoundException", () => Effect.succeed({} as Record<string, string>)),
156 );
157
158 const observedPolicy = (vectorBucketName: string) =>
159 s3vectors.getVectorBucketPolicy({ vectorBucketName }).pipe(
160 Effect.map((r) => r.policy),
161 Effect.catchTag("NotFoundException", () =>
162 Effect.succeed(undefined as string | undefined),
163 ),
164 );
165
166 const desiredEncryption = (props: VectorBucketProps) =>
167 props.encryption
168 ? {
169 sseType: props.encryption.sseType,
170 kmsKeyArn: props.encryption.kmsKeyArn,
171 }
172 : undefined;
173
174 return VectorBucket.Provider.of({
175 stables: ["vectorBucketName", "vectorBucketArn"],
176 list: () =>
177 Effect.gen(function* () {
178 const buckets = yield* s3vectors.listVectorBuckets.items({}).pipe(Stream.runCollect);
179 return Array.from(buckets).map((b) => ({
180 vectorBucketName: b.vectorBucketName,
181 vectorBucketArn: b.vectorBucketArn,
182 }));
183 }),
184 read: Effect.fn(function* ({ id, olds, output }) {
185 const name = output?.vectorBucketName ?? (yield* createName(id, olds ?? {}));
186 const found = yield* observe(name);
187 if (!found) return undefined;
188 const attrs = {
189 vectorBucketName: found.vectorBucketName,
190 vectorBucketArn: found.vectorBucketArn,
191 };
192 const tags = yield* observedTags(found.vectorBucketArn);
193 return (yield* hasAlchemyTags(id, tags)) ? attrs : Unowned(attrs);
194 }),
195 diff: Effect.fn(function* ({ id, news, olds }) {
196 if (!isResolved(news)) return undefined;
197 const oldName = yield* createName(id, olds ?? {});
198 const newName = yield* createName(id, news ?? {});
199 if (oldName !== newName) return { action: "replace" } as const;
200 // Encryption is fixed at create time — any change replaces.
201 if (encryptionKey(olds?.encryption) !== encryptionKey(news?.encryption)) {
202 return { action: "replace" } as const;
203 }
204 // fall through: engine default update (tags only)
205 }),
206 reconcile: Effect.fn(function* ({ id, news, output, session }) {
207 const name = output?.vectorBucketName ?? (yield* createName(id, news));
208 const internalTags = yield* createInternalTags(id);
209 const desiredTags = { ...news.tags, ...internalTags };
210
211 // 1. OBSERVE — cloud state is authoritative.
212 let live = yield* observe(name);
213
214 // 2. ENSURE — create when missing; a concurrent create surfaces as
215 // ConflictException, which we treat as a race and re-observe.
216 if (live === undefined) {
217 yield* s3vectors
218 .createVectorBucket({
219 vectorBucketName: name,
220 encryptionConfiguration: desiredEncryption(news),
221 tags: desiredTags,
222 })
223 .pipe(Effect.catchTag("ConflictException", () => Effect.void));
224 live = yield* observe(name);
225 }
226
227 const vectorBucketArn = live?.vectorBucketArn ?? output?.vectorBucketArn;
228
229 // 3. SYNC TAGS — diff against OBSERVED cloud tags so adoption and
230 // drift converge (create-time tags only apply on first create).
231 if (vectorBucketArn !== undefined) {
232 const currentTags = yield* observedTags(vectorBucketArn);
233 const { upsert, removed } = diffTags(currentTags, desiredTags);
234 if (upsert.length > 0) {
235 yield* s3vectors.tagResource({
236 resourceArn: vectorBucketArn,
237 tags: Object.fromEntries(upsert.map((t) => [t.Key, t.Value])),
238 });
239 }
240 if (removed.length > 0) {
241 yield* s3vectors.untagResource({
242 resourceArn: vectorBucketArn,
243 tagKeys: removed,
244 });
245 }
246 }
247
248 // 4. SYNC POLICY — diff desired against the OBSERVED bucket policy
249 // so adoption and drift converge (delete when the prop is gone).
250 const desiredPolicy =
251 news.policy !== undefined && news.policy.length > 0
252 ? JSON.stringify({
253 Version: "2012-10-17",
254 Statement: news.policy,
255 })
256 : undefined;
257 const existingPolicy = yield* observedPolicy(name);
258 if (desiredPolicy !== undefined) {
259 if (existingPolicy !== desiredPolicy) {
260 yield* s3vectors.putVectorBucketPolicy({
261 vectorBucketName: name,
262 policy: desiredPolicy,
263 });
264 yield* session.note(`Updated bucket policy: ${name}`);
265 }
266 } else if (existingPolicy !== undefined) {
267 yield* s3vectors
268 .deleteVectorBucketPolicy({ vectorBucketName: name })
269 .pipe(Effect.catchTag("NotFoundException", () => Effect.void));
270 yield* session.note(`Removed bucket policy: ${name}`);
271 }
272
273 yield* session.note(name);
274 return { vectorBucketName: name, vectorBucketArn: vectorBucketArn! };
275 }),
276 delete: Effect.fn(function* ({ output, force }) {
277 const vectorBucketName = output.vectorBucketName;
278 if (force !== true) {
279 yield* s3vectors
280 .deleteVectorBucket({ vectorBucketName })
281 .pipe(Effect.catchTag("NotFoundException", () => Effect.void));
282 return;
283 }
284
285 const purgeAndDelete = Effect.gen(function* () {
286 // Indexes are scoped to their bucket and invisible to a global
287 // nuke scan. Only the explicit force path may purge them.
288 const indexes = yield* s3vectors.listIndexes.items({ vectorBucketName }).pipe(
289 Stream.runCollect,
290 Effect.map((chunk) => Array.from(chunk)),
291 Effect.catchTag("NotFoundException", () => Effect.succeed([])),
292 );
293 yield* Effect.forEach(
294 indexes,
295 (index) =>
296 s3vectors
297 .deleteIndex({
298 vectorBucketName,
299 indexName: index.indexName,
300 })
301 .pipe(Effect.catchTag("NotFoundException", () => Effect.void)),
302 { concurrency: 4, discard: true },
303 );
304 yield* s3vectors.deleteVectorBucket({ vectorBucketName });
305 });
306
307 yield* purgeAndDelete.pipe(
308 // Index deletion is eventually consistent and bucket deletion can
309 // report Conflict until all indexes disappear. Re-list on retry.
310 Effect.retry({
311 while: (e) =>
312 e._tag === "ConflictException" || e._tag === "ServiceUnavailableException",
313 schedule: Schedule.max([Schedule.exponential(500), Schedule.recurs(8)]),
314 }),
315 Effect.catchTag("NotFoundException", () => Effect.void),
316 );
317 }),
318 });
319 }),
320 );