@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 455 lines 17 KB
Raw
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 });