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

main
ts 369 lines 13 KB
Raw
1 import * as appsignals from "@distilled.cloud/aws/application-signals";
2 import { Unowned } from "alchemy/AdoptPolicy";
3 import { isResolved } from "alchemy/Diff";
4 import * as Provider from "alchemy/Provider";
5 import { Resource } from "alchemy/Resource";
6 import { createInternalTags, createTagsList, diffTags, hasAlchemyTags } from "alchemy/Tags";
7 import * as Data from "effect/Data";
8 import * as Effect from "effect/Effect";
9 import type { Providers } from "../Providers.ts";
10
11 export class InstrumentationConfigurationUnexpectedResponse extends Data.TaggedError(
12 "InstrumentationConfigurationUnexpectedResponse",
13 )<{
14 readonly message: string;
15 readonly cause?: unknown;
16 }> {}
17
18 export interface InstrumentationConfigurationProps {
19 /**
20 * The kind of dynamic instrumentation: `PROBE` or `BREAKPOINT`.
21 * Configurations are immutable — changing the type replaces the
22 * configuration.
23 */
24 instrumentationType: appsignals.InstrumentationType;
25 /**
26 * Name of the Application Signals service the instrumented code belongs
27 * to. Changing it replaces the configuration.
28 */
29 service: string;
30 /**
31 * The service's environment (e.g. `eks:prod`, `lambda:default`).
32 * Changing it replaces the configuration.
33 */
34 environment: string;
35 /**
36 * The signal produced by the instrumentation (currently `SNAPSHOT`).
37 * Changing it replaces the configuration.
38 */
39 signalType: appsignals.DynamicInstrumentationSignalType;
40 /**
41 * The code location to instrument (`Language`, `FilePath`, and — as the
42 * language requires — `CodeUnit`, `ClassName`, `MethodName`,
43 * `LineNumber`). Changing the location replaces the configuration.
44 */
45 location: appsignals.CodeLocation;
46 /**
47 * What the instrumentation captures at the location: arguments, return
48 * value, stack trace, locals, and the mandatory `CaptureLimits`.
49 * Configurations are immutable — changing this replaces it.
50 */
51 captureConfiguration: appsignals.CodeCaptureConfiguration;
52 /**
53 * A human-readable description of the configuration.
54 */
55 description?: string;
56 /**
57 * When the configuration expires and stops instrumenting. Accepts a
58 * `Date` or an ISO timestamp string.
59 */
60 expiresAt?: Date | string;
61 /**
62 * Attribute filter groups — the instrumentation only fires when a
63 * request matches all attributes within one of the groups.
64 */
65 attributeFilters?: { [key: string]: string | undefined }[];
66 /**
67 * Tags to apply to the configuration. Merged with internal Alchemy tags.
68 */
69 tags?: Record<string, string>;
70 }
71
72 export interface InstrumentationConfiguration extends Resource<
73 "AWS.ApplicationSignals.InstrumentationConfiguration",
74 InstrumentationConfigurationProps,
75 {
76 /**
77 * ARN of the instrumentation configuration.
78 */
79 arn: string;
80 /**
81 * Server-computed hash uniquely identifying the instrumented location
82 * within the service/environment/type/signal scope.
83 */
84 locationHash: string;
85 /**
86 * The instrumentation type (`PROBE` or `BREAKPOINT`).
87 */
88 instrumentationType: appsignals.InstrumentationType;
89 /**
90 * The Application Signals service the configuration belongs to.
91 */
92 service: string;
93 /**
94 * The service environment the configuration belongs to.
95 */
96 environment: string;
97 /**
98 * The signal type produced by the instrumentation.
99 */
100 signalType: appsignals.DynamicInstrumentationSignalType;
101 /**
102 * When the configuration was created (ISO timestamp).
103 */
104 createdAt: string;
105 },
106 never,
107 Providers
108 > {}
109
110 /**
111 * A CloudWatch Application Signals dynamic instrumentation configuration —
112 * instructs instrumented SDK agents to capture a snapshot (arguments,
113 * locals, return value, stack trace) at a specific code location of a
114 * discovered service, without redeploying the application.
115 *
116 * Configurations are immutable after creation: every change except tags
117 * replaces the configuration. Tags remain mutable through the standard
118 * tagging APIs.
119 *
120 * ### Creating an Instrumentation Configuration
121 * **Example:** Snapshot Probe on a Python Method
122 * ```typescript
123 * import * as AWS from "@alchemy.run/aws";
124 *
125 * const probe = yield* AWS.ApplicationSignals.InstrumentationConfiguration(
126 * "CheckoutProbe",
127 * {
128 * instrumentationType: "PROBE",
129 * service: "checkout-service",
130 * environment: "eks:prod",
131 * signalType: "SNAPSHOT",
132 * location: {
133 * Language: "Python",
134 * CodeUnit: "app.checkout",
135 * MethodName: "process_order",
136 * FilePath: "app/checkout.py",
137 * LineNumber: 42,
138 * },
139 * captureConfiguration: {
140 * CaptureLocals: ["order_id", "total"],
141 * CaptureLimits: { MaxHits: 100 },
142 * },
143 * },
144 * );
145 * ```
146 *
147 * **Example:** Expiring Probe with Attribute Filters
148 * ```typescript
149 * const probe = yield* AWS.ApplicationSignals.InstrumentationConfiguration(
150 * "DebugProbe",
151 * {
152 * instrumentationType: "PROBE",
153 * service: "checkout-service",
154 * environment: "eks:prod",
155 * signalType: "SNAPSHOT",
156 * location: {
157 * Language: "Java",
158 * ClassName: "com.example.Checkout",
159 * MethodName: "processOrder",
160 * FilePath: "src/main/java/com/example/Checkout.java",
161 * },
162 * captureConfiguration: {
163 * CaptureArguments: ["order"],
164 * CaptureLimits: { MaxHits: 10 },
165 * },
166 * expiresAt: new Date(Date.now() + 24 * 3600 * 1000),
167 * attributeFilters: [{ "aws.local.operation": "POST /checkout" }],
168 * },
169 * );
170 * ```
171 *
172 * @resource
173 */
174 export const InstrumentationConfiguration = Resource<InstrumentationConfiguration>(
175 "AWS.ApplicationSignals.InstrumentationConfiguration",
176 );
177
178 /**
179 * Normalize `expiresAt` (which the engine's state serialization flattens to
180 * an ISO string) back to a `Date` for the wire.
181 */
182 const toExpiresAt = (value: Date | string | undefined): Date | undefined =>
183 value === undefined ? undefined : new Date(value);
184
185 /**
186 * The identity + payload of a configuration in a canonical, comparable
187 * shape. Everything here is create-only: a change replaces the resource.
188 */
189 const immutableFingerprint = (props: InstrumentationConfigurationProps) =>
190 JSON.stringify({
191 instrumentationType: props.instrumentationType,
192 service: props.service,
193 environment: props.environment,
194 signalType: props.signalType,
195 location: props.location,
196 captureConfiguration: props.captureConfiguration,
197 description: props.description,
198 expiresAt: toExpiresAt(props.expiresAt)?.getTime(),
199 attributeFilters: props.attributeFilters,
200 });
201
202 export const InstrumentationConfigurationProvider = () =>
203 Provider.effect(
204 InstrumentationConfiguration,
205 Effect.gen(function* () {
206 /** The identity quadruple shared by get/create/delete requests. */
207 const identity = (
208 props: Pick<
209 InstrumentationConfigurationProps,
210 "instrumentationType" | "service" | "environment" | "signalType"
211 >,
212 ) => ({
213 InstrumentationType: props.instrumentationType,
214 Service: props.service,
215 Environment: props.environment,
216 SignalType: props.signalType,
217 });
218
219 /** Observe by location hash (preferred) or code location. */
220 const observe = Effect.fn(function* (
221 props: InstrumentationConfigurationProps,
222 locationHash: string | undefined,
223 ) {
224 const response = yield* appsignals
225 .getInstrumentationConfiguration({
226 ...identity(props),
227 LocationIdentifier: locationHash
228 ? { LocationHash: locationHash }
229 : { CodeLocation: props.location },
230 })
231 .pipe(Effect.catchTag("ResourceNotFoundException", () => Effect.undefined));
232 return response?.Configuration;
233 });
234
235 const observedTags = (arn: string) =>
236 appsignals.listTagsForResource({ ResourceArn: arn }).pipe(
237 Effect.map((response) =>
238 Object.fromEntries((response.Tags ?? []).map((tag) => [tag.Key, tag.Value])),
239 ),
240 Effect.catchTag("ResourceNotFoundException", () =>
241 Effect.succeed({} as Record<string, string>),
242 ),
243 );
244
245 const toAttrs = (configuration: appsignals.InstrumentationConfiguration) => ({
246 arn: configuration.ARN,
247 locationHash: configuration.LocationHash,
248 instrumentationType: configuration.InstrumentationType,
249 service: configuration.Service,
250 environment: configuration.Environment,
251 signalType: configuration.SignalType,
252 createdAt: configuration.CreatedAt.toISOString(),
253 });
254
255 return {
256 stables: [
257 "arn",
258 "locationHash",
259 "instrumentationType",
260 "service",
261 "environment",
262 "signalType",
263 ],
264
265 read: Effect.fn(function* ({ id, olds, output }) {
266 const props = olds;
267 if (props === undefined) return undefined;
268 const found = yield* observe(props, output?.locationHash);
269 if (found === undefined) return undefined;
270 const attrs = toAttrs(found);
271 const tags = yield* observedTags(found.ARN);
272 return (yield* hasAlchemyTags(id, tags)) ? attrs : Unowned(attrs);
273 }),
274
275 diff: Effect.fn(function* ({ news, olds }) {
276 if (!isResolved(news)) return undefined;
277 // Configurations are immutable after creation — any change other
278 // than tags replaces. Tags fall through to the default update.
279 if (olds !== undefined && immutableFingerprint(news) !== immutableFingerprint(olds)) {
280 return { action: "replace" } as const;
281 }
282 }),
283
284 reconcile: Effect.fn(function* ({ id, news, output, session }) {
285 const internalTags = yield* createInternalTags(id);
286 const desiredTags = { ...news.tags, ...internalTags };
287
288 // 1. Observe — cloud state is authoritative; `output` only caches
289 // the location hash.
290 let live = yield* observe(news, output?.locationHash);
291
292 if (live === undefined) {
293 // 2. Ensure — create when missing; a concurrent create of the
294 // same location surfaces as ConflictException, which is a
295 // race: re-observe and continue.
296 live = yield* appsignals
297 .createInstrumentationConfiguration({
298 ...identity(news),
299 Location: { CodeLocation: news.location },
300 CaptureConfiguration: {
301 CodeCapture: news.captureConfiguration,
302 },
303 Description: news.description,
304 ExpiresAt: toExpiresAt(news.expiresAt),
305 AttributeFilters: news.attributeFilters,
306 Tags: createTagsList(desiredTags),
307 })
308 .pipe(
309 Effect.catchTag("ConflictException", () =>
310 observe(news, undefined).pipe(
311 Effect.flatMap((observed) =>
312 observed === undefined
313 ? Effect.fail(
314 new InstrumentationConfigurationUnexpectedResponse({
315 message: `instrumentation configuration for '${news.service}' conflicted but was not observable`,
316 }),
317 )
318 : Effect.succeed(observed),
319 ),
320 ),
321 ),
322 );
323 }
324 // 3. There is no update API — the diff replaces on any change to
325 // the immutable payload, so an observed configuration is
326 // already converged apart from tags.
327
328 // 3b. SYNC TAGS — diff against OBSERVED cloud tags so adoption
329 // converges (create-time Tags only apply on first create).
330 const currentTags = yield* observedTags(live.ARN);
331 const { upsert, removed } = diffTags(currentTags, desiredTags);
332 if (upsert.length > 0) {
333 yield* appsignals.tagResource({
334 ResourceArn: live.ARN,
335 Tags: upsert,
336 });
337 }
338 if (removed.length > 0) {
339 yield* appsignals.untagResource({
340 ResourceArn: live.ARN,
341 TagKeys: removed,
342 });
343 }
344
345 yield* session.note(live.LocationHash);
346 return toAttrs(live);
347 }),
348
349 delete: Effect.fn(function* ({ output }) {
350 yield* appsignals
351 .deleteInstrumentationConfiguration({
352 InstrumentationType: output.instrumentationType,
353 Service: output.service,
354 Environment: output.environment,
355 SignalType: output.signalType,
356 LocationIdentifier: { LocationHash: output.locationHash },
357 })
358 .pipe(
359 // Idempotent delete — already-gone is success.
360 Effect.catchTag("ResourceNotFoundException", () => Effect.void),
361 );
362 }),
363
364 // No account-wide enumeration API (listing requires a service +
365 // environment + type scope).
366 list: () => Effect.succeed([]),
367 };
368 }),
369 );