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

import { sanitizeKey, type RuntimeContext } from "alchemy/RuntimeContext";
import * as Context from "effect/Context";
import type * as Effect from "effect/Effect";
import type * as Redacted from "effect/Redacted";
import type { CustomAlert } from "./CustomAlert.ts";
import type { AlertType, NotificationPolicy } from "./NotificationPolicy.ts";

/**
 * Whether a notification opens or closes an incident. Alert types without
 * incidents leave it unset.
 */
export type NotificationAlertEvent =
  | "ALERT_STATE_EVENT_START"
  | "ALERT_STATE_EVENT_END"
  // Keep the union open so new Cloudflare states aren't blocked by stale types.
  | (string & {});

/**
 * One notification Cloudflare dispatched for a policy: the generic webhook
 * envelope, with the alert-specific payload in `data`.
 *
 * @see {@link https://developers.cloudflare.com/notifications/reference/webhook-payload-schema/ | Webhook payload schema}
 */
export interface Notification<Data = Record<string, unknown>> {
  /** Name of the webhook destination that received the notification. */
  readonly name: string;
  /** Human-readable summary of the alert. */
  readonly text: string;
  /** Alert-specific payload. Its shape depends on `alertType`. */
  readonly data: Data;
  /** When Cloudflare generated the notification, in Unix seconds (UTC). */
  readonly ts: number;
  /** Account the alert fired in. Not sent by every alert type. */
  readonly accountId: string | undefined;
  /** Id of the policy that fired. Not sent by every alert type. */
  readonly policyId: string | undefined;
  /** Name of the policy that fired. */
  readonly policyName: string | undefined;
  /** The alert type that fired, e.g. `workers_observability_real_time_issue`. */
  readonly alertType: AlertType | undefined;
  /** Ties together the notifications of one incident. */
  readonly alertCorrelationId: string | undefined;
  /** Whether this notification opens or closes an incident. */
  readonly alertEvent: NotificationAlertEvent | undefined;
}

/** A policy whose notifications a runtime can consume. */
export type NotifyingPolicy = NotificationPolicy | CustomAlert;

export interface ConsumeNotificationsProps {
  /**
   * Secret Cloudflare sends in the `cf-webhook-auth` header of every
   * notification. Requests without it are rejected. When omitted, a random
   * secret is generated at deploy and bound onto the host.
   */
  secret?: Redacted.Redacted<string>;
  /**
   * Path on the host that Cloudflare delivers to. Defaults to a deterministic
   * per-policy path, so deliveries don't collide with your application
   * routes.
   */
  path?: string;
}

/**
 * Run an Effect for every notification a policy fires.
 *
 * Call it in the Construction phase of any runtime that receives HTTP (a
 * `WebhookHost`, such as a Cloudflare Worker). Cloudflare then delivers the
 * policy's notifications to that runtime: the event source creates a webhook
 * destination at the runtime's URL and adds it to the policy, so the policy
 * needs no `mechanisms` of its own.
 *
 * **Example:** Open a GitHub issue for each new Worker issue
 * ```typescript
 * const policy = yield* Cloudflare.Alerting.NotificationPolicy("IssuePolicy", {
 *   alertType: "workers_observability_real_time_issue",
 * });
 *
 * // `text` is Cloudflare's report: a summary line, then details and links.
 * const createIssue = yield* GitHub.CreateIssue(yield* Repo);
 * yield* Cloudflare.Alerting.consumeNotifications(policy, (notification) =>
 *   createIssue({
 *     title: notification.text.split("\n")[0],
 *     body: notification.text,
 *   }),
 * );
 * ```
 *
 * **Example:** Page on a SQL custom alert, with your own secret
 * ```typescript
 * const errors = yield* ErrorSpike; // a Cloudflare.Alerting.CustomAlert
 *
 * yield* Cloudflare.Alerting.consumeNotifications(
 *   errors,
 *   { secret: yield* Config.Redacted("ALERT_WEBHOOK_SECRET") },
 *   (notification) =>
 *     notification.alertEvent === "ALERT_STATE_EVENT_END"
 *       ? pager.resolve(notification.alertCorrelationId)
 *       : pager.trigger(notification.alertCorrelationId, notification.text),
 * );
 * ```
 *
 * @binding
 * @product Alerting
 */
export function consumeNotifications<Req = never>(
  policy: NotifyingPolicy,
  process: (notification: Notification) => Effect.Effect<void, never, Req | RuntimeContext>,
): Effect.Effect<void, never, NotificationEventSource>;
export function consumeNotifications<Req = never>(
  policy: NotifyingPolicy,
  props: ConsumeNotificationsProps,
  process: (notification: Notification) => Effect.Effect<void, never, Req | RuntimeContext>,
): Effect.Effect<void, never, NotificationEventSource>;
export function consumeNotifications(
  policy: NotifyingPolicy,
  propsOrProcess:
    | ConsumeNotificationsProps
    | ((notification: Notification) => Effect.Effect<void, never, any>),
  maybeProcess?: (notification: Notification) => Effect.Effect<void, never, any>,
): Effect.Effect<void, never, NotificationEventSource> {
  const [props, process] =
    typeof propsOrProcess === "function" ? [{}, propsOrProcess] : [propsOrProcess, maybeProcess!];
  return NotificationEventSource.use((source) => source(policy, props, process));
}

export type NotificationEventSourceService = <Req = never>(
  policy: NotifyingPolicy,
  props: ConsumeNotificationsProps,
  process: (notification: Notification) => Effect.Effect<void, never, Req>,
) => Effect.Effect<void, never, never>;

export class NotificationEventSource extends Context.Service<
  NotificationEventSource,
  NotificationEventSourceService
>()("Cloudflare.Alerting.NotificationEventSource") {}

/**
 * Delivery path of a policy's notifications. Shared by the deploy-time half
 * (the webhook URL) and the runtime half (the claimed route).
 */
export const notificationPath = (
  policy: Pick<NotifyingPolicy, "LogicalId">,
  props: Pick<ConsumeNotificationsProps, "path"> = {},
): string =>
  props.path ?? `/__alchemy/cloudflare/notifications/${encodeURIComponent(policy.LogicalId)}`;

/** Env var under which the host holds a policy's webhook secret. */
export const notificationSecretEnvName = (policy: Pick<NotifyingPolicy, "LogicalId">): string =>
  `ALCHEMY_CLOUDFLARE_NOTIFICATION_SECRET_${sanitizeKey(policy.LogicalId)}`;