The best way to control Claude Code, Codex and more from any computer or phone
| 1 | import * as neptune from "@distilled.cloud/aws/neptune"; |
| 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 Schedule from "effect/Schedule"; |
| 10 | import * as Stream from "effect/Stream"; |
| 11 | import type { Providers } from "../Providers.ts"; |
| 12 | |
| 13 | export class NeptuneDBClusterParameterGroupUnexpectedResponse extends Data.TaggedError( |
| 14 | "NeptuneDBClusterParameterGroupUnexpectedResponse", |
| 15 | )<{ |
| 16 | readonly message: string; |
| 17 | readonly cause?: unknown; |
| 18 | }> {} |
| 19 | |
| 20 | export interface DBClusterParameterGroupProps { |
| 21 | /** |
| 22 | * Name of the DB cluster parameter group. If omitted, a deterministic name |
| 23 | * is generated. Changing it forces replacement. |
| 24 | */ |
| 25 | dbClusterParameterGroupName?: string; |
| 26 | /** |
| 27 | * DB cluster parameter group family, e.g. `neptune1.4`, `neptune1.3`. |
| 28 | * Immutable — forces replacement. |
| 29 | */ |
| 30 | family: string; |
| 31 | /** |
| 32 | * Description for the parameter group. |
| 33 | * @default "Managed by Alchemy" |
| 34 | */ |
| 35 | description?: string; |
| 36 | /** |
| 37 | * Cluster parameter overrides, e.g. |
| 38 | * `{ neptune_query_timeout: "120000" }`. Parameters removed from this map |
| 39 | * are reset to their engine defaults. Static parameters are applied with |
| 40 | * `pending-reboot`, dynamic parameters with `immediate`. |
| 41 | */ |
| 42 | parameters?: Record<string, string>; |
| 43 | /** |
| 44 | * User-defined tags for the parameter group. |
| 45 | */ |
| 46 | tags?: Record<string, string>; |
| 47 | } |
| 48 | |
| 49 | export interface DBClusterParameterGroup extends Resource< |
| 50 | "AWS.Neptune.DBClusterParameterGroup", |
| 51 | DBClusterParameterGroupProps, |
| 52 | { |
| 53 | /** Name of the parameter group. */ |
| 54 | dbClusterParameterGroupName: string; |
| 55 | /** ARN of the parameter group. */ |
| 56 | dbClusterParameterGroupArn: string | undefined; |
| 57 | /** Parameter group family (e.g. `neptune1.4`). */ |
| 58 | family: string; |
| 59 | /** Description of the parameter group. */ |
| 60 | description: string | undefined; |
| 61 | /** Non-default parameter values applied to the group. */ |
| 62 | parameters: Record<string, string>; |
| 63 | /** Tags on the parameter group (user + internal Alchemy tags). */ |
| 64 | tags: Record<string, string>; |
| 65 | }, |
| 66 | never, |
| 67 | Providers |
| 68 | > {} |
| 69 | |
| 70 | /** |
| 71 | * An Amazon Neptune DB cluster parameter group — a named set of engine |
| 72 | * configuration parameters (query timeout, audit logging, ...) that can be |
| 73 | * attached to one or more Neptune {@link DBCluster}s. |
| 74 | * ### Creating a Parameter Group |
| 75 | * **Example:** Parameter group with a custom query timeout |
| 76 | * ```typescript |
| 77 | * const params = yield* DBClusterParameterGroup("Params", { |
| 78 | * family: "neptune1.4", |
| 79 | * parameters: { |
| 80 | * neptune_query_timeout: "120000", |
| 81 | * }, |
| 82 | * }); |
| 83 | * ``` |
| 84 | * |
| 85 | * ### Attaching to a Cluster |
| 86 | * **Example:** Cluster using the parameter group |
| 87 | * ```typescript |
| 88 | * const cluster = yield* DBCluster("Graph", { |
| 89 | * dbSubnetGroupName: subnetGroup.dbSubnetGroupName, |
| 90 | * dbClusterParameterGroupName: params.dbClusterParameterGroupName, |
| 91 | * }); |
| 92 | * ``` |
| 93 | * |
| 94 | * @resource |
| 95 | */ |
| 96 | export const DBClusterParameterGroup = Resource<DBClusterParameterGroup>( |
| 97 | "AWS.Neptune.DBClusterParameterGroup", |
| 98 | ); |
| 99 | |
| 100 | const toTagRecord = ( |
| 101 | tags: Array<{ Key?: string; Value?: string }> | undefined, |
| 102 | ): Record<string, string> => |
| 103 | Object.fromEntries( |
| 104 | (tags ?? []) |
| 105 | .filter( |
| 106 | (tag): tag is { Key: string; Value: string } => |
| 107 | typeof tag.Key === "string" && typeof tag.Value === "string", |
| 108 | ) |
| 109 | .map((tag) => [tag.Key, tag.Value]), |
| 110 | ); |
| 111 | |
| 112 | /** |
| 113 | * A parameter modify/reset issued immediately after another change fails with |
| 114 | * `InvalidDBParameterGroupStateFault` ("has pending changes") until the prior |
| 115 | * change settles — retry it on a short bounded schedule. |
| 116 | */ |
| 117 | const retryWhileParameterGroupBusy = <A, E extends { _tag: string }, R>( |
| 118 | self: Effect.Effect<A, E, R>, |
| 119 | ): Effect.Effect<A, E, R> => |
| 120 | Effect.retry(self, { |
| 121 | while: (e) => e._tag === "InvalidDBParameterGroupStateFault", |
| 122 | schedule: Schedule.max([Schedule.fixed("5 seconds"), Schedule.recurs(10)]), |
| 123 | }); |
| 124 | |
| 125 | export const DBClusterParameterGroupProvider = () => |
| 126 | Provider.effect( |
| 127 | DBClusterParameterGroup, |
| 128 | Effect.gen(function* () { |
| 129 | const toName = (id: string, props: DBClusterParameterGroupProps) => |
| 130 | props.dbClusterParameterGroupName |
| 131 | ? Effect.succeed(props.dbClusterParameterGroupName) |
| 132 | : createPhysicalName({ id, maxLength: 255 }); |
| 133 | |
| 134 | const readGroup = Effect.fn(function* (groupName: string) { |
| 135 | const response = yield* neptune |
| 136 | .describeDBClusterParameterGroups({ |
| 137 | DBClusterParameterGroupName: groupName, |
| 138 | }) |
| 139 | .pipe(Effect.catchTag("DBParameterGroupNotFoundFault", () => Effect.undefined)); |
| 140 | return response?.DBClusterParameterGroups?.[0]; |
| 141 | }); |
| 142 | |
| 143 | // All parameters (defaults + overrides) with their current values and |
| 144 | // apply types — the observed baseline for the parameter sync. |
| 145 | const readParameters = Effect.fn(function* (groupName: string) { |
| 146 | return yield* neptune.describeDBClusterParameters |
| 147 | .pages({ DBClusterParameterGroupName: groupName }) |
| 148 | .pipe( |
| 149 | Stream.runCollect, |
| 150 | Effect.map((chunk) => Array.from(chunk).flatMap((page) => page.Parameters ?? [])), |
| 151 | ); |
| 152 | }); |
| 153 | |
| 154 | // The subset of parameters the user has overridden (Source `user`) — |
| 155 | // used to compute resets when a prop entry is removed. |
| 156 | const readUserParameters = Effect.fn(function* (groupName: string) { |
| 157 | return yield* neptune.describeDBClusterParameters |
| 158 | .pages({ DBClusterParameterGroupName: groupName, Source: "user" }) |
| 159 | .pipe( |
| 160 | Stream.runCollect, |
| 161 | Effect.map((chunk) => Array.from(chunk).flatMap((page) => page.Parameters ?? [])), |
| 162 | ); |
| 163 | }); |
| 164 | |
| 165 | const readTags = Effect.fn(function* (arn: string | undefined) { |
| 166 | if (!arn) return {} as Record<string, string>; |
| 167 | const response = yield* neptune.listTagsForResource({ |
| 168 | ResourceName: arn, |
| 169 | }); |
| 170 | return toTagRecord(response?.TagList); |
| 171 | }); |
| 172 | |
| 173 | const toUserParameterRecord = (parameters: neptune.Parameter[]): Record<string, string> => |
| 174 | Object.fromEntries( |
| 175 | parameters.flatMap((p) => |
| 176 | p.ParameterName !== undefined && p.ParameterValue !== undefined |
| 177 | ? [[p.ParameterName, p.ParameterValue]] |
| 178 | : [], |
| 179 | ), |
| 180 | ); |
| 181 | |
| 182 | return { |
| 183 | stables: ["dbClusterParameterGroupArn", "dbClusterParameterGroupName", "family"], |
| 184 | diff: Effect.fn(function* ({ id, olds, news }) { |
| 185 | if (!isResolved(news)) return undefined; |
| 186 | if ((yield* toName(id, olds ?? { family: "" })) !== (yield* toName(id, news))) { |
| 187 | return { action: "replace" } as const; |
| 188 | } |
| 189 | // Family is immutable — any change forces a fresh group. |
| 190 | if (olds !== undefined && olds.family !== news.family) { |
| 191 | return { action: "replace" } as const; |
| 192 | } |
| 193 | }), |
| 194 | read: Effect.fn(function* ({ id, olds, output }) { |
| 195 | const name = |
| 196 | output?.dbClusterParameterGroupName ?? |
| 197 | (yield* toName(id, olds ?? ({ family: "" } as DBClusterParameterGroupProps))); |
| 198 | const group = yield* readGroup(name); |
| 199 | if (!group?.DBClusterParameterGroupName) { |
| 200 | return undefined; |
| 201 | } |
| 202 | const userParameters = yield* readUserParameters(name); |
| 203 | const tags = yield* readTags(group.DBClusterParameterGroupArn); |
| 204 | return { |
| 205 | dbClusterParameterGroupName: group.DBClusterParameterGroupName, |
| 206 | dbClusterParameterGroupArn: group.DBClusterParameterGroupArn, |
| 207 | family: group.DBParameterGroupFamily ?? "", |
| 208 | description: group.Description, |
| 209 | parameters: toUserParameterRecord(userParameters), |
| 210 | tags, |
| 211 | }; |
| 212 | }), |
| 213 | reconcile: Effect.fn(function* ({ id, news, output, session }) { |
| 214 | const name = output?.dbClusterParameterGroupName ?? (yield* toName(id, news)); |
| 215 | const internalTags = yield* createInternalTags(id); |
| 216 | const desiredTags = { ...internalTags, ...news.tags }; |
| 217 | |
| 218 | // Observe — fetch live parameter-group state. |
| 219 | let observed = yield* readGroup(name); |
| 220 | |
| 221 | // Ensure — create if missing. Tolerate |
| 222 | // `DBParameterGroupAlreadyExistsFault` as a race with a peer |
| 223 | // reconciler by re-reading. |
| 224 | if (!observed?.DBClusterParameterGroupName) { |
| 225 | yield* neptune |
| 226 | .createDBClusterParameterGroup({ |
| 227 | DBClusterParameterGroupName: name, |
| 228 | DBParameterGroupFamily: news.family, |
| 229 | Description: news.description ?? "Managed by Alchemy", |
| 230 | Tags: Object.entries(desiredTags).map(([Key, Value]) => ({ |
| 231 | Key, |
| 232 | Value, |
| 233 | })), |
| 234 | }) |
| 235 | .pipe(Effect.catchTag("DBParameterGroupAlreadyExistsFault", () => Effect.void)); |
| 236 | observed = yield* readGroup(name); |
| 237 | if (!observed?.DBClusterParameterGroupName) { |
| 238 | return yield* new NeptuneDBClusterParameterGroupUnexpectedResponse({ |
| 239 | message: `Failed to create DB cluster parameter group '${name}'`, |
| 240 | }); |
| 241 | } |
| 242 | } |
| 243 | |
| 244 | // Sync parameters — diff observed cloud values against desired. |
| 245 | const desiredParameters = news.parameters ?? {}; |
| 246 | const allParameters = yield* readParameters(name); |
| 247 | const byName = new Map(allParameters.map((p) => [p.ParameterName, p])); |
| 248 | |
| 249 | const toModify: neptune.Parameter[] = Object.entries(desiredParameters).flatMap( |
| 250 | ([ParameterName, ParameterValue]) => { |
| 251 | const current = byName.get(ParameterName); |
| 252 | if (current?.ParameterValue === ParameterValue) return []; |
| 253 | return [ |
| 254 | { |
| 255 | ParameterName, |
| 256 | ParameterValue, |
| 257 | ApplyMethod: current?.ApplyType === "static" ? "pending-reboot" : "immediate", |
| 258 | }, |
| 259 | ]; |
| 260 | }, |
| 261 | ); |
| 262 | if (toModify.length > 0) { |
| 263 | // The API caps a single call at 20 parameters. |
| 264 | for (let i = 0; i < toModify.length; i += 20) { |
| 265 | yield* retryWhileParameterGroupBusy( |
| 266 | neptune.modifyDBClusterParameterGroup({ |
| 267 | DBClusterParameterGroupName: name, |
| 268 | Parameters: toModify.slice(i, i + 20), |
| 269 | }), |
| 270 | ); |
| 271 | } |
| 272 | } |
| 273 | |
| 274 | // Reset user-overridden parameters that were removed from props. |
| 275 | const userParameters = yield* readUserParameters(name); |
| 276 | const toReset = userParameters.flatMap((p) => |
| 277 | p.ParameterName !== undefined && !(p.ParameterName in desiredParameters) |
| 278 | ? [ |
| 279 | { |
| 280 | ParameterName: p.ParameterName, |
| 281 | ApplyMethod: |
| 282 | p.ApplyType === "static" |
| 283 | ? ("pending-reboot" as const) |
| 284 | : ("immediate" as const), |
| 285 | }, |
| 286 | ] |
| 287 | : [], |
| 288 | ); |
| 289 | if (toReset.length > 0) { |
| 290 | for (let i = 0; i < toReset.length; i += 20) { |
| 291 | yield* retryWhileParameterGroupBusy( |
| 292 | neptune.resetDBClusterParameterGroup({ |
| 293 | DBClusterParameterGroupName: name, |
| 294 | ResetAllParameters: false, |
| 295 | Parameters: toReset.slice(i, i + 20), |
| 296 | }), |
| 297 | ); |
| 298 | } |
| 299 | } |
| 300 | |
| 301 | const arn = observed.DBClusterParameterGroupArn; |
| 302 | |
| 303 | // Sync tags — diff observed cloud tags against desired. |
| 304 | const observedTags = yield* readTags(arn); |
| 305 | const { removed, upsert } = diffTags(observedTags, desiredTags); |
| 306 | if (upsert.length > 0 && arn) { |
| 307 | yield* neptune.addTagsToResource({ |
| 308 | ResourceName: arn, |
| 309 | Tags: upsert, |
| 310 | }); |
| 311 | } |
| 312 | if (removed.length > 0 && arn) { |
| 313 | yield* neptune.removeTagsFromResource({ |
| 314 | ResourceName: arn, |
| 315 | TagKeys: removed, |
| 316 | }); |
| 317 | } |
| 318 | |
| 319 | yield* session.note(arn ?? name); |
| 320 | return { |
| 321 | dbClusterParameterGroupName: observed.DBClusterParameterGroupName, |
| 322 | dbClusterParameterGroupArn: arn, |
| 323 | family: observed.DBParameterGroupFamily ?? news.family, |
| 324 | description: observed.Description, |
| 325 | parameters: desiredParameters, |
| 326 | tags: desiredTags, |
| 327 | }; |
| 328 | }), |
| 329 | list: () => |
| 330 | // AWS account/region collection: the RDS-family control plane |
| 331 | // serves parameter groups for every engine, so keep only families |
| 332 | // beginning with `neptune`. Hydrating per-group parameters/tags |
| 333 | // would fan out one call per item — mirror `DBSubnetGroup.list` and |
| 334 | // emit empty maps instead. |
| 335 | neptune.describeDBClusterParameterGroups.pages({}).pipe( |
| 336 | Stream.runCollect, |
| 337 | Effect.map((chunk) => |
| 338 | Array.from(chunk).flatMap((page) => |
| 339 | (page.DBClusterParameterGroups ?? []).flatMap((group) => |
| 340 | group.DBClusterParameterGroupName && |
| 341 | // `default.<family>` groups are AWS-managed and undeletable. |
| 342 | !group.DBClusterParameterGroupName.startsWith("default.") && |
| 343 | group.DBParameterGroupFamily?.startsWith("neptune") |
| 344 | ? [ |
| 345 | { |
| 346 | dbClusterParameterGroupName: group.DBClusterParameterGroupName, |
| 347 | dbClusterParameterGroupArn: group.DBClusterParameterGroupArn, |
| 348 | family: group.DBParameterGroupFamily, |
| 349 | description: group.Description, |
| 350 | parameters: {} as Record<string, string>, |
| 351 | tags: {} as Record<string, string>, |
| 352 | }, |
| 353 | ] |
| 354 | : [], |
| 355 | ), |
| 356 | ), |
| 357 | ), |
| 358 | ), |
| 359 | delete: Effect.fn(function* ({ output }) { |
| 360 | yield* neptune |
| 361 | .deleteDBClusterParameterGroup({ |
| 362 | DBClusterParameterGroupName: output.dbClusterParameterGroupName, |
| 363 | }) |
| 364 | .pipe(Effect.catchTag("DBParameterGroupNotFoundFault", () => Effect.void)); |
| 365 | }), |
| 366 | }; |
| 367 | }), |
| 368 | ); |