import * as workers from "@distilled.cloud/cloudflare/workers";
import { Unowned } from "alchemy/AdoptPolicy";
import { isResolved } from "alchemy/Diff";
import { createPhysicalName } from "alchemy/PhysicalName";
import * as Provider from "alchemy/Provider";
import { Resource } from "alchemy/Resource";
import { unwrapRedacted } from "alchemy/Util/data";
import * as Effect from "effect/Effect";
import * as Predicate from "effect/Predicate";
import * as Redacted from "effect/Redacted";
import * as Schedule from "effect/Schedule";
import * as Stream from "effect/Stream";
import { CloudflareEnvironment } from "../CloudflareEnvironment.ts";
import type { Providers } from "../Providers.ts";
const TypeId = "Cloudflare.Workers.ObservabilityDestination" as const;
type TypeId = typeof TypeId;
/**
* The Workers Logs dataset exported by an observability destination.
*/
export type ObservabilityDataset =
| "opentelemetry-traces"
| "opentelemetry-logs"
| "opentelemetry-metrics";
export interface ObservabilityDestinationProps {
/**
* Human readable destination name. Cloudflare derives the destination's
* stable `slug` from it and the name cannot be changed afterwards —
* updating this property triggers a replacement. If omitted, a unique
* name is generated from the app, stage, and logical ID.
* @default ${app}-${stage}-${id}
*/
name?: string;
/**
* HTTPS endpoint the OTLP payloads are pushed to (e.g. an OTLP/HTTP
* collector). Mutable — updated in place.
*
* Cloudflare verifies the endpoint with a preflight request on create
* (unless {@link skipPreflightCheck} is set) and on **every** update, so
* the endpoint must accept a `POST` with a `2xx` response for updates to
* succeed.
*/
url: string;
/**
* Extra HTTP headers sent with each push (e.g. authentication tokens).
* Pass credentials as `Redacted` values to keep them out of plan output.
* Cloudflare always adds a `content-type: application/json` header of
* its own. Mutable — updated in place.
* @default {}
*/
headers?: Record<string, string | Redacted.Redacted<string>>;
/**
* Which Workers Logs dataset to export. Cannot be changed after
* creation — updating this property triggers a replacement.
*/
logpushDataset: ObservabilityDataset;
/**
* Whether the destination actively exports data. Mutable — updated in
* place.
* @default true
*/
enabled?: boolean;
/**
* Skip the create-time preflight request against {@link url}. Useful
* when the collector rejects empty probe payloads. Create-only — the
* update API always performs the preflight check.
* @default false
*/
skipPreflightCheck?: boolean;
}
export interface ObservabilityDestinationAttributes {
/**
* Cloudflare-assigned stable identifier, derived from the name at
* creation time.
*/
slug: string;
/**
* The Cloudflare account the destination belongs to.
*/
accountId: string;
/**
* Human readable destination name.
*/
name: string;
/**
* Whether the destination actively exports data.
*/
enabled: boolean;
/**
* HTTPS endpoint the OTLP payloads are pushed to.
*/
url: string;
/**
* The Workers Logs dataset this destination exports.
*/
logpushDataset: ObservabilityDataset;
/**
* The underlying Logpush destination string (the URL with the
* configured headers encoded as query parameters). Redacted because it
* embeds the header values, including any credentials. Undefined when
* Cloudflare omits it from the response.
*/
destinationConf?: Redacted.Redacted<string>;
/**
* Names of the Worker scripts currently opted in to this destination.
*/
scripts: string[];
}
export type ObservabilityDestination = Resource<
TypeId,
ObservabilityDestinationProps,
ObservabilityDestinationAttributes,
never,
Providers
>;
/**
* A Workers observability destination — an account-level OTLP export of
* Workers Logs telemetry (traces, logs, or metrics) pushed to an external
* HTTPS collector via Logpush.
*
* A destination is identified by its Cloudflare-derived `slug` (stable,
* computed from the name at creation). The endpoint URL, headers, and
* enabled flag are mutable in place; `name` and `logpushDataset` force a
* replacement.
*
* Cloudflare preflights the endpoint with a `POST` on create (skippable
* via `skipPreflightCheck`) and on every in-place update (not skippable),
* so the collector must answer `2xx` for updates to converge.
*
* Safety: destinations carry no ownership markers and Cloudflare enforces
* one destination per name. When there is no prior state, `read` scans the
* account for a destination with the same name and reports it as
* `Unowned`, so the engine refuses to take it over unless `--adopt` (or
* `adopt(true)`) is set.
* ### Exporting Workers traces
* **Example:** Push traces to an OTLP collector
* ```typescript
* const traces = yield* Cloudflare.Workers.ObservabilityDestination("Traces", {
* url: "https://otel.example.com/v1/traces",
* headers: { authorization: secret },
* logpushDataset: "opentelemetry-traces",
* });
* ```
*
* ### Exporting Workers logs
* **Example:** Push logs, skipping the create-time preflight
* ```typescript
* const logs = yield* Cloudflare.Workers.ObservabilityDestination("Logs", {
* name: "my-app-logs",
* url: "https://collector.example.com/v1/logs",
* logpushDataset: "opentelemetry-logs",
* skipPreflightCheck: true,
* });
* ```
*
* ### Pausing an export
* **Example:** Disable the destination without deleting it
* ```typescript
* yield* Cloudflare.Workers.ObservabilityDestination("Logs", {
* name: "my-app-logs",
* url: "https://collector.example.com/v1/logs",
* logpushDataset: "opentelemetry-logs",
* enabled: false,
* });
* ```
*
* @resource
* @product Workers
* @category Workers & Compute
*/
export const ObservabilityDestination = Resource<ObservabilityDestination>(TypeId);
/**
* Returns true if the given value is an ObservabilityDestination resource.
*/
export const isObservabilityDestination = (value: unknown): value is ObservabilityDestination =>
Predicate.hasProperty(value, "Type") && value.Type === TypeId;
export const ObservabilityDestinationProvider = () =>
Provider.succeed(ObservabilityDestination, {
stables: ["slug", "accountId", "name", "logpushDataset"],
diff: Effect.fn(function* ({ id, olds, news, output }) {
if (!isResolved(news)) return undefined;
const { accountId } = yield* yield* CloudflareEnvironment;
if ((output?.accountId ?? accountId) !== accountId) {
return { action: "replace" } as const;
}
// The slug is derived from the name at creation and the update API
// cannot rename — a name change is a replacement.
const oldName = output?.name ?? olds?.name ?? (yield* createDestinationName(id));
// Auto-generated names are engine-owned: the deployed name stays
// authoritative even if the generator would name this id differently
// today. Only an explicit user-provided name can force a replace.
const newName = news.name ?? oldName;
if (oldName !== newName) {
return { action: "replace" } as const;
}
// The update API cannot change the dataset.
const oldDataset = output?.logpushDataset ?? olds?.logpushDataset;
if (oldDataset !== undefined && oldDataset !== news.logpushDataset) {
return { action: "replace" } as const;
}
// State written by earlier versions holds `destinationConf` as a plain
// string. Reconcile to re-read it as `Redacted`; without header or URL
// drift this issues no PATCH.
if (output?.destinationConf !== undefined && !Redacted.isRedacted(output.destinationConf)) {
return { action: "update" } as const;
}
return undefined;
}),
read: Effect.fn(function* ({ id, output, olds }) {
const { accountId } = yield* yield* CloudflareEnvironment;
const acct = output?.accountId ?? accountId;
// Owned path: refresh by our persisted slug.
if (output?.slug) {
const observed = yield* findBySlug(acct, output.slug);
return observed ? toAttributes(observed, acct) : undefined;
}
// Adoption path: no state of our own, but Cloudflare enforces one
// destination per name, so an exact name match is the same logical
// destination. Destinations carry no ownership markers, so brand it
// `Unowned` and let the engine gate takeover behind the adopt
// policy.
const name = olds?.name ?? (yield* createDestinationName(id));
const observed = yield* findByName(acct, name);
return observed ? Unowned(toAttributes(observed, acct)) : undefined;
}),
reconcile: Effect.fn(function* ({ id, news, olds, output }) {
const { accountId } = yield* yield* CloudflareEnvironment;
// Prefer the deployed name: regenerating would target a different
// resource if the generator's output for this id ever drifts.
const name = news.name ?? output?.name ?? (yield* createDestinationName(id));
// Inputs have been resolved to concrete values by Plan.
const url = news.url as string;
const headers = unwrapRedacted(news.headers ?? {});
// Cloudflare masks header values on read, so the last values we know
// were applied stand in for them: the previous props, or what create
// just sent.
let appliedHeaders = olds?.headers ? unwrapRedacted(olds.headers) : undefined;
const enabled = news.enabled ?? true;
// 1. Observe — the slug cached on `output` is a hint, not a
// guarantee; fall back to the name (Cloudflare enforces name
// uniqueness, and ownership of a name match has already been
// verified upstream by `read` + the adopt policy).
let observed = output?.slug ? yield* findBySlug(accountId, output.slug) : undefined;
if (!observed) {
observed = yield* findByName(accountId, name);
}
// 2. Ensure. The API reports both a duplicate name and a failed
// endpoint preflight as the same opaque 400 — re-observe by name
// to tell a creation race (converge via sync below) from a
// genuine failure (re-fail).
if (!observed) {
const created = yield* workers
.createObservabilityDestination({
accountId,
name,
enabled,
skipPreflightCheck: news.skipPreflightCheck,
configuration: {
type: "logpush",
url,
headers,
logpushDataset: news.logpushDataset,
},
})
.pipe(
Effect.catchTag("ObservabilityDestinationCreateFailed", (originalError) =>
Effect.gen(function* () {
const match = yield* findByName(accountId, name);
if (!match) {
return yield* originalError;
}
return match;
}),
),
);
appliedHeaders = headers;
const createdSlug = created.slug;
observed = isObservedDestination(created)
? created
: yield* freshObserved(accountId, createdSlug);
}
// 3. Sync — diff observed cloud state against desired and PATCH only
// on drift. Skipping the no-op matters doubly here: every PATCH
// re-runs the endpoint preflight.
if (
observed.enabled !== enabled ||
observed.configuration.url !== url ||
!sameHeaders(observed.configuration.headers, headers, appliedHeaders)
) {
const patched = yield* workers
.patchObservabilityDestination({
accountId,
slug: observed.slug,
enabled,
configuration: { type: "logpush", url, headers },
})
.pipe(
// Every PATCH re-runs the endpoint preflight POST from
// Cloudflare's edge. A freshly deployed endpoint (e.g. a
// workers.dev sink) can transiently fail that probe while the
// route propagates, so ride out preflight failures briefly.
Effect.retry({
while: (e) => e._tag === "ObservabilityDestinationPreflightFailed",
schedule: Schedule.min([
Schedule.exponential("1 second"),
Schedule.spaced("5 seconds"),
]),
times: 8,
}),
);
observed = yield* freshObserved(accountId, patched.slug);
}
// 4. Return.
return toAttributes(observed, accountId);
}),
delete: Effect.fn(function* ({ output }) {
yield* workers
.deleteObservabilityDestination({
accountId: output.accountId,
slug: output.slug,
})
.pipe(Effect.catchTag("ObservabilityDestinationNotFound", () => Effect.void));
}),
// Account collection. Observability destinations are account-scoped and
// the distilled list op paginates on `result`; exhaustively collect every
// page and hydrate each item into the exact `read` Attributes shape via
// `toAttributes`. The destination's stored credentials/headers token are
// write-only on the API, so — like `read` — they never appear here.
list: Effect.fn(function* () {
const { accountId } = yield* yield* CloudflareEnvironment;
return yield* workers.listObservabilityDestinations.items({ accountId }).pipe(
Stream.runCollect,
Effect.map((chunk) =>
Array.from(chunk).map((observed) => toAttributes(observed, accountId)),
),
);
}),
});
type ObservedDestination = workers.ListObservabilityDestinationsResponse["result"][number];
const isObservedDestination = (
value: ObservedDestination | workers.CreateObservabilityDestinationResponse,
): value is ObservedDestination => Predicate.hasProperty(value.configuration, "headers");
const createDestinationName = (id: string) => createPhysicalName({ id, lowercase: true });
/**
* Locate a destination by its stable slug. There is no get-by-slug API,
* so observation goes through the list endpoint.
*/
const findBySlug = (accountId: string, slug: string) =>
workers.listObservabilityDestinations.items({ accountId }).pipe(
Stream.filter((d) => d.slug === slug),
Stream.runCollect,
Effect.map((chunk) => Array.from(chunk).at(0)),
);
/**
* Locate a destination by exact name. Cloudflare enforces name
* uniqueness, so a match identifies the destination.
*/
const findByName = (accountId: string, name: string) =>
workers.listObservabilityDestinations.items({ accountId }).pipe(
Stream.filter((d) => d.name === name),
Stream.runCollect,
Effect.map((chunk) => Array.from(chunk).at(0)),
);
/**
* Re-read a destination through the list endpoint after a write. The
* create/patch responses omit the stored headers, so the list item is the
* canonical observed shape.
*/
const freshObserved = (accountId: string, slug: string) =>
findBySlug(accountId, slug).pipe(
Effect.flatMap((observed) =>
observed
? Effect.succeed(observed)
: // The destination cannot vanish between the write that just
// succeeded and this read except via an out-of-band delete racing
// us — surface that as the typed not-found the API would raise.
Effect.fail(
workers.ObservabilityDestinationNotFound.make({
code: 0,
message: `observability destination "${slug}" disappeared during reconcile`,
}),
),
),
);
/**
* Compare observed headers against the desired set. Cloudflare always
* injects a `content-type: application/json` header of its own — ignore
* it unless the user explicitly pinned one, so an empty desired set is
* not perpetually "dirty".
*
* Cloudflare masks header values as `null` in its responses, so only the
* header names are observable. A masked value is compared against the
* last values known to be applied instead; without them (adoption) it
* cannot be verified and counts as drift.
*/
const sameHeaders = (
observed: Record<string, unknown>,
desired: Record<string, string>,
applied: Record<string, string> | undefined,
) => {
const keys = Object.keys(observed).filter(
(key) => key !== "content-type" || "content-type" in desired,
);
return (
keys.length === Object.keys(desired).length &&
keys.every((key) => {
const value = observed[key];
return value == null
? applied !== undefined && applied[key] === desired[key]
: (typeof value === "string" ? value : JSON.stringify(value)) === desired[key];
})
);
};
const toAttributes = (
observed: ObservedDestination,
accountId: string,
): ObservabilityDestinationAttributes => ({
slug: observed.slug,
accountId,
name: observed.name,
enabled: observed.enabled,
url: observed.configuration.url,
// Distilled widens generated string enums to open unions (`string & {}`).
logpushDataset: observed.configuration.logpushDataset as ObservabilityDataset,
destinationConf:
observed.configuration.destinationConf == null
? undefined
: Redacted.make(observed.configuration.destinationConf),
scripts: [...observed.scripts],
});