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

main
ts 368 lines 14.3 KB
Raw
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 );