@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, 04:45 UTC

main
ts 542 lines 19.8 KB
Raw
1 import * as logs from "@distilled.cloud/aws/cloudwatch-logs";
2 import * as ec2 from "@distilled.cloud/aws/ec2";
3 import * as obs from "@distilled.cloud/aws/observabilityadmin";
4 import { Unowned } from "alchemy/AdoptPolicy";
5 import { isResolved } from "alchemy/Diff";
6 import { createPhysicalName } from "alchemy/PhysicalName";
7 import * as Provider from "alchemy/Provider";
8 import { Resource } from "alchemy/Resource";
9 import { createInternalTags, diffTags, hasAlchemyTags } from "alchemy/Tags";
10 import { toWireDays } from "alchemy/Util/Duration";
11 import * as Data from "effect/Data";
12 import type * as Duration from "effect/Duration";
13 import * as Effect from "effect/Effect";
14 import * as Schedule from "effect/Schedule";
15 import * as Stream from "effect/Stream";
16 import type { Providers } from "../Providers.ts";
17
18 export class TelemetryRuleNotReady extends Data.TaggedError("TelemetryRuleNotReady")<{
19 readonly message: string;
20 readonly cause?: unknown;
21 }> {}
22
23 /**
24 * Where a telemetry rule delivers the telemetry it enables. Mirrors the wire
25 * `TelemetryDestinationConfiguration`, with the retention period expressed as
26 * a `Duration.Input` instead of the wire's `RetentionInDays`.
27 */
28 export interface TelemetryRuleDestination extends Omit<
29 obs.TelemetryDestinationConfiguration,
30 "RetentionInDays"
31 > {
32 /**
33 * How long CloudWatch Logs retains the telemetry delivered by this rule.
34 * Accepts any `Duration.Input` (e.g. `"30 days"`, `Duration.days(90)`);
35 * converted to whole days on the wire (`RetentionInDays`).
36 */
37 Retention?: Duration.Input;
38 }
39
40 export interface TelemetryRuleProps {
41 /**
42 * Name of the telemetry rule. If omitted, a deterministic physical name is
43 * generated. Changing the name replaces the rule.
44 */
45 ruleName?: string;
46 /**
47 * The type of telemetry the rule enables — `"Logs"`, `"Metrics"`, or
48 * `"Traces"`.
49 */
50 telemetryType: obs.TelemetryType;
51 /**
52 * The AWS resource type the rule applies to, e.g. `"AWS::EC2::VPC"`.
53 */
54 resourceType?: obs.ResourceType;
55 /**
56 * The telemetry sources the rule enables, e.g. `["VPC_FLOW_LOGS"]`.
57 */
58 telemetrySourceTypes?: obs.TelemetrySourceType[];
59 /**
60 * Where the enabled telemetry is delivered (destination type, pattern,
61 * retention, and per-source parameters such as VPC flow-log format).
62 */
63 destinationConfiguration?: TelemetryRuleDestination;
64 /**
65 * Organization-level scope selector (organization rules only).
66 */
67 scope?: string;
68 /**
69 * Criteria selecting which resources the rule configures (such as
70 * resource tags). The expression format is service-defined (the console's
71 * tag filter builder produces it); an invalid expression is rejected with
72 * `ValidationException: Invalid resource selection criteria`. Without
73 * selection criteria the rule applies to every resource of `resourceType`
74 * in the account.
75 */
76 selectionCriteria?: string;
77 /**
78 * Whether the rule's telemetry parameters may be updated after creation.
79 */
80 allowFieldUpdates?: boolean;
81 /**
82 * Regions the rule applies to. Mutually exclusive with `allRegions`.
83 */
84 regions?: string[];
85 /**
86 * Apply the rule in all regions. Mutually exclusive with `regions`.
87 */
88 allRegions?: boolean;
89 /**
90 * User-defined tags for the rule.
91 */
92 tags?: Record<string, string>;
93 }
94
95 export interface TelemetryRule extends Resource<
96 "AWS.ObservabilityAdmin.TelemetryRule",
97 TelemetryRuleProps,
98 {
99 /** The name of the telemetry rule. */
100 ruleName: string;
101 /** The ARN of the telemetry rule. */
102 ruleArn: string;
103 /** The telemetry type the rule enables. */
104 telemetryType: string | undefined;
105 /** The resource type the rule applies to. */
106 resourceType: string | undefined;
107 /** The tags applied to the rule. */
108 tags: Record<string, string>;
109 },
110 never,
111 Providers
112 > {}
113
114 /**
115 * A CloudWatch **telemetry rule** (Observability Admin) — automatically
116 * enables telemetry (such as VPC flow logs) for AWS resources in your
117 * account that match the rule's criteria.
118 *
119 * The account must be onboarded to CloudWatch telemetry config (see
120 * `ObservabilityAdmin.TelemetryConfig`) before rules can be created.
121 *
122 * ### Creating a Telemetry Rule
123 * **Example:** Enable VPC flow logs for the account's VPCs
124 * ```typescript
125 * import * as ObservabilityAdmin from "@alchemy.run/aws/ObservabilityAdmin";
126 *
127 * // Onboard the account to telemetry config first.
128 * const telemetry = yield* ObservabilityAdmin.TelemetryConfig("Telemetry");
129 *
130 * const rule = yield* ObservabilityAdmin.TelemetryRule("FlowLogs", {
131 * resourceType: "AWS::EC2::VPC",
132 * telemetryType: "Logs",
133 * telemetrySourceTypes: ["VPC_FLOW_LOGS"],
134 * destinationConfiguration: {
135 * DestinationType: "cloud-watch-logs",
136 * Retention: "30 days",
137 * },
138 * });
139 * ```
140 *
141 * **Example:** Custom flow-log parameters
142 * ```typescript
143 * const rule = yield* ObservabilityAdmin.TelemetryRule("FlowLogs", {
144 * resourceType: "AWS::EC2::VPC",
145 * telemetryType: "Logs",
146 * telemetrySourceTypes: ["VPC_FLOW_LOGS"],
147 * destinationConfiguration: {
148 * DestinationType: "cloud-watch-logs",
149 * Retention: "90 days",
150 * VPCFlowLogParameters: {
151 * TrafficType: "REJECT",
152 * MaxAggregationInterval: 600,
153 * },
154 * },
155 * });
156 * ```
157 *
158 * @resource
159 */
160 export const TelemetryRule = Resource<TelemetryRule>("AWS.ObservabilityAdmin.TelemetryRule");
161
162 /** Normalize the wire tag map (values may be undefined) to a plain record. */
163 const toTagRecord = (
164 tags: { [key: string]: string | undefined } | undefined,
165 ): Record<string, string> =>
166 Object.fromEntries(
167 Object.entries(tags ?? {}).filter((entry): entry is [string, string] => entry[1] !== undefined),
168 );
169
170 const sameJson = (a: unknown, b: unknown): boolean => JSON.stringify(a) === JSON.stringify(b);
171
172 /**
173 * True when any field the desired rule declares differs from the observed
174 * rule. Fields the desired rule leaves unset are don't-cares (AWS echoes
175 * service defaults for them).
176 */
177 const ruleNeedsUpdate = (
178 desired: obs.TelemetryRule,
179 observed: obs.TelemetryRule | undefined,
180 ): boolean => {
181 if (observed === undefined) return true;
182 const observedByKey = new Map<string, unknown>(Object.entries(observed));
183 return Object.entries(desired).some(([key, value]) => !sameJson(value, observedByKey.get(key)));
184 };
185
186 const vpcFlowLogGroupName = "/aws/vpc";
187
188 const isVpcFlowLogRule = (rule: obs.TelemetryRule | undefined): boolean =>
189 rule?.ResourceType === "AWS::EC2::VPC" &&
190 rule.TelemetryType === "Logs" &&
191 rule.TelemetrySourceTypes?.includes("VPC_FLOW_LOGS") === true &&
192 rule.DestinationConfiguration?.DestinationType === "cloud-watch-logs";
193
194 const isManagedVpcFlowLog = (
195 flowLog: ec2.FlowLog,
196 ): flowLog is ec2.FlowLog & { FlowLogId: string } =>
197 flowLog.FlowLogId !== undefined &&
198 flowLog.ResourceId?.startsWith("vpc-") === true &&
199 flowLog.LogGroupName === vpcFlowLogGroupName &&
200 flowLog.LogDestinationType === "cloud-watch-logs" &&
201 flowLog.Tags?.some(
202 (tag) => tag.Key === "CloudWatchTelemetryRuleManaged" && tag.Value === "true",
203 ) === true;
204
205 class TelemetryRuleStillExists extends Data.TaggedError("TelemetryRuleStillExists")<{
206 readonly ruleName: string;
207 }> {}
208
209 class ManagedVpcFlowLogDeleteFailed extends Data.TaggedError("ManagedVpcFlowLogDeleteFailed")<{
210 readonly failures: ec2.UnsuccessfulItem[];
211 }> {}
212
213 class ManagedVpcFlowLogsStillExist extends Data.TaggedError("ManagedVpcFlowLogsStillExist")<{
214 readonly flowLogIds: string[];
215 }> {}
216
217 class ManagedVpcLogGroupStillExists extends Data.TaggedError("ManagedVpcLogGroupStillExists")<{
218 readonly logGroupName: string;
219 }> {}
220
221 const cleanupObservationSchedule = Schedule.max([Schedule.fixed("1 second"), Schedule.recurs(10)]);
222
223 /** Project props to the wire `TelemetryRule` struct (dropping undefineds). */
224 const toWireRule = (props: TelemetryRuleProps): obs.TelemetryRule =>
225 JSON.parse(
226 JSON.stringify({
227 ResourceType: props.resourceType,
228 TelemetryType: props.telemetryType,
229 TelemetrySourceTypes: props.telemetrySourceTypes,
230 DestinationConfiguration:
231 props.destinationConfiguration === undefined
232 ? undefined
233 : (() => {
234 const { Retention, ...rest } = props.destinationConfiguration;
235 return {
236 ...rest,
237 RetentionInDays: toWireDays(Retention),
238 };
239 })(),
240 Scope: props.scope,
241 SelectionCriteria: props.selectionCriteria,
242 AllowFieldUpdates: props.allowFieldUpdates,
243 Regions: props.regions,
244 AllRegions: props.allRegions,
245 }),
246 );
247
248 export const TelemetryRuleProvider = () =>
249 Provider.effect(
250 TelemetryRule,
251 Effect.gen(function* () {
252 const createName = Effect.fn(function* (id: string, props: TelemetryRuleProps) {
253 return props.ruleName ?? (yield* createPhysicalName({ id }));
254 });
255
256 const readRule = Effect.fn(function* (identifier: string) {
257 return yield* obs
258 .getTelemetryRule({ RuleIdentifier: identifier })
259 .pipe(Effect.catchTag("ResourceNotFoundException", () => Effect.undefined));
260 });
261
262 const waitUntilRuleAbsent = Effect.fn(function* (ruleName: string) {
263 yield* readRule(ruleName).pipe(
264 Effect.flatMap((rule) =>
265 rule === undefined
266 ? Effect.void
267 : Effect.fail(new TelemetryRuleStillExists({ ruleName })),
268 ),
269 Effect.retry({
270 while: (error) => error._tag === "TelemetryRuleStillExists",
271 schedule: cleanupObservationSchedule,
272 }),
273 );
274 });
275
276 const matchingRulesRemain = Effect.fn(function* () {
277 const summaries = yield* obs.listTelemetryRules.items({}).pipe(
278 Stream.runCollect,
279 Effect.map((items) => Array.from(items)),
280 );
281 const rules = yield* Effect.forEach(
282 summaries.flatMap((summary) =>
283 summary.RuleName === undefined ? [] : [summary.RuleName],
284 ),
285 readRule,
286 { concurrency: 4 },
287 );
288 return rules.some((rule) => isVpcFlowLogRule(rule?.TelemetryRule));
289 });
290
291 const listManagedVpcFlowLogs = () =>
292 ec2.describeFlowLogs
293 .items({
294 Filter: [
295 {
296 Name: "tag:CloudWatchTelemetryRuleManaged",
297 Values: ["true"],
298 },
299 { Name: "log-group-name", Values: [vpcFlowLogGroupName] },
300 ],
301 })
302 .pipe(
303 Stream.runCollect,
304 Effect.map((items) => Array.from(items).filter(isManagedVpcFlowLog)),
305 );
306
307 const waitUntilManagedFlowLogsAbsent = Effect.fn(function* (deletedIds: string[]) {
308 const deleted = new Set(deletedIds);
309 yield* listManagedVpcFlowLogs().pipe(
310 Effect.flatMap((flowLogs) => {
311 const remaining = flowLogs
312 .map((flowLog) => flowLog.FlowLogId)
313 .filter((flowLogId) => deleted.has(flowLogId));
314 return remaining.length === 0
315 ? Effect.void
316 : Effect.fail(
317 new ManagedVpcFlowLogsStillExist({
318 flowLogIds: remaining,
319 }),
320 );
321 }),
322 Effect.retry({
323 while: (error) => error._tag === "ManagedVpcFlowLogsStillExist",
324 schedule: cleanupObservationSchedule,
325 }),
326 );
327 });
328
329 const waitUntilVpcLogGroupAbsent = logs
330 .describeLogGroups({
331 logGroupNamePrefix: vpcFlowLogGroupName,
332 limit: 1,
333 })
334 .pipe(
335 Effect.flatMap((response) =>
336 response.logGroups?.some((group) => group.logGroupName === vpcFlowLogGroupName) === true
337 ? Effect.fail(
338 new ManagedVpcLogGroupStillExists({
339 logGroupName: vpcFlowLogGroupName,
340 }),
341 )
342 : Effect.void,
343 ),
344 Effect.retry({
345 while: (error) => error._tag === "ManagedVpcLogGroupStillExists",
346 schedule: cleanupObservationSchedule,
347 }),
348 );
349
350 const cleanupManagedVpcFlowLogs = Effect.fn(function* () {
351 const managed = yield* listManagedVpcFlowLogs();
352 const flowLogIds = managed.map((flowLog) => flowLog.FlowLogId);
353 if (flowLogIds.length > 0) {
354 yield* ec2.deleteFlowLogs({ FlowLogIds: flowLogIds }).pipe(
355 Effect.flatMap((response) => {
356 const failures = (response.Unsuccessful ?? []).filter(
357 (failure) => failure.Error?.Code !== "InvalidFlowLogId.NotFound",
358 );
359 return failures.length === 0
360 ? Effect.void
361 : Effect.fail(new ManagedVpcFlowLogDeleteFailed({ failures }));
362 }),
363 Effect.retry({
364 while: (error) => error._tag === "ManagedVpcFlowLogDeleteFailed",
365 schedule: cleanupObservationSchedule,
366 }),
367 );
368 yield* waitUntilManagedFlowLogsAbsent(flowLogIds);
369 }
370
371 // `/aws/vpc` is shared by all Observability Admin-managed VPC flow
372 // logs. Delete it only after no flow log of any ownership still uses
373 // the destination; otherwise deleting the group would destroy user
374 // logs or another rule's delivery target.
375 const groupConsumers = yield* ec2.describeFlowLogs
376 .items({
377 Filter: [{ Name: "log-group-name", Values: [vpcFlowLogGroupName] }],
378 })
379 .pipe(Stream.runCollect);
380 if (groupConsumers.length > 0) return;
381
382 yield* logs.deleteLogGroup({ logGroupName: vpcFlowLogGroupName }).pipe(
383 Effect.retry({
384 while: (error) =>
385 error._tag === "OperationAbortedException" ||
386 error._tag === "ServiceUnavailableException",
387 schedule: cleanupObservationSchedule,
388 }),
389 Effect.catchTag("ResourceNotFoundException", () => Effect.void),
390 );
391 yield* waitUntilVpcLogGroupAbsent;
392 });
393
394 const readTags = Effect.fn(function* (ruleArn: string) {
395 return yield* obs.listTagsForResource({ ResourceARN: ruleArn }).pipe(
396 Effect.map((r) => toTagRecord(r.Tags)),
397 Effect.catchTag("ResourceNotFoundException", () =>
398 Effect.succeed({} as Record<string, string>),
399 ),
400 );
401 });
402
403 const toAttrs = (rule: obs.GetTelemetryRuleOutput, tags: Record<string, string>) => ({
404 ruleName: rule.RuleName ?? "",
405 ruleArn: rule.RuleArn ?? "",
406 telemetryType: rule.TelemetryRule?.TelemetryType,
407 resourceType: rule.TelemetryRule?.ResourceType,
408 tags,
409 });
410
411 const readAttrs = Effect.fn(function* (identifier: string) {
412 const rule = yield* readRule(identifier);
413 if (rule === undefined || rule.RuleArn === undefined) return undefined;
414 const tags = yield* readTags(rule.RuleArn);
415 return toAttrs(rule, tags);
416 });
417
418 return TelemetryRule.Provider.of({
419 stables: ["ruleName", "ruleArn"],
420
421 list: () =>
422 obs.listTelemetryRules.items({}).pipe(
423 Stream.runCollect,
424 Effect.flatMap((summaries) =>
425 Effect.forEach(
426 Array.from(summaries).flatMap((s) =>
427 s.RuleName === undefined ? [] : [s.RuleName],
428 ),
429 (name) => readAttrs(name),
430 { concurrency: 4 },
431 ),
432 ),
433 Effect.map((attrs) => attrs.flatMap((a) => (a === undefined ? [] : [a]))),
434 ),
435
436 read: Effect.fn(function* ({ id, olds, output }) {
437 const name = output?.ruleName ?? (yield* createName(id, olds ?? {}));
438 const attrs = yield* readAttrs(name);
439 if (attrs === undefined) return undefined;
440 return (yield* hasAlchemyTags(id, attrs.tags)) ? attrs : Unowned(attrs);
441 }),
442
443 diff: Effect.fn(function* ({ id, news, olds }) {
444 if (!isResolved(news)) return undefined;
445 // The name is the only immutable property; the rule configuration
446 // is updatable in place via UpdateTelemetryRule.
447 if ((yield* createName(id, olds)) !== (yield* createName(id, news))) {
448 return { action: "replace" } as const;
449 }
450 return undefined;
451 }),
452
453 reconcile: Effect.fn(function* ({ id, news, output, session }) {
454 const props = news!;
455 const name = output?.ruleName ?? (yield* createName(id, props));
456 const internalTags = yield* createInternalTags(id);
457 const desiredTags = { ...props.tags, ...internalTags };
458 const desiredRule = toWireRule(props);
459
460 // 1. Observe — cloud state is authoritative.
461 let observed = yield* readRule(name);
462
463 // 2. Ensure — create if missing; a ConflictException means a peer
464 // created the same-named rule concurrently, so re-observe.
465 if (observed === undefined) {
466 yield* obs
467 .createTelemetryRule({
468 RuleName: name,
469 Rule: desiredRule,
470 Tags: desiredTags,
471 })
472 .pipe(Effect.catchTag("ConflictException", () => Effect.void));
473 // The read-after-create is eventually consistent; wait (bounded)
474 // for the rule to materialize.
475 observed = yield* readRule(name).pipe(
476 Effect.flatMap((rule) =>
477 rule === undefined
478 ? Effect.fail(
479 new TelemetryRuleNotReady({
480 message: `telemetry rule '${name}' not yet visible`,
481 }),
482 )
483 : Effect.succeed(rule),
484 ),
485 Effect.retry({
486 schedule: Schedule.max([Schedule.fixed("2 seconds"), Schedule.recurs(8)]),
487 }),
488 );
489 } else if (ruleNeedsUpdate(desiredRule, observed.TelemetryRule)) {
490 // 3. Sync — UpdateTelemetryRule replaces the whole rule config;
491 // apply only on an actual delta against OBSERVED state.
492 yield* obs.updateTelemetryRule({
493 RuleIdentifier: name,
494 Rule: desiredRule,
495 });
496 observed = (yield* readRule(name)) ?? observed;
497 }
498
499 // 3b. Sync tags — diff against OBSERVED cloud tags.
500 const ruleArn = observed.RuleArn!;
501 const observedTags = yield* readTags(ruleArn);
502 const { removed, upsert } = diffTags(observedTags, desiredTags);
503 if (upsert.length > 0) {
504 yield* obs.tagResource({
505 ResourceARN: ruleArn,
506 Tags: Object.fromEntries(upsert.map((t) => [t.Key, t.Value])),
507 });
508 }
509 if (removed.length > 0) {
510 yield* obs.untagResource({
511 ResourceARN: ruleArn,
512 TagKeys: removed,
513 });
514 }
515
516 yield* session.note(name);
517 const tags = yield* readTags(ruleArn);
518 return toAttrs(observed, tags);
519 }),
520
521 delete: Effect.fn(function* ({ output, olds }) {
522 // Capture the live rule before deleting it so adoption and drift do
523 // not make cleanup decisions from stale desired state.
524 const observed = yield* readRule(output.ruleName);
525 const deletedRule =
526 observed?.TelemetryRule ?? (olds === undefined ? undefined : toWireRule(olds));
527 yield* obs
528 .deleteTelemetryRule({ RuleIdentifier: output.ruleName })
529 .pipe(Effect.catchTag("ResourceNotFoundException", () => Effect.void));
530 yield* waitUntilRuleAbsent(output.ruleName);
531
532 // Observability Admin asynchronously creates EC2 flow logs and the
533 // shared `/aws/vpc` destination for VPC_FLOW_LOGS rules, but deleting
534 // the rule does not remove them. Reap only when this was such a rule
535 // and no other live rule can own the shared managed resources.
536 if (isVpcFlowLogRule(deletedRule) && !(yield* matchingRulesRemain())) {
537 yield* cleanupManagedVpcFlowLogs();
538 }
539 }),
540 });
541 }),
542 );