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
| 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 | }); |