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

main
ts 454 lines 16.7 KB
Raw
1 import * as neptunegraph from "@distilled.cloud/aws/neptune-graph";
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 { createInternalTags, diffTags } from "alchemy/Tags";
7 import * as Data from "effect/Data";
8 import * as Effect from "effect/Effect";
9 import * as Option from "effect/Option";
10 import * as Schedule from "effect/Schedule";
11 import * as Stream from "effect/Stream";
12 import type { Providers } from "../Providers.ts";
13
14 export class NeptuneGraphGraphUnexpectedResponse extends Data.TaggedError(
15 "NeptuneGraphGraphUnexpectedResponse",
16 )<{
17 readonly message: string;
18 readonly cause?: unknown;
19 }> {}
20
21 export interface GraphProps {
22 /**
23 * Name of the graph (lowercase letters, numbers, and hyphens; must start
24 * with a letter). If omitted, a deterministic name is generated.
25 * Changing it forces replacement.
26 */
27 graphName?: string;
28 /**
29 * Provisioned memory-optimized Neptune Capacity Units (m-NCUs) for the
30 * graph, e.g. `16`, `32`, `64`. In-place modify.
31 */
32 provisionedMemory: number;
33 /**
34 * Whether the graph endpoint is reachable from the public internet
35 * (requests are still IAM-authenticated). In-place modify.
36 * @default false
37 */
38 publicConnectivity?: boolean;
39 /**
40 * Number of replicas in other AZs. Replicas incur additional cost.
41 * Immutable — forces replacement.
42 * @default 1
43 */
44 replicaCount?: number;
45 /**
46 * KMS key used to encrypt data in the graph. Immutable — forces
47 * replacement.
48 */
49 kmsKeyIdentifier?: string;
50 /**
51 * Vector-search configuration (dimension of vectors, 1-65535). Immutable —
52 * forces replacement.
53 */
54 vectorSearchConfiguration?: {
55 /**
56 * Number of dimensions per vector.
57 */
58 dimension: number;
59 };
60 /**
61 * Block accidental deletion. In-place modify.
62 * @default true
63 */
64 deletionProtection?: boolean;
65 /**
66 * User-defined tags.
67 */
68 tags?: Record<string, string>;
69 }
70
71 export interface Graph extends Resource<
72 "AWS.NeptuneGraph.Graph",
73 GraphProps,
74 {
75 /** Server-assigned unique id of the graph (e.g. `g-abc123`). */
76 graphId: string;
77 /** Name of the graph. */
78 graphName: string;
79 /** ARN of the graph. */
80 graphArn: string;
81 /** HTTPS query endpoint of the graph. */
82 endpoint: string | undefined;
83 /** Current lifecycle status (e.g. `CREATING`, `AVAILABLE`). */
84 status: string | undefined;
85 /** Provisioned memory in m-NCUs. */
86 provisionedMemory: number | undefined;
87 /** Whether the endpoint is reachable from the public internet. */
88 publicConnectivity: boolean | undefined;
89 /** Number of read replicas. */
90 replicaCount: number | undefined;
91 /** KMS key encrypting the graph, if customer-managed. */
92 kmsKeyIdentifier: string | undefined;
93 /** Vector search embedding dimension, if enabled. */
94 vectorSearchDimension: number | undefined;
95 /** Whether deletion protection is enabled. */
96 deletionProtection: boolean | undefined;
97 /** Creation time of the graph (ISO 8601). */
98 createTime: string | undefined;
99 /** Tags on the graph (user + internal Alchemy tags). */
100 tags: Record<string, string>;
101 },
102 never,
103 Providers
104 > {}
105
106 /**
107 * An Amazon Neptune Analytics graph — a serverless, memory-optimized graph
108 * that serves openCypher queries over an IAM-authenticated HTTPS endpoint.
109 * Unlike classic Neptune, a graph with `publicConnectivity: true` needs no
110 * VPC plumbing at all. Provisioning takes several minutes and the graph
111 * bills per m-NCU-hour while it exists.
112 *
113 * Mutable fields (`provisionedMemory`, `publicConnectivity`,
114 * `deletionProtection`) are reconciled in place; immutable fields
115 * (`replicaCount`, `kmsKeyIdentifier`, `vectorSearchConfiguration`) force a
116 * replacement.
117 * ### Creating a Graph
118 * **Example:** Publicly reachable analytics graph
119 * ```typescript
120 * const graph = yield* Graph("Knowledge", {
121 * provisionedMemory: 16,
122 * publicConnectivity: true,
123 * replicaCount: 0,
124 * deletionProtection: false,
125 * });
126 * ```
127 *
128 * ### Vector Search
129 * **Example:** Graph with vector search enabled
130 * ```typescript
131 * const graph = yield* Graph("Embeddings", {
132 * provisionedMemory: 16,
133 * vectorSearchConfiguration: { dimension: 1536 },
134 * });
135 * ```
136 *
137 * ### Querying
138 * **Example:** Query from a Lambda function via the ExecuteQuery binding
139 * ```typescript
140 * const executeQuery = yield* AWS.NeptuneGraph.ExecuteQuery(graph);
141 * const result = yield* executeQuery({
142 * queryString: "MATCH (n) RETURN count(n) AS n",
143 * language: "OPEN_CYPHER",
144 * });
145 * ```
146 *
147 * @resource
148 */
149 export const Graph = Resource<Graph>("AWS.NeptuneGraph.Graph");
150
151 type GraphOutput = neptunegraph.GetGraphOutput;
152
153 /**
154 * The graph entered the terminal `FAILED` state during provisioning or a
155 * modification. Not retried.
156 */
157 export class GraphProvisioningFailed extends Data.TaggedError("GraphProvisioningFailed")<{
158 readonly graphId: string;
159 readonly reason: string;
160 }> {}
161
162 class GraphNotReady extends Data.TaggedError("GraphNotReady")<{
163 readonly graphId: string;
164 readonly status: string;
165 }> {}
166
167 const toTagRecord = (
168 tags: { [key: string]: string | undefined } | undefined,
169 ): Record<string, string> =>
170 Object.fromEntries(
171 Object.entries(tags ?? {}).filter(
172 (entry): entry is [string, string] => typeof entry[1] === "string",
173 ),
174 );
175
176 const toAttrs = ({
177 graph,
178 tags,
179 }: {
180 graph: GraphOutput;
181 tags: Record<string, string>;
182 }): Graph["Attributes"] => ({
183 graphId: graph.id,
184 graphName: graph.name,
185 graphArn: graph.arn,
186 endpoint: graph.endpoint,
187 status: graph.status,
188 provisionedMemory: graph.provisionedMemory,
189 publicConnectivity: graph.publicConnectivity,
190 replicaCount: graph.replicaCount,
191 kmsKeyIdentifier: graph.kmsKeyIdentifier,
192 vectorSearchDimension: graph.vectorSearchConfiguration?.dimension,
193 deletionProtection: graph.deletionProtection,
194 createTime: graph.createTime?.toISOString(),
195 tags,
196 });
197
198 export const GraphProvider = () =>
199 Provider.effect(
200 Graph,
201 Effect.gen(function* () {
202 const toName = (id: string, props: GraphProps) =>
203 props.graphName
204 ? Effect.succeed(props.graphName)
205 : createPhysicalName({ id, maxLength: 63, lowercase: true });
206
207 const getGraph = Effect.fn(function* (graphId: string) {
208 return yield* neptunegraph
209 .getGraph({ graphIdentifier: graphId })
210 .pipe(Effect.catchTag("ResourceNotFoundException", () => Effect.undefined));
211 });
212
213 // Graph names are unique per account/region — resolve a graph by name
214 // when no id is cached (state-persistence failure recovery).
215 const findGraphByName = Effect.fn(function* (name: string) {
216 const summary = yield* neptunegraph.listGraphs.items({}).pipe(
217 Stream.filter((graph) => graph.name === name),
218 Stream.runHead,
219 Effect.map(Option.getOrUndefined),
220 );
221 if (summary === undefined) return undefined;
222 return yield* getGraph(summary.id);
223 });
224
225 const observeGraph = Effect.fn(function* (graphId: string | undefined, name: string) {
226 if (graphId !== undefined) {
227 const graph = yield* getGraph(graphId);
228 if (graph !== undefined) return graph;
229 }
230 return yield* findGraphByName(name);
231 });
232
233 const readTags = Effect.fn(function* (arn: string) {
234 const response = yield* neptunegraph
235 .listTagsForResource({ resourceArn: arn })
236 .pipe(Effect.catchTag("ResourceNotFoundException", () => Effect.undefined));
237 return toTagRecord(response?.tags);
238 });
239
240 // Explicitly-typed pipeable retry helper. Inlining `Effect.retry` in a
241 // provider lifecycle op leaks `Retry.Return`'s conditional into
242 // declaration emit and widens the provider layer to `unknown` R for
243 // every consumer of `AWS.providers()`.
244 const retryWhileGraphNotReady = <A, E extends { readonly _tag: string }, R>(
245 self: Effect.Effect<A, E, R>,
246 ): Effect.Effect<A, E, R> =>
247 Effect.retry(self, {
248 while: (e) => e._tag === "GraphNotReady",
249 schedule: Schedule.max([Schedule.fixed("10 seconds"), Schedule.recurs(90)]),
250 });
251
252 // Bounded readiness wait: graph creation/modification takes several
253 // minutes. Budgets ~15 min (90 * 10s). Fails fast on FAILED.
254 const waitForGraph = Effect.fn(function* (graphId: string) {
255 return yield* retryWhileGraphNotReady(
256 Effect.gen(function* () {
257 const graph = yield* getGraph(graphId);
258 if (graph === undefined) {
259 return yield* new GraphNotReady({ graphId, status: "missing" });
260 }
261 if (graph.status === "FAILED") {
262 return yield* new GraphProvisioningFailed({
263 graphId,
264 reason: graph.statusReason ?? "unknown",
265 });
266 }
267 if (graph.status !== "AVAILABLE") {
268 return yield* new GraphNotReady({
269 graphId,
270 status: graph.status ?? "unknown",
271 });
272 }
273 return graph;
274 }),
275 );
276 });
277
278 return {
279 stables: ["graphId", "graphArn", "graphName"],
280 // AWS account/region collection: enumerate every Neptune Analytics
281 // graph via the paginated `listGraphs`. Summaries omit create time,
282 // vector-search config, and tags — emit undefined/empty for those
283 // rather than a per-item `getGraph`/`listTagsForResource` fan-out.
284 list: () =>
285 neptunegraph.listGraphs.items({}).pipe(
286 Stream.runCollect,
287 Effect.map((chunk) =>
288 Array.from(chunk).map((graph) => ({
289 graphId: graph.id,
290 graphName: graph.name,
291 graphArn: graph.arn,
292 endpoint: graph.endpoint,
293 status: graph.status,
294 provisionedMemory: graph.provisionedMemory,
295 publicConnectivity: graph.publicConnectivity,
296 replicaCount: graph.replicaCount,
297 kmsKeyIdentifier: graph.kmsKeyIdentifier,
298 vectorSearchDimension: undefined,
299 deletionProtection: graph.deletionProtection,
300 createTime: undefined,
301 tags: {} as Record<string, string>,
302 })),
303 ),
304 ),
305 diff: Effect.fn(function* ({ id, olds, news }) {
306 if (!isResolved(news)) return undefined;
307 if ((yield* toName(id, olds ?? { provisionedMemory: 0 })) !== (yield* toName(id, news))) {
308 return { action: "replace" } as const;
309 }
310 // Immutable props — any change forces a fresh graph.
311 if (
312 olds !== undefined &&
313 (olds.replicaCount !== news.replicaCount ||
314 olds.kmsKeyIdentifier !== news.kmsKeyIdentifier ||
315 olds.vectorSearchConfiguration?.dimension !==
316 news.vectorSearchConfiguration?.dimension)
317 ) {
318 return { action: "replace" } as const;
319 }
320 }),
321 read: Effect.fn(function* ({ id, olds, output }) {
322 const name =
323 output?.graphName ??
324 (yield* toName(id, olds ?? ({ provisionedMemory: 0 } as GraphProps)));
325 const graph = yield* observeGraph(output?.graphId, name);
326 if (graph === undefined) {
327 return undefined;
328 }
329 const tags = yield* readTags(graph.arn);
330 return toAttrs({ graph, tags });
331 }),
332 reconcile: Effect.fn(function* ({ id, news, output, session }) {
333 const name = output?.graphName ?? (yield* toName(id, news));
334 const internalTags = yield* createInternalTags(id);
335 const desiredTags = { ...internalTags, ...news.tags };
336
337 // Observe — fetch live graph state (by cached id, else by name).
338 let observed = yield* observeGraph(output?.graphId, name);
339
340 // Ensure — create if missing. A ConflictException here means a
341 // peer reconciler won the create race — re-resolve by name.
342 if (observed === undefined) {
343 const created = yield* neptunegraph
344 .createGraph({
345 graphName: name,
346 provisionedMemory: news.provisionedMemory,
347 publicConnectivity: news.publicConnectivity,
348 replicaCount: news.replicaCount,
349 kmsKeyIdentifier: news.kmsKeyIdentifier,
350 vectorSearchConfiguration: news.vectorSearchConfiguration,
351 deletionProtection: news.deletionProtection,
352 tags: desiredTags,
353 })
354 .pipe(Effect.catchTag("ConflictException", () => Effect.undefined));
355 const graphId = created?.id ?? (yield* findGraphByName(name))?.id;
356 if (graphId === undefined) {
357 return yield* new NeptuneGraphGraphUnexpectedResponse({
358 message: `Failed to create graph '${name}'`,
359 });
360 }
361 observed = yield* waitForGraph(graphId);
362 } else {
363 // Wait for the graph to settle before any modify so the call
364 // doesn't hit ConflictException(CONCURRENT_MODIFICATION).
365 observed = yield* waitForGraph(observed.id);
366
367 // Sync — single `updateGraph` carrying only the in-place fields
368 // whose desired value differs from the observed cloud state.
369 const update: Omit<neptunegraph.UpdateGraphInput, "graphIdentifier"> = {};
370 let dirty = false;
371 if (
372 news.provisionedMemory !== undefined &&
373 news.provisionedMemory !== observed.provisionedMemory
374 ) {
375 update.provisionedMemory = news.provisionedMemory;
376 dirty = true;
377 }
378 if (
379 news.publicConnectivity !== undefined &&
380 news.publicConnectivity !== observed.publicConnectivity
381 ) {
382 update.publicConnectivity = news.publicConnectivity;
383 dirty = true;
384 }
385 if (
386 news.deletionProtection !== undefined &&
387 news.deletionProtection !== observed.deletionProtection
388 ) {
389 update.deletionProtection = news.deletionProtection;
390 dirty = true;
391 }
392 if (dirty) {
393 yield* neptunegraph.updateGraph({
394 graphIdentifier: observed.id,
395 ...update,
396 });
397 observed = yield* waitForGraph(observed.id);
398 }
399 }
400
401 // Sync tags — diff observed cloud tags against desired.
402 const observedTags = yield* readTags(observed.arn);
403 const { removed, upsert } = diffTags(observedTags, desiredTags);
404 if (upsert.length > 0) {
405 yield* neptunegraph.tagResource({
406 resourceArn: observed.arn,
407 tags: Object.fromEntries(upsert.map(({ Key, Value }) => [Key, Value])),
408 });
409 }
410 if (removed.length > 0) {
411 yield* neptunegraph.untagResource({
412 resourceArn: observed.arn,
413 tagKeys: removed,
414 });
415 }
416
417 yield* session.note(observed.arn);
418 return toAttrs({ graph: observed, tags: desiredTags });
419 }),
420 delete: Effect.fn(function* ({ output }) {
421 // Deletion is blocked while delete-protection is on — disable it
422 // first if the live graph still has it enabled.
423 const observed = yield* getGraph(output.graphId);
424 if (observed === undefined) return;
425 if (observed.deletionProtection === true) {
426 yield* neptunegraph
427 .updateGraph({
428 graphIdentifier: output.graphId,
429 deletionProtection: false,
430 })
431 .pipe(Effect.catchTag("ResourceNotFoundException", () => Effect.undefined));
432 }
433 yield* neptunegraph
434 .deleteGraph({
435 graphIdentifier: output.graphId,
436 skipSnapshot: true,
437 })
438 .pipe(Effect.catchTag("ResourceNotFoundException", () => Effect.undefined));
439 // Block until the graph is fully gone — deletion is async and the
440 // graph bills until it disappears.
441 yield* Effect.repeat(
442 neptunegraph.getGraph({ graphIdentifier: output.graphId }).pipe(
443 Effect.as(true),
444 Effect.catchTag("ResourceNotFoundException", () => Effect.succeed(false)),
445 ),
446 {
447 schedule: Schedule.max([Schedule.fixed("10 seconds"), Schedule.recurs(60)]),
448 until: (exists) => exists === false,
449 },
450 ).pipe(Effect.catch(() => Effect.void));
451 }),
452 };
453 }),
454 );