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

main
ts 457 lines 17.3 KB
Raw
1 import * as ConfigProvider from "effect/ConfigProvider";
2 import * as Context from "effect/Context";
3 import type * as Duration from "effect/Duration";
4 import * as Effect from "effect/Effect";
5 import * as Formatter from "effect/Formatter";
6 import * as HttpClient from "effect/http/HttpClient";
7 import * as HttpClientRequest from "effect/http/HttpClientRequest";
8 import * as Layer from "effect/Layer";
9 import * as OtlpLogger from "effect/observability/OtlpLogger";
10 import * as OtlpMetrics from "effect/observability/OtlpMetrics";
11 import * as OtlpSerialization from "effect/observability/OtlpSerialization";
12 import * as OtlpTracer from "effect/observability/OtlpTracer";
13 import * as Predicate from "effect/Predicate";
14 import * as Redacted from "effect/Redacted";
15 import * as Result from "effect/Result";
16 import type * as Scope from "effect/Scope";
17 import { unpackEnvValue } from "./RuntimeContext.ts";
18
19 /**
20 * The shape of the {@link Telemetry} reference: a Layer of telemetry
21 * exporters (tracer, loggers, metrics) built once per event into the
22 * event's request scope. Requirements are satisfied from the runtime's
23 * isolate context (`HttpClient`, `ConfigProvider`, …).
24 */
25 export type TelemetryLayer = Layer.Layer<never, any, any>;
26
27 /**
28 * Read one bound value back at runtime. `rc.set` packs values for the env
29 * var wire (plain values JSON-stringified, `Redacted` as a marker routed
30 * through the secret channel), so the raw env string must be unpacked with
31 * {@link unpackEnvValue} — it handles all three shapes (packed JSON,
32 * Redacted marker, and a raw string set directly in the environment).
33 */
34 const readBoundValue = (key: string): Effect.Effect<unknown> =>
35 Effect.flatMap(ConfigProvider.ConfigProvider, (provider) => provider.load([key])).pipe(
36 // Missing optional bindings are normal on every event. Read their scalar
37 // directly instead of constructing a Config/Schema error for each absence.
38 Effect.orDie,
39 Effect.catchDefect((defect) =>
40 Predicate.isTagged(defect, "SourceError") ? Effect.undefined : Effect.die(defect),
41 ),
42 Effect.map((node) => {
43 const raw = node?.value;
44 if (raw === undefined || raw === "") {
45 return undefined;
46 }
47 const value = unpackEnvValue<unknown>(raw);
48 return Redacted.isRedacted(value) ? Redacted.value(value) : value;
49 }),
50 );
51
52 const readBound = (key: string): Effect.Effect<string | undefined> =>
53 readBoundValue(key).pipe(
54 Effect.map((inner) =>
55 inner === undefined ? undefined : typeof inner === "string" ? inner : Formatter.format(inner),
56 ),
57 );
58
59 /**
60 * `service.name` fallback chain for the default exporter: the standard
61 * OTEL variable, then the physical Function/Worker name, then the stack
62 * name. `OtlpResource.fromConfig` dies without a service name, so the
63 * chain must always produce one.
64 */
65 const defaultServiceName = Effect.gen(function* () {
66 return (
67 (yield* readBound("OTEL_SERVICE_NAME")) ??
68 (yield* readBound("ALCHEMY_WORKER_NAME")) ??
69 (yield* readBound("AWS_LAMBDA_FUNCTION_NAME")) ??
70 (yield* readBound("ALCHEMY_STACK_NAME")) ??
71 "alchemy"
72 );
73 });
74
75 const defaultResource = Effect.gen(function* () {
76 const serviceName = yield* defaultServiceName;
77 const stack = yield* readBound("ALCHEMY_STACK_NAME");
78 const stage = yield* readBound("ALCHEMY_STAGE");
79 return {
80 serviceName,
81 attributes: {
82 ...(stack !== undefined ? { "alchemy.stack": stack } : undefined),
83 ...(stage !== undefined ? { "alchemy.stage": stage } : undefined),
84 },
85 };
86 });
87
88 /**
89 * Parse the OpenTelemetry `OTEL_EXPORTER_OTLP_HEADERS` format:
90 * `key1=value1,key2=value2` with URL-encoded values.
91 */
92 const parseOtlpHeaders = (raw: string | undefined): Record<string, string> | undefined => {
93 if (raw === undefined || raw === "") {
94 return undefined;
95 }
96 const headers: Record<string, string> = {};
97 for (const entry of raw.split(",")) {
98 const eq = entry.indexOf("=");
99 if (eq === -1) {
100 continue;
101 }
102 const key = entry.slice(0, eq).trim();
103 if (key === "") {
104 continue;
105 }
106 const value = entry.slice(eq + 1).trim();
107 try {
108 headers[key] = decodeURIComponent(value);
109 } catch {
110 headers[key] = value;
111 }
112 }
113 return headers;
114 };
115
116 /**
117 * One export target for one signal, as stored in the bound destination
118 * list: a concrete OTLP/HTTP URL and the headers to send with it.
119 */
120 export interface ResolvedSignal {
121 url: string;
122 headers?: Record<string, string> | undefined;
123 }
124
125 /**
126 * One export destination in the bound list — the resolved form of one
127 * {@link layerOtlp} layer.
128 */
129 export interface ResolvedDestination {
130 traces?: ResolvedSignal | undefined;
131 logs?: ResolvedSignal | undefined;
132 metrics?: ResolvedSignal | undefined;
133 }
134
135 /**
136 * The single env binding carrying every configured destination as a JSON
137 * array of {@link ResolvedDestination}. One key (instead of per-signal
138 * keys) is what lets multiple `layerOtlp` layers compose — each layer
139 * build appends its destination and rebinds the full list.
140 */
141 export const EXPORTERS_KEY = "ALCHEMY_OTEL_EXPORTERS";
142
143 /**
144 * Resolve one signal's endpoint + headers from the standard OpenTelemetry
145 * env vars (`OTEL_EXPORTER_OTLP_{SIGNAL}_ENDPOINT` as-is, or the base
146 * endpoint with `/v1/{signal}` appended; headers per-signal → base). This
147 * forms an *implicit extra destination*, so platform-injected OTLP config
148 * exports without any layer.
149 */
150 const signalConfig = (signal: "TRACES" | "LOGS" | "METRICS", base: string | undefined) =>
151 Effect.gen(function* () {
152 const specific = yield* readBound(`OTEL_EXPORTER_OTLP_${signal}_ENDPOINT`);
153 const url =
154 specific !== undefined && specific !== ""
155 ? specific
156 : base !== undefined && base !== ""
157 ? `${base.replace(/\/$/, "")}/v1/${signal.toLowerCase()}`
158 : undefined;
159 if (url === undefined) {
160 return undefined;
161 }
162 const rawHeaders =
163 (yield* readBound(`OTEL_EXPORTER_OTLP_${signal}_HEADERS`)) ??
164 (yield* readBound("OTEL_EXPORTER_OTLP_HEADERS"));
165 return { url, headers: parseOtlpHeaders(rawHeaders) } as ResolvedSignal;
166 });
167
168 /**
169 * Sentinel URLs the single exporter set posts to; the fanout client
170 * rewrites each POST to every configured destination for that signal.
171 * Serializing once through one exporter per signal is what keeps span ids
172 * consistent across destinations — Effect has a single `Tracer` service,
173 * so per-destination tracers would generate divergent trace ids.
174 */
175 const SENTINEL = {
176 traces: "http://telemetry.alchemy.internal/v1/traces",
177 logs: "http://telemetry.alchemy.internal/v1/logs",
178 metrics: "http://telemetry.alchemy.internal/v1/metrics",
179 } as const;
180
181 /**
182 * Wrap the ambient `HttpClient` so a POST to a sentinel URL is re-sent to
183 * every destination configured for that signal (with the destination's own
184 * headers). A single healthy destination keeps the exporter alive: the
185 * first 2xx response is returned; per-destination failures are logged at
186 * debug and only surface when every destination fails.
187 */
188 const fanoutClient = (
189 routes: ReadonlyMap<string, ResolvedSignal[]>,
190 ): Layer.Layer<HttpClient.HttpClient, never, HttpClient.HttpClient> =>
191 Layer.effect(
192 HttpClient.HttpClient,
193 Effect.gen(function* () {
194 const base = yield* HttpClient.HttpClient;
195 return HttpClient.transform(base, (effect, request) => {
196 const targets = routes.get(request.url);
197 if (targets === undefined) {
198 return effect;
199 }
200 return Effect.gen(function* () {
201 const results = yield* Effect.forEach(
202 targets,
203 (target) =>
204 Effect.result(
205 base.execute(
206 request.pipe(
207 HttpClientRequest.setUrl(target.url),
208 HttpClientRequest.setHeaders(target.headers ?? {}),
209 ),
210 ),
211 ),
212 { concurrency: "unbounded" },
213 );
214 const healthy = results.find(
215 (result) =>
216 Result.isSuccess(result) &&
217 result.success.status >= 200 &&
218 result.success.status < 300,
219 );
220 const anySuccess = healthy ?? results.find((result) => Result.isSuccess(result));
221 if (anySuccess !== undefined && Result.isSuccess(anySuccess)) {
222 for (const result of results) {
223 if (result !== anySuccess && Result.isFailure(result)) {
224 yield* Effect.logDebug("telemetry destination failed", result.failure);
225 }
226 }
227 return anySuccess.success;
228 }
229 const failure = results.find((result) => Result.isFailure(result));
230 return yield* failure !== undefined && Result.isFailure(failure)
231 ? Effect.fail(failure.failure)
232 : effect;
233 });
234 });
235 }),
236 );
237
238 /**
239 * Every destination this runtime exports to: the bound `layerOtlp` list,
240 * plus the standard `OTEL_EXPORTER_OTLP_*` variables as an implicit extra
241 * destination. Resolved per call, since providers can change between events.
242 *
243 * @internal
244 */
245 export const configuredDestinations: Effect.Effect<ResolvedDestination[]> = Effect.gen(
246 function* () {
247 // Depending on the secret/plain packing path, the bound list arrives
248 // as a JSON string or already parsed into an array.
249 const rawList = yield* readBoundValue(EXPORTERS_KEY);
250 const bound: ResolvedDestination[] = Array.isArray(rawList)
251 ? (rawList as ResolvedDestination[])
252 : typeof rawList === "string" && rawList !== ""
253 ? yield* Effect.try(() => JSON.parse(rawList) as ResolvedDestination[]).pipe(Effect.orDie)
254 : [];
255 const baseEndpoint = yield* readBound("OTEL_EXPORTER_OTLP_ENDPOINT");
256 const [stdTraces, stdLogs, stdMetrics] = yield* Effect.all([
257 signalConfig("TRACES", baseEndpoint),
258 signalConfig("LOGS", baseEndpoint),
259 signalConfig("METRICS", baseEndpoint),
260 ]);
261 return [
262 ...bound,
263 ...(stdTraces || stdLogs || stdMetrics
264 ? [{ traces: stdTraces, logs: stdLogs, metrics: stdMetrics }]
265 : []),
266 ];
267 },
268 );
269
270 const makeExporterLayer = (options?: {
271 exportInterval?: Duration.Input;
272 shutdownTimeout?: Duration.Input;
273 }): TelemetryLayer =>
274 Layer.unwrap(
275 Effect.gen(function* () {
276 const destinations = yield* configuredDestinations;
277 const targets = (signal: keyof ResolvedDestination) =>
278 destinations.flatMap((destination) => {
279 const resolved = destination[signal];
280 return resolved !== undefined ? [resolved] : [];
281 });
282 const traces = targets("traces");
283 const logs = targets("logs");
284 const metrics = targets("metrics");
285 if (traces.length === 0 && logs.length === 0 && metrics.length === 0) {
286 return Layer.empty;
287 }
288 const resource = yield* defaultResource;
289 const routes = new Map<string, ResolvedSignal[]>();
290 const layers: Layer.Layer<never, never, any>[] = [];
291 if (traces.length > 0) {
292 routes.set(SENTINEL.traces, traces);
293 layers.push(
294 OtlpTracer.layer({
295 url: SENTINEL.traces,
296 resource,
297 exportInterval: options?.exportInterval,
298 shutdownTimeout: options?.shutdownTimeout,
299 }),
300 );
301 }
302 if (logs.length > 0) {
303 routes.set(SENTINEL.logs, logs);
304 layers.push(
305 OtlpLogger.layer({
306 url: SENTINEL.logs,
307 resource,
308 exportInterval: options?.exportInterval,
309 shutdownTimeout: options?.shutdownTimeout,
310 }),
311 );
312 }
313 if (metrics.length > 0) {
314 routes.set(SENTINEL.metrics, metrics);
315 layers.push(
316 OtlpMetrics.layer({
317 url: SENTINEL.metrics,
318 resource,
319 exportInterval: options?.exportInterval,
320 shutdownTimeout: options?.shutdownTimeout,
321 }).pipe(
322 // Metrics go out as protobuf: OTLP/HTTP receivers must accept
323 // it, while JSON is optional and some reject it on /v1/metrics
324 // (Axiom answers 415 Unsupported Media Type).
325 Layer.provide(OtlpSerialization.layerProtobuf),
326 ),
327 );
328 }
329 return Layer.mergeAll(...(layers as [Layer.Layer<never>])).pipe(
330 Layer.provide(OtlpSerialization.layerJson),
331 Layer.provide(fanoutClient(routes)),
332 );
333 }).pipe(
334 Effect.catchCause((cause) =>
335 Effect.logWarning("Invalid telemetry configuration; telemetry disabled", cause).pipe(
336 Effect.as(Layer.empty),
337 ),
338 ),
339 ),
340 );
341
342 /**
343 * The runtime half of the {@link layerOtlp} binding, and the default
344 * per-event Layer: reads the bound `OTEL_EXPORTER_OTLP_*` values back and
345 * constructs the OTLP exporters (JSON for traces and logs, protobuf for
346 * metrics). Each signal resolves independently;
347 * only configured signals export; resolves to `Layer.empty` when nothing is
348 * bound, so no exporters are built until a destination is configured.
349 *
350 * The periodic export intervals are effectively disabled: the exporter is
351 * built per event and the request-scope flush delivers everything. An
352 * interval export firing mid-event would race the scope close — the close
353 * interrupts the exporter's in-flight batch (already spliced out of the
354 * buffer), silently dropping it. Lambda invocations regularly outlive the
355 * 1-second logger interval, which is exactly how this was discovered.
356 * Final exports get the OTLP ten-second batch budget rather than the
357 * exporter's three-second shutdown default, which can cancel slow delivery.
358 *
359 * A malformed configuration degrades to `Layer.empty` with a warning
360 * instead of failing the event.
361 */
362 export const fromBoundConfig: TelemetryLayer = makeExporterLayer({
363 exportInterval: "1 hour",
364 shutdownTimeout: "10 seconds",
365 });
366
367 /**
368 * The process-runtime half of the binding: same bound-value resolution with
369 * the standard periodic export intervals, since a server's root scope only
370 * flushes at shutdown.
371 */
372 const fromBoundConfigProcess: TelemetryLayer = makeExporterLayer();
373
374 /**
375 * The per-event telemetry exporters, as a `Context.Reference` holding the
376 * Layer the runtime bridges build into every event's request scope.
377 * Provide it via {@link layerOtlp} / {@link layer} rather than directly —
378 * see the module documentation.
379 */
380 export const Telemetry = Context.Reference<TelemetryLayer>("alchemy/Telemetry", {
381 defaultValue: () => fromBoundConfig,
382 });
383
384 const reference = Telemetry;
385
386 /**
387 * Build the configured {@link Telemetry} Layer into an event's request
388 * scope, returning the Context of telemetry services to provide to the
389 * event's handler effect.
390 *
391 * Called by the runtime bridges (Worker, Durable Object, Workflow, Lambda)
392 * once per event. Building into the *request* scope — not the
393 * never-finalized isolate scope — is what makes export work on workerd:
394 * the batching fiber lives inside the event's I/O context and the final
395 * flush runs from the scope's finalizer, which the bridges register with
396 * `ctx.waitUntil`.
397 *
398 * A failed build (bad user Layer, config error) degrades to an empty
399 * Context with a warning instead of failing the event.
400 *
401 * `override` is the (possibly merged) custom Layer registered on the
402 * runtime context by {@link layer} during init. It composes with
403 * — rather than replaces — the bound OTLP destinations: loggers and metric
404 * exporters merge, and a custom `Tracer` (a single Effect service) wins
405 * over the built-in one.
406 *
407 * Declared `R = never`: the Layer's actual requirements (`HttpClient`,
408 * `ConfigProvider`, …) are satisfied at runtime by the bridge's surrounding
409 * `Effect.provide` of the built runtime context.
410 */
411 export const buildEventTelemetry = (
412 context: Context.Context<never>,
413 scope: Scope.Scope,
414 override?: TelemetryLayer,
415 base?: TelemetryLayer,
416 ): Effect.Effect<Context.Context<never>> =>
417 Effect.suspend(() => {
418 const bound = base ?? Context.get(context, reference);
419 return Layer.buildWithScope(
420 override === undefined ? bound : Layer.mergeAll(bound, override),
421 scope,
422 );
423 }).pipe(
424 Effect.catchCause((cause) =>
425 Effect.logWarning("Failed to build telemetry layer", cause).pipe(Effect.as(Context.empty())),
426 ),
427 ) as Effect.Effect<Context.Context<never>>;
428
429 /**
430 * Provide telemetry to a long-running server process (Cloudflare Container,
431 * ECS Task, EC2 host, Lambda microVM).
432 *
433 * Unlike the per-event runtime bridges, server processes have no I/O-context
434 * pinning and a real shutdown: the configured {@link Telemetry} Layer is
435 * built ONCE into the ambient root scope, exporters batch on their intervals
436 * for the life of the process, and the final flush runs when the root scope
437 * closes on graceful exit.
438 *
439 * `runtimeContext` is the entrypoint's runtime context; its `telemetry`
440 * field carries the custom Layer(s) registered by {@link layer}
441 * during init, composed with the bound OTLP destinations (read with the
442 * standard periodic export intervals).
443 */
444 export const provideProcessTelemetry =
445 (runtimeContext?: { telemetry?: TelemetryLayer | undefined }) =>
446 <A, E, R>(effect: Effect.Effect<A, E, R>): Effect.Effect<A, E, R | Scope.Scope> =>
447 Effect.gen(function* () {
448 const context = yield* Effect.context<never>();
449 const scope = yield* Effect.scope;
450 const telemetry = yield* buildEventTelemetry(
451 context,
452 scope,
453 runtimeContext?.telemetry,
454 fromBoundConfigProcess,
455 );
456 return yield* Effect.provideContext(effect, telemetry);
457 });