sailfork / t3code-github / .repos/ alchemy-effect/ packages/ cloudflare/ src/ Alerting/ Webhook.ts

import * as alerting from "@distilled.cloud/cloudflare/alerting";
import { createPhysicalName } from "alchemy/PhysicalName";
import * as Provider from "alchemy/Provider";
import { Resource } from "alchemy/Resource";
import * as Data from "effect/Data";
import * as Effect from "effect/Effect";
import * as Option from "effect/Option";
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";

export class WebhookUnexpectedResponse extends Data.TaggedError("WebhookUnexpectedResponse")<{
  readonly message: string;
  readonly cause?: unknown;
}> {}

const TypeId = "Cloudflare.Alerting.Webhook" as const;
type TypeId = typeof TypeId;

/**
 * Webhook destination endpoint type, inferred by Cloudflare from the URL.
 */
export type NotificationWebhookType =
  | "datadog"
  | "discord"
  | "feishu"
  | "gchat"
  | "generic"
  | "opsgenie"
  | "slack"
  | "splunk"
  // Keep the union open so new Cloudflare destination types aren't blocked
  // by stale types.
  | (string & {});

export interface NotificationWebhookProps {
  /**
   * Name of the webhook destination. Included in the request body when a
   * notification is dispatched. If omitted, a unique name is generated.
   * Mutable — renames are applied in place.
   * @default ${app}-${id}-${stage}-${suffix}
   */
  name?: string;
  /**
   * The POST endpoint Cloudflare calls when dispatching a notification.
   * Cloudflare sends a test request on create/update; the endpoint must
   * respond with a 2xx or the operation fails with `WebhookTestFailed`.
   * Mutable — updated in place.
   */
  url: string;
  /**
   * Optional secret sent in the `cf-webhook-auth` header on every
   * notification dispatch (for generic webhooks). Write-only: Cloudflare
   * never returns it, so drift cannot be observed — the secret is re-sent
   * whenever the prop value changes.
   */
  secret?: Redacted.Redacted<string>;
}

export interface NotificationWebhookAttributes {
  /** Cloudflare-assigned webhook destination UUID. */
  webhookId: string;
  /** Account that owns this webhook destination. */
  accountId: string;
  /** Name of the webhook destination. */
  name: string;
  /** The POST endpoint called when dispatching a notification. */
  url: string;
  /** Endpoint type inferred by Cloudflare from the URL (e.g. `generic`, `slack`). */
  type: NotificationWebhookType | undefined;
  /** ISO8601 creation timestamp. */
  createdAt: string | undefined;
}

export type NotificationWebhook = Resource<
  TypeId,
  NotificationWebhookProps,
  NotificationWebhookAttributes,
  never,
  Providers
>;

/**
 * A Cloudflare Notifications webhook destination.
 *
 * Webhook destinations receive alert notifications dispatched by
 * {@link NotificationPolicy | notification policies}. Cloudflare sends a
 * test POST to the URL when the webhook is created or updated, so the
 * endpoint must be live and respond with a 2xx.
 * ### Creating a Webhook destination
 * **Example:** Generic webhook with a generated name
 * ```typescript
 * const webhook = yield* Cloudflare.Alerting.NotificationWebhook("AlertsHook", {
 *   url: "https://alerts.example.com/cf",
 * });
 * ```
 *
 * **Example:** Webhook with an auth secret
 * The secret is sent in the `cf-webhook-auth` header on every dispatch.
 * ```typescript
 * const webhook = yield* Cloudflare.Alerting.NotificationWebhook("AlertsHook", {
 *   name: "production-alerts",
 *   url: "https://alerts.example.com/cf",
 *   secret: yield* Config.Redacted("WEBHOOK_SECRET"),
 * });
 * ```
 *
 * ### Using with a Notification policy
 * **Example:** Dispatch policy notifications to the webhook
 * ```typescript
 * yield* Cloudflare.Alerting.NotificationPolicy("SslAlerts", {
 *   alertType: "universal_ssl_event_type",
 *   mechanisms: { webhooks: [{ id: webhook.webhookId }] },
 * });
 * ```
 *
 * @see https://developers.cloudflare.com/notifications/get-started/configure-webhooks/
 *
 * @resource
 * @product Alerting
 * @category Observability & Analytics
 */
export const NotificationWebhook = Resource<NotificationWebhook>(TypeId);

/**
 * Returns true if the given value is a NotificationWebhook resource.
 */
export const isNotificationWebhook = (value: unknown): value is NotificationWebhook =>
  Predicate.hasProperty(value, "Type") && value.Type === TypeId;

export const NotificationWebhookProvider = () =>
  Provider.succeed(NotificationWebhook, {
    stables: ["webhookId", "accountId"],

    // Account collection (pattern b): enumerate every webhook destination in
    // the account and hydrate each into the same Attributes shape `read`
    // returns. The secret is write-only (never returned by Cloudflare), so it
    // is absent from Attributes and there is nothing extra to fetch per item.
    list: Effect.fn(function* () {
      const { accountId } = yield* yield* CloudflareEnvironment;
      return yield* alerting.listDestinationWebhooks.pages({ accountId }).pipe(
        Stream.runCollect,
        Effect.map((chunk) =>
          Array.from(chunk).flatMap((page) =>
            (page.result ?? [])
              .map(narrowWebhook)
              .filter((w): w is ObservedWebhook => w !== undefined)
              .map((w) => toWebhookAttributes(w, accountId)),
          ),
        ),
      );
    }),

    diff: Effect.fn(function* ({ output }) {
      const { accountId } = yield* yield* CloudflareEnvironment;
      if ((output?.accountId ?? accountId) !== accountId) {
        return { action: "replace" } as const;
      }
    }),

    read: Effect.fn(function* ({ id, output, olds }) {
      const { accountId } = yield* yield* CloudflareEnvironment;
      const acct = output?.accountId ?? accountId;

      // Owned path: refresh by the persisted webhook id.
      if (output?.webhookId) {
        const observed = yield* observeWebhook(acct, output.webhookId);
        if (observed) return toWebhookAttributes(observed, acct);
      }

      // Cold read: no persisted id (state-persistence failure) — find the
      // deterministic physical name in the account's webhook list.
      const name = yield* createWebhookName(id, olds?.name);
      const match = yield* findWebhookByName(acct, name);
      if (match) return toWebhookAttributes(match, acct);
      return undefined;
    }),

    reconcile: Effect.fn(function* ({ id, news, output, olds }) {
      const { accountId } = yield* yield* CloudflareEnvironment;
      const name = yield* createWebhookName(id, news.name);
      // Inputs are resolved to concrete values by the engine before
      // reconcile runs.
      const url = news.url as string;
      const secret = news.secret === undefined ? undefined : Redacted.value(news.secret);

      // 1. Observe — by cached id first, then by deterministic name.
      let observed: ObservedWebhook | undefined;
      if (output?.webhookId) {
        observed = yield* observeWebhook(accountId, output.webhookId);
      }
      if (!observed) {
        observed = yield* findWebhookByName(accountId, name);
      }

      // 2. Ensure — create when missing. Cloudflare fires a test POST at
      //    the URL from an arbitrary PoP; when the destination is a
      //    just-deployed Worker that PoP may not have the fresh
      //    workers.dev subdomain yet and the test POST 404s even though
      //    the URL serves elsewhere. A bounded retry (~2 min, capped
      //    backoff) rides out edge propagation — fresh workers.dev URLs
      //    have been observed to 404 for well over a minute under heavy
      //    account-wide deploy load; a genuinely broken endpoint still
      //    fails after the budget is exhausted.
      if (!observed) {
        const created = yield* alerting
          .createDestinationWebhook({
            accountId,
            name,
            url,
            secret,
          })
          .pipe(
            Effect.retry({
              while: (e) => e._tag === "WebhookTestFailed",
              schedule: Schedule.max([
                Schedule.min([Schedule.exponential("1 second"), Schedule.spaced("5 seconds")]),
                Schedule.recurs(24),
              ]),
            }),
          );
        if (!created.id) {
          return yield* new WebhookUnexpectedResponse({
            message: "Cloudflare did not return an id for the created webhook destination",
          });
        }
        const fresh = yield* observeWebhook(accountId, created.id);
        return toWebhookAttributes(fresh ?? { id: created.id }, accountId);
      }

      // 3. Sync — PUT the full desired body when any observable field
      //    drifts, or when the (write-only, unobservable) secret prop
      //    changed between olds and news.
      const oldSecret = olds?.secret === undefined ? undefined : Redacted.value(olds.secret);
      const secretChanged = secret !== oldSecret;
      if (observed.name !== name || observed.url !== url || secretChanged) {
        // The update PUT fires the same test POST as create — ride out edge
        // propagation of a just-deployed destination URL the same way.
        yield* alerting
          .updateDestinationWebhook({
            accountId,
            webhookId: observed.id,
            name,
            url,
            secret,
          })
          .pipe(
            Effect.retry({
              while: (e) => e._tag === "WebhookTestFailed",
              schedule: Schedule.max([Schedule.exponential("1 second"), Schedule.recurs(5)]),
            }),
          );
        const fresh = yield* observeWebhook(accountId, observed.id);
        return toWebhookAttributes(fresh ?? observed, accountId);
      }

      // 4. Return.
      return toWebhookAttributes(observed, accountId);
    }),

    delete: Effect.fn(function* ({ output }) {
      // Cloudflare answers `deleteDestinationWebhook` for a webhook that no
      // longer exists with a generic `InternalServerError` (code 15000)
      // rather than a not-found error. Since that envelope is
      // indistinguishable from a genuine server fault, catch the typed tag
      // and verify the webhook is actually gone: `WebhookNotFound` on the
      // follow-up read confirms idempotent success; anything still present
      // re-fails with the original error.
      yield* alerting
        .deleteDestinationWebhook({
          accountId: output.accountId,
          webhookId: output.webhookId,
        })
        .pipe(
          Effect.catchTag("InternalServerError", (e) =>
            observeWebhook(output.accountId, output.webhookId).pipe(
              Effect.flatMap((observed) => (observed === undefined ? Effect.void : Effect.fail(e))),
            ),
          ),
        );
    }),
  });

interface ObservedWebhook {
  readonly id: string;
  readonly name?: string;
  readonly url?: string;
  readonly type?: NotificationWebhookType;
  readonly createdAt?: string;
}

const undef = <T>(v: T | null | undefined): T | undefined => (v == null ? undefined : v);

const narrowWebhook = (raw: {
  id?: string | null;
  name?: string | null;
  url?: string | null;
  type?: string | null;
  createdAt?: string | null;
}): ObservedWebhook | undefined =>
  raw.id == null
    ? undefined
    : {
        id: raw.id,
        name: undef(raw.name),
        url: undef(raw.url),
        type: undef(raw.type) as NotificationWebhookType | undefined,
        createdAt: undef(raw.createdAt),
      };

const observeWebhook = (accountId: string, webhookId: string) =>
  alerting.getDestinationWebhook({ accountId, webhookId }).pipe(
    Effect.map((w) => narrowWebhook({ ...w, id: w.id ?? webhookId })),
    Effect.catchTag("WebhookNotFound", () => Effect.undefined),
  );

const findWebhookByName = (accountId: string, name: string) =>
  alerting.listDestinationWebhooks.items({ accountId }).pipe(
    Stream.filter((w) => w.name === name && w.id != null),
    Stream.runHead,
    Effect.map(Option.getOrUndefined),
    Effect.map((w) => (w === undefined ? undefined : narrowWebhook(w))),
  );

const toWebhookAttributes = (
  observed: ObservedWebhook,
  accountId: string,
): NotificationWebhookAttributes => ({
  webhookId: observed.id,
  accountId,
  name: observed.name ?? "",
  url: observed.url ?? "",
  type: observed.type,
  createdAt: observed.createdAt,
});

const createWebhookName = (id: string, name: string | undefined) =>
  Effect.gen(function* () {
    return name ?? (yield* createPhysicalName({ id, lowercase: true }));
  });