The best way to control Claude Code, Codex and more from any computer or phone
| 1 | import * as workers from "@distilled.cloud/cloudflare/workers"; |
| 2 | import { Unowned } from "alchemy/AdoptPolicy"; |
| 3 | import { isResolved } from "alchemy/Diff"; |
| 4 | import { createPhysicalName } from "alchemy/PhysicalName"; |
| 5 | import * as Provider from "alchemy/Provider"; |
| 6 | import { Resource } from "alchemy/Resource"; |
| 7 | import { unwrapRedacted } from "alchemy/Util/data"; |
| 8 | import * as Effect from "effect/Effect"; |
| 9 | import * as Predicate from "effect/Predicate"; |
| 10 | import * as Redacted from "effect/Redacted"; |
| 11 | import * as Schedule from "effect/Schedule"; |
| 12 | import * as Stream from "effect/Stream"; |
| 13 | import { CloudflareEnvironment } from "../CloudflareEnvironment.ts"; |
| 14 | import type { Providers } from "../Providers.ts"; |
| 15 | |
| 16 | const TypeId = "Cloudflare.Workers.ObservabilityDestination" as const; |
| 17 | type TypeId = typeof TypeId; |
| 18 | |
| 19 | /** |
| 20 | * The Workers Logs dataset exported by an observability destination. |
| 21 | */ |
| 22 | export type ObservabilityDataset = |
| 23 | | "opentelemetry-traces" |
| 24 | | "opentelemetry-logs" |
| 25 | | "opentelemetry-metrics"; |
| 26 | |
| 27 | export interface ObservabilityDestinationProps { |
| 28 | /** |
| 29 | * Human readable destination name. Cloudflare derives the destination's |
| 30 | * stable `slug` from it and the name cannot be changed afterwards — |
| 31 | * updating this property triggers a replacement. If omitted, a unique |
| 32 | * name is generated from the app, stage, and logical ID. |
| 33 | * @default ${app}-${stage}-${id} |
| 34 | */ |
| 35 | name?: string; |
| 36 | /** |
| 37 | * HTTPS endpoint the OTLP payloads are pushed to (e.g. an OTLP/HTTP |
| 38 | * collector). Mutable — updated in place. |
| 39 | * |
| 40 | * Cloudflare verifies the endpoint with a preflight request on create |
| 41 | * (unless {@link skipPreflightCheck} is set) and on **every** update, so |
| 42 | * the endpoint must accept a `POST` with a `2xx` response for updates to |
| 43 | * succeed. |
| 44 | */ |
| 45 | url: string; |
| 46 | /** |
| 47 | * Extra HTTP headers sent with each push (e.g. authentication tokens). |
| 48 | * Pass credentials as `Redacted` values to keep them out of plan output. |
| 49 | * Cloudflare always adds a `content-type: application/json` header of |
| 50 | * its own. Mutable — updated in place. |
| 51 | * @default {} |
| 52 | */ |
| 53 | headers?: Record<string, string | Redacted.Redacted<string>>; |
| 54 | /** |
| 55 | * Which Workers Logs dataset to export. Cannot be changed after |
| 56 | * creation — updating this property triggers a replacement. |
| 57 | */ |
| 58 | logpushDataset: ObservabilityDataset; |
| 59 | /** |
| 60 | * Whether the destination actively exports data. Mutable — updated in |
| 61 | * place. |
| 62 | * @default true |
| 63 | */ |
| 64 | enabled?: boolean; |
| 65 | /** |
| 66 | * Skip the create-time preflight request against {@link url}. Useful |
| 67 | * when the collector rejects empty probe payloads. Create-only — the |
| 68 | * update API always performs the preflight check. |
| 69 | * @default false |
| 70 | */ |
| 71 | skipPreflightCheck?: boolean; |
| 72 | } |
| 73 | |
| 74 | export interface ObservabilityDestinationAttributes { |
| 75 | /** |
| 76 | * Cloudflare-assigned stable identifier, derived from the name at |
| 77 | * creation time. |
| 78 | */ |
| 79 | slug: string; |
| 80 | /** |
| 81 | * The Cloudflare account the destination belongs to. |
| 82 | */ |
| 83 | accountId: string; |
| 84 | /** |
| 85 | * Human readable destination name. |
| 86 | */ |
| 87 | name: string; |
| 88 | /** |
| 89 | * Whether the destination actively exports data. |
| 90 | */ |
| 91 | enabled: boolean; |
| 92 | /** |
| 93 | * HTTPS endpoint the OTLP payloads are pushed to. |
| 94 | */ |
| 95 | url: string; |
| 96 | /** |
| 97 | * The Workers Logs dataset this destination exports. |
| 98 | */ |
| 99 | logpushDataset: ObservabilityDataset; |
| 100 | /** |
| 101 | * The underlying Logpush destination string (the URL with the |
| 102 | * configured headers encoded as query parameters). Redacted because it |
| 103 | * embeds the header values, including any credentials. Undefined when |
| 104 | * Cloudflare omits it from the response. |
| 105 | */ |
| 106 | destinationConf?: Redacted.Redacted<string>; |
| 107 | /** |
| 108 | * Names of the Worker scripts currently opted in to this destination. |
| 109 | */ |
| 110 | scripts: string[]; |
| 111 | } |
| 112 | |
| 113 | export type ObservabilityDestination = Resource< |
| 114 | TypeId, |
| 115 | ObservabilityDestinationProps, |
| 116 | ObservabilityDestinationAttributes, |
| 117 | never, |
| 118 | Providers |
| 119 | >; |
| 120 | |
| 121 | /** |
| 122 | * A Workers observability destination — an account-level OTLP export of |
| 123 | * Workers Logs telemetry (traces, logs, or metrics) pushed to an external |
| 124 | * HTTPS collector via Logpush. |
| 125 | * |
| 126 | * A destination is identified by its Cloudflare-derived `slug` (stable, |
| 127 | * computed from the name at creation). The endpoint URL, headers, and |
| 128 | * enabled flag are mutable in place; `name` and `logpushDataset` force a |
| 129 | * replacement. |
| 130 | * |
| 131 | * Cloudflare preflights the endpoint with a `POST` on create (skippable |
| 132 | * via `skipPreflightCheck`) and on every in-place update (not skippable), |
| 133 | * so the collector must answer `2xx` for updates to converge. |
| 134 | * |
| 135 | * Safety: destinations carry no ownership markers and Cloudflare enforces |
| 136 | * one destination per name. When there is no prior state, `read` scans the |
| 137 | * account for a destination with the same name and reports it as |
| 138 | * `Unowned`, so the engine refuses to take it over unless `--adopt` (or |
| 139 | * `adopt(true)`) is set. |
| 140 | * ### Exporting Workers traces |
| 141 | * **Example:** Push traces to an OTLP collector |
| 142 | * ```typescript |
| 143 | * const traces = yield* Cloudflare.Workers.ObservabilityDestination("Traces", { |
| 144 | * url: "https://otel.example.com/v1/traces", |
| 145 | * headers: { authorization: secret }, |
| 146 | * logpushDataset: "opentelemetry-traces", |
| 147 | * }); |
| 148 | * ``` |
| 149 | * |
| 150 | * ### Exporting Workers logs |
| 151 | * **Example:** Push logs, skipping the create-time preflight |
| 152 | * ```typescript |
| 153 | * const logs = yield* Cloudflare.Workers.ObservabilityDestination("Logs", { |
| 154 | * name: "my-app-logs", |
| 155 | * url: "https://collector.example.com/v1/logs", |
| 156 | * logpushDataset: "opentelemetry-logs", |
| 157 | * skipPreflightCheck: true, |
| 158 | * }); |
| 159 | * ``` |
| 160 | * |
| 161 | * ### Pausing an export |
| 162 | * **Example:** Disable the destination without deleting it |
| 163 | * ```typescript |
| 164 | * yield* Cloudflare.Workers.ObservabilityDestination("Logs", { |
| 165 | * name: "my-app-logs", |
| 166 | * url: "https://collector.example.com/v1/logs", |
| 167 | * logpushDataset: "opentelemetry-logs", |
| 168 | * enabled: false, |
| 169 | * }); |
| 170 | * ``` |
| 171 | * |
| 172 | * @resource |
| 173 | * @product Workers |
| 174 | * @category Workers & Compute |
| 175 | */ |
| 176 | export const ObservabilityDestination = Resource<ObservabilityDestination>(TypeId); |
| 177 | |
| 178 | /** |
| 179 | * Returns true if the given value is an ObservabilityDestination resource. |
| 180 | */ |
| 181 | export const isObservabilityDestination = (value: unknown): value is ObservabilityDestination => |
| 182 | Predicate.hasProperty(value, "Type") && value.Type === TypeId; |
| 183 | |
| 184 | export const ObservabilityDestinationProvider = () => |
| 185 | Provider.succeed(ObservabilityDestination, { |
| 186 | stables: ["slug", "accountId", "name", "logpushDataset"], |
| 187 | |
| 188 | diff: Effect.fn(function* ({ id, olds, news, output }) { |
| 189 | if (!isResolved(news)) return undefined; |
| 190 | const { accountId } = yield* yield* CloudflareEnvironment; |
| 191 | if ((output?.accountId ?? accountId) !== accountId) { |
| 192 | return { action: "replace" } as const; |
| 193 | } |
| 194 | // The slug is derived from the name at creation and the update API |
| 195 | // cannot rename — a name change is a replacement. |
| 196 | const oldName = output?.name ?? olds?.name ?? (yield* createDestinationName(id)); |
| 197 | // Auto-generated names are engine-owned: the deployed name stays |
| 198 | // authoritative even if the generator would name this id differently |
| 199 | // today. Only an explicit user-provided name can force a replace. |
| 200 | const newName = news.name ?? oldName; |
| 201 | if (oldName !== newName) { |
| 202 | return { action: "replace" } as const; |
| 203 | } |
| 204 | // The update API cannot change the dataset. |
| 205 | const oldDataset = output?.logpushDataset ?? olds?.logpushDataset; |
| 206 | if (oldDataset !== undefined && oldDataset !== news.logpushDataset) { |
| 207 | return { action: "replace" } as const; |
| 208 | } |
| 209 | // State written by earlier versions holds `destinationConf` as a plain |
| 210 | // string. Reconcile to re-read it as `Redacted`; without header or URL |
| 211 | // drift this issues no PATCH. |
| 212 | if (output?.destinationConf !== undefined && !Redacted.isRedacted(output.destinationConf)) { |
| 213 | return { action: "update" } as const; |
| 214 | } |
| 215 | return undefined; |
| 216 | }), |
| 217 | |
| 218 | read: Effect.fn(function* ({ id, output, olds }) { |
| 219 | const { accountId } = yield* yield* CloudflareEnvironment; |
| 220 | const acct = output?.accountId ?? accountId; |
| 221 | |
| 222 | // Owned path: refresh by our persisted slug. |
| 223 | if (output?.slug) { |
| 224 | const observed = yield* findBySlug(acct, output.slug); |
| 225 | return observed ? toAttributes(observed, acct) : undefined; |
| 226 | } |
| 227 | // Adoption path: no state of our own, but Cloudflare enforces one |
| 228 | // destination per name, so an exact name match is the same logical |
| 229 | // destination. Destinations carry no ownership markers, so brand it |
| 230 | // `Unowned` and let the engine gate takeover behind the adopt |
| 231 | // policy. |
| 232 | const name = olds?.name ?? (yield* createDestinationName(id)); |
| 233 | const observed = yield* findByName(acct, name); |
| 234 | return observed ? Unowned(toAttributes(observed, acct)) : undefined; |
| 235 | }), |
| 236 | |
| 237 | reconcile: Effect.fn(function* ({ id, news, olds, output }) { |
| 238 | const { accountId } = yield* yield* CloudflareEnvironment; |
| 239 | // Prefer the deployed name: regenerating would target a different |
| 240 | // resource if the generator's output for this id ever drifts. |
| 241 | const name = news.name ?? output?.name ?? (yield* createDestinationName(id)); |
| 242 | // Inputs have been resolved to concrete values by Plan. |
| 243 | const url = news.url as string; |
| 244 | const headers = unwrapRedacted(news.headers ?? {}); |
| 245 | // Cloudflare masks header values on read, so the last values we know |
| 246 | // were applied stand in for them: the previous props, or what create |
| 247 | // just sent. |
| 248 | let appliedHeaders = olds?.headers ? unwrapRedacted(olds.headers) : undefined; |
| 249 | const enabled = news.enabled ?? true; |
| 250 | |
| 251 | // 1. Observe — the slug cached on `output` is a hint, not a |
| 252 | // guarantee; fall back to the name (Cloudflare enforces name |
| 253 | // uniqueness, and ownership of a name match has already been |
| 254 | // verified upstream by `read` + the adopt policy). |
| 255 | let observed = output?.slug ? yield* findBySlug(accountId, output.slug) : undefined; |
| 256 | if (!observed) { |
| 257 | observed = yield* findByName(accountId, name); |
| 258 | } |
| 259 | |
| 260 | // 2. Ensure. The API reports both a duplicate name and a failed |
| 261 | // endpoint preflight as the same opaque 400 — re-observe by name |
| 262 | // to tell a creation race (converge via sync below) from a |
| 263 | // genuine failure (re-fail). |
| 264 | if (!observed) { |
| 265 | const created = yield* workers |
| 266 | .createObservabilityDestination({ |
| 267 | accountId, |
| 268 | name, |
| 269 | enabled, |
| 270 | skipPreflightCheck: news.skipPreflightCheck, |
| 271 | configuration: { |
| 272 | type: "logpush", |
| 273 | url, |
| 274 | headers, |
| 275 | logpushDataset: news.logpushDataset, |
| 276 | }, |
| 277 | }) |
| 278 | .pipe( |
| 279 | Effect.catchTag("ObservabilityDestinationCreateFailed", (originalError) => |
| 280 | Effect.gen(function* () { |
| 281 | const match = yield* findByName(accountId, name); |
| 282 | if (!match) { |
| 283 | return yield* originalError; |
| 284 | } |
| 285 | return match; |
| 286 | }), |
| 287 | ), |
| 288 | ); |
| 289 | appliedHeaders = headers; |
| 290 | const createdSlug = created.slug; |
| 291 | observed = isObservedDestination(created) |
| 292 | ? created |
| 293 | : yield* freshObserved(accountId, createdSlug); |
| 294 | } |
| 295 | |
| 296 | // 3. Sync — diff observed cloud state against desired and PATCH only |
| 297 | // on drift. Skipping the no-op matters doubly here: every PATCH |
| 298 | // re-runs the endpoint preflight. |
| 299 | if ( |
| 300 | observed.enabled !== enabled || |
| 301 | observed.configuration.url !== url || |
| 302 | !sameHeaders(observed.configuration.headers, headers, appliedHeaders) |
| 303 | ) { |
| 304 | const patched = yield* workers |
| 305 | .patchObservabilityDestination({ |
| 306 | accountId, |
| 307 | slug: observed.slug, |
| 308 | enabled, |
| 309 | configuration: { type: "logpush", url, headers }, |
| 310 | }) |
| 311 | .pipe( |
| 312 | // Every PATCH re-runs the endpoint preflight POST from |
| 313 | // Cloudflare's edge. A freshly deployed endpoint (e.g. a |
| 314 | // workers.dev sink) can transiently fail that probe while the |
| 315 | // route propagates, so ride out preflight failures briefly. |
| 316 | Effect.retry({ |
| 317 | while: (e) => e._tag === "ObservabilityDestinationPreflightFailed", |
| 318 | schedule: Schedule.min([ |
| 319 | Schedule.exponential("1 second"), |
| 320 | Schedule.spaced("5 seconds"), |
| 321 | ]), |
| 322 | times: 8, |
| 323 | }), |
| 324 | ); |
| 325 | observed = yield* freshObserved(accountId, patched.slug); |
| 326 | } |
| 327 | |
| 328 | // 4. Return. |
| 329 | return toAttributes(observed, accountId); |
| 330 | }), |
| 331 | |
| 332 | delete: Effect.fn(function* ({ output }) { |
| 333 | yield* workers |
| 334 | .deleteObservabilityDestination({ |
| 335 | accountId: output.accountId, |
| 336 | slug: output.slug, |
| 337 | }) |
| 338 | .pipe(Effect.catchTag("ObservabilityDestinationNotFound", () => Effect.void)); |
| 339 | }), |
| 340 | |
| 341 | // Account collection. Observability destinations are account-scoped and |
| 342 | // the distilled list op paginates on `result`; exhaustively collect every |
| 343 | // page and hydrate each item into the exact `read` Attributes shape via |
| 344 | // `toAttributes`. The destination's stored credentials/headers token are |
| 345 | // write-only on the API, so — like `read` — they never appear here. |
| 346 | list: Effect.fn(function* () { |
| 347 | const { accountId } = yield* yield* CloudflareEnvironment; |
| 348 | return yield* workers.listObservabilityDestinations.items({ accountId }).pipe( |
| 349 | Stream.runCollect, |
| 350 | Effect.map((chunk) => |
| 351 | Array.from(chunk).map((observed) => toAttributes(observed, accountId)), |
| 352 | ), |
| 353 | ); |
| 354 | }), |
| 355 | }); |
| 356 | |
| 357 | type ObservedDestination = workers.ListObservabilityDestinationsResponse["result"][number]; |
| 358 | |
| 359 | const isObservedDestination = ( |
| 360 | value: ObservedDestination | workers.CreateObservabilityDestinationResponse, |
| 361 | ): value is ObservedDestination => Predicate.hasProperty(value.configuration, "headers"); |
| 362 | |
| 363 | const createDestinationName = (id: string) => createPhysicalName({ id, lowercase: true }); |
| 364 | |
| 365 | /** |
| 366 | * Locate a destination by its stable slug. There is no get-by-slug API, |
| 367 | * so observation goes through the list endpoint. |
| 368 | */ |
| 369 | const findBySlug = (accountId: string, slug: string) => |
| 370 | workers.listObservabilityDestinations.items({ accountId }).pipe( |
| 371 | Stream.filter((d) => d.slug === slug), |
| 372 | Stream.runCollect, |
| 373 | Effect.map((chunk) => Array.from(chunk).at(0)), |
| 374 | ); |
| 375 | |
| 376 | /** |
| 377 | * Locate a destination by exact name. Cloudflare enforces name |
| 378 | * uniqueness, so a match identifies the destination. |
| 379 | */ |
| 380 | const findByName = (accountId: string, name: string) => |
| 381 | workers.listObservabilityDestinations.items({ accountId }).pipe( |
| 382 | Stream.filter((d) => d.name === name), |
| 383 | Stream.runCollect, |
| 384 | Effect.map((chunk) => Array.from(chunk).at(0)), |
| 385 | ); |
| 386 | |
| 387 | /** |
| 388 | * Re-read a destination through the list endpoint after a write. The |
| 389 | * create/patch responses omit the stored headers, so the list item is the |
| 390 | * canonical observed shape. |
| 391 | */ |
| 392 | const freshObserved = (accountId: string, slug: string) => |
| 393 | findBySlug(accountId, slug).pipe( |
| 394 | Effect.flatMap((observed) => |
| 395 | observed |
| 396 | ? Effect.succeed(observed) |
| 397 | : // The destination cannot vanish between the write that just |
| 398 | // succeeded and this read except via an out-of-band delete racing |
| 399 | // us — surface that as the typed not-found the API would raise. |
| 400 | Effect.fail( |
| 401 | workers.ObservabilityDestinationNotFound.make({ |
| 402 | code: 0, |
| 403 | message: `observability destination "${slug}" disappeared during reconcile`, |
| 404 | }), |
| 405 | ), |
| 406 | ), |
| 407 | ); |
| 408 | |
| 409 | /** |
| 410 | * Compare observed headers against the desired set. Cloudflare always |
| 411 | * injects a `content-type: application/json` header of its own — ignore |
| 412 | * it unless the user explicitly pinned one, so an empty desired set is |
| 413 | * not perpetually "dirty". |
| 414 | * |
| 415 | * Cloudflare masks header values as `null` in its responses, so only the |
| 416 | * header names are observable. A masked value is compared against the |
| 417 | * last values known to be applied instead; without them (adoption) it |
| 418 | * cannot be verified and counts as drift. |
| 419 | */ |
| 420 | const sameHeaders = ( |
| 421 | observed: Record<string, unknown>, |
| 422 | desired: Record<string, string>, |
| 423 | applied: Record<string, string> | undefined, |
| 424 | ) => { |
| 425 | const keys = Object.keys(observed).filter( |
| 426 | (key) => key !== "content-type" || "content-type" in desired, |
| 427 | ); |
| 428 | return ( |
| 429 | keys.length === Object.keys(desired).length && |
| 430 | keys.every((key) => { |
| 431 | const value = observed[key]; |
| 432 | return value == null |
| 433 | ? applied !== undefined && applied[key] === desired[key] |
| 434 | : (typeof value === "string" ? value : JSON.stringify(value)) === desired[key]; |
| 435 | }) |
| 436 | ); |
| 437 | }; |
| 438 | |
| 439 | const toAttributes = ( |
| 440 | observed: ObservedDestination, |
| 441 | accountId: string, |
| 442 | ): ObservabilityDestinationAttributes => ({ |
| 443 | slug: observed.slug, |
| 444 | accountId, |
| 445 | name: observed.name, |
| 446 | enabled: observed.enabled, |
| 447 | url: observed.configuration.url, |
| 448 | // Distilled widens generated string enums to open unions (`string & {}`). |
| 449 | logpushDataset: observed.configuration.logpushDataset as ObservabilityDataset, |
| 450 | destinationConf: |
| 451 | observed.configuration.destinationConf == null |
| 452 | ? undefined |
| 453 | : Redacted.make(observed.configuration.destinationConf), |
| 454 | scripts: [...observed.scripts], |
| 455 | }); |