The best way to control Claude Code, Codex and more from any computer or phone
| 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 | ); |