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

import * as alerting from "@distilled.cloud/cloudflare/alerting";
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 Predicate from "effect/Predicate";
import * as Stream from "effect/Stream";
import { CloudflareEnvironment } from "../CloudflareEnvironment.ts";
import type { Providers } from "../Providers.ts";
import {
  boundMechanisms,
  createPolicyName,
  findPolicyByName,
  narrowPolicy,
  type NotificationPolicyBinding,
  type ObservedPolicy,
  observePolicy,
  type PolicyBody,
  policyEqualsObserved,
} from "./internal.ts";
import type { NotificationPolicyMechanisms } from "./NotificationPolicy.ts";

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

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

/**
 * A time window in minutes or hours, at least one minute (e.g. `"5m"`,
 * `"1h"`).
 */
export type CustomAlertWindow = `${number}m` | `${number}h`;

/**
 * Fire when the query result crosses a fixed value.
 */
export interface CustomAlertThresholdTrigger {
  type: "threshold";
  /** How the query result is compared to `value`. */
  operator: "<" | ">" | "<=" | ">=" | "==" | "!=";
  /** The value the query result is compared to. */
  value: number;
  /** The time range the query covers on each evaluation. */
  window: CustomAlertWindow;
  /** Don't fire while the query result is below this value. */
  minimumThreshold?: number;
}

/**
 * Fire when the query result moves away from its recent baseline.
 */
export interface CustomAlertAnomalyTrigger {
  type: "anomaly";
  /** Fire on spikes, drops, or both. */
  direction: "spike" | "drop" | "both";
  /** How many standard deviations from the baseline count as an anomaly. */
  zScore: number;
  /** The time range the query covers on each evaluation. */
  window: CustomAlertWindow;
  /** The longer time range the baseline is computed over. */
  baselineWindow: CustomAlertWindow;
  /** Don't fire while the query result is below this value. */
  minimumThreshold?: number;
}

/**
 * Fire when the query result falls below a service level objective,
 * checked over a short and a long window.
 */
export interface CustomAlertSloTrigger {
  type: "slo";
  /** The objective the query result is held to (e.g. `99.9`). */
  target: number;
  /** The short window the objective is checked over. */
  shortWindow: CustomAlertWindow;
  /** The long window the objective is checked over. */
  longWindow: CustomAlertWindow;
  /** Don't fire while the query result is below this value. */
  minimumThreshold?: number;
}

/**
 * When a custom alert fires.
 */
export type CustomAlertTrigger =
  | CustomAlertThresholdTrigger
  | CustomAlertAnomalyTrigger
  | CustomAlertSloTrigger;

export interface CustomAlertProps {
  /**
   * Name of the alert. If omitted, a unique name is generated.
   * Mutable — renames are applied in place.
   * @default ${app}-${id}-${stage}-${suffix}
   */
  name?: string;
  /**
   * Optional human-readable description of the alert.
   */
  description?: string;
  /**
   * A [SQL API](https://developers.cloudflare.com/analytics/sql-api/) query
   * returning the number the trigger evaluates, e.g.
   * `SELECT count() AS value FROM logs.workersLogs WHERE …`. The query must
   * scope itself to the account (`accountTag = '…'`). Cloudflare checks
   * it when the alert is saved and rejects it with `InvalidAlertQuery`.
   */
  query: string;
  /** When the alert fires. */
  trigger: CustomAlertTrigger;
  /**
   * How often Cloudflare runs the query.
   * @default "1m"
   */
  every?: CustomAlertWindow;
  /**
   * Destinations notified when the alert fires. At least one destination is
   * required, either declared here or bound by a runtime that consumes the
   * alert's notifications (`Cloudflare.Alerting.consumeNotifications`).
   */
  mechanisms?: NotificationPolicyMechanisms;
  /**
   * How often to re-alert while the alert keeps firing (e.g. `"30m"`).
   */
  alertInterval?: string;
  /**
   * Whether the alert is enabled.
   * @default true
   */
  enabled?: boolean;
}

export interface CustomAlertAttributes {
  /** Cloudflare-assigned notification policy UUID. */
  policyId: string;
  /** Account that owns this alert. */
  accountId: string;
  /** Name of the alert. */
  name: string;
  /** Whether the alert is enabled. */
  enabled: boolean;
  /** ISO8601 creation timestamp. */
  created: string | undefined;
  /** ISO8601 last-modified timestamp. */
  modified: string | undefined;
}

export type CustomAlert = Resource<
  TypeId,
  CustomAlertProps,
  CustomAlertAttributes,
  NotificationPolicyBinding,
  Providers
>;

/**
 * A Cloudflare custom alert: a SQL query Cloudflare runs on a schedule,
 * with a trigger that decides when to notify.
 *
 * The query runs against the
 * [SQL API](https://developers.cloudflare.com/analytics/sql-api/), so it
 * can read Workers logs and traces, HTTP requests, Analytics Engine
 * datasets and the other analytics datasets. Notifications go to the same
 * destinations as a `NotificationPolicy` (email, webhooks, PagerDuty).
 * ### Alerting on a threshold
 * **Example:** Alert when a Worker logs more than 100 errors in 5 minutes
 * ```typescript
 * yield* Cloudflare.Alerting.CustomAlert("ErrorSpike", {
 *   query: `SELECT count() AS value FROM logs.workersLogs
 *           WHERE accountTag = '${accountId}' AND level = 'error'`,
 *   trigger: { type: "threshold", operator: ">", value: 100, window: "5m" },
 *   every: "5m",
 *   mechanisms: { email: [{ id: "ops@example.com" }] },
 * });
 * ```
 *
 * ### Alerting on anomalies
 * **Example:** Alert when request volume spikes or drops
 * ```typescript
 * yield* Cloudflare.Alerting.CustomAlert("TrafficAnomaly", {
 *   query: `SELECT count() AS value FROM events.httpRequests
 *           WHERE accountTag = '${accountId}'`,
 *   trigger: {
 *     type: "anomaly",
 *     direction: "both",
 *     zScore: 3,
 *     window: "5m",
 *     baselineWindow: "1h",
 *   },
 *   mechanisms: { webhooks: [{ id: webhook.webhookId }] },
 * });
 * ```
 *
 * ### Alerting on an SLO
 * **Example:** Alert when the success rate drops below 99.9%
 * ```typescript
 * yield* Cloudflare.Alerting.CustomAlert("Availability", {
 *   query: `SELECT 100 * countIf(httpStatus < 500) / count() AS value
 *           FROM logs.workersLogs WHERE accountTag = '${accountId}'`,
 *   trigger: { type: "slo", target: 99.9, shortWindow: "5m", longWindow: "1h" },
 *   mechanisms: { pagerduty: [{ id: pagerDutyId }] },
 * });
 * ```
 *
 * @see https://developers.cloudflare.com/notifications/
 *
 * @resource
 * @product Alerting
 * @category Observability & Analytics
 */
export const CustomAlert = Resource<CustomAlert>(TypeId);

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

export const CustomAlertProvider = () =>
  Provider.succeed(CustomAlert, {
    stables: ["policyId", "accountId"],

    // Account-scoped collection: the account's `custom_analytics` policies.
    list: Effect.fn(function* () {
      const { accountId } = yield* yield* CloudflareEnvironment;
      return yield* alerting.listPolicies.items({ accountId }).pipe(
        Stream.filter((p) => p.alertType === "custom_analytics"),
        Stream.runCollect,
        Effect.map((chunk) =>
          Array.from(chunk)
            .map(narrowPolicy)
            .filter((p): p is ObservedPolicy => p !== undefined)
            .map((p) => toAttributes(p, 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 policy id.
      if (output?.policyId) {
        const observed = yield* observePolicy(acct, output.policyId);
        return observed ? toAttributes(observed, acct) : undefined;
      }

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

    reconcile: Effect.fn(function* ({ id, news, output, bindings }) {
      const { accountId } = yield* yield* CloudflareEnvironment;
      const name = yield* createPolicyName(id, news.name ?? output?.name);
      const desired = buildBody(name, news, bindings);

      // 1. Observe — by cached id first, then by deterministic name.
      let observed: ObservedPolicy | undefined;
      if (output?.policyId) {
        observed = yield* observePolicy(accountId, output.policyId);
      }
      if (!observed) {
        observed = yield* findPolicyByName(accountId, name);
      }

      // 2. Ensure — create when missing. `createPolicy` only returns the
      //    new id; re-read for the full attribute set.
      if (!observed) {
        const created = yield* alerting.createPolicy({ accountId, ...desired });
        if (!created.id) {
          return yield* new CustomAlertUnexpectedResponse({
            message: "Cloudflare did not return an id for the created custom alert",
          });
        }
        const fresh = yield* observePolicy(accountId, created.id);
        return toAttributes(fresh ?? { id: created.id, name }, accountId);
      }

      // 3. Sync — PUT the full desired body when anything drifts from the
      //    observed policy, filters included.
      if (!policyEqualsObserved(desired, observed)) {
        yield* alerting.updatePolicy({ accountId, policyId: observed.id, ...desired });
        const fresh = yield* observePolicy(accountId, observed.id);
        return toAttributes(fresh ?? observed, accountId);
      }

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

    delete: Effect.fn(function* ({ output }) {
      yield* alerting
        .deletePolicy({ accountId: output.accountId, policyId: output.policyId })
        .pipe(Effect.catchTag("PolicyNotFound", () => Effect.void));
    }),
  });

const buildBody = (
  name: string,
  news: CustomAlertProps,
  bindings: ReadonlyArray<{ data: NotificationPolicyBinding }>,
): PolicyBody => ({
  name,
  alertType: "custom_analytics",
  enabled: news.enabled ?? true,
  description: news.description,
  alertInterval: news.alertInterval,
  // `Input<string>` ids are resolved to concrete strings by the engine
  // before reconcile runs; bound webhooks extend the declared ones.
  mechanisms: boundMechanisms(news.mechanisms, bindings),
  filters: {
    source: ["sql_api"],
    selectors: [news.query],
    // Cloudflare stores 1m when omitted; send it so observed state matches.
    executionInterval: [news.every ?? "1m"],
    ...triggerFilters(news.trigger),
  },
});

const ZSCORE_ALGORITHMS = {
  spike: "zscore_spike",
  drop: "zscore_drop",
  both: "zscore_spike_and_drop",
} as const;

/**
 * Encode a trigger as the `alert_trigger_preferences*` filters. Anomaly
 * and SLO triggers only accept the `<` operator, so it is fixed here.
 */
const triggerFilters = (trigger: CustomAlertTrigger): NonNullable<PolicyBody["filters"]> => {
  const minimum =
    trigger.minimumThreshold === undefined
      ? {}
      : { alertTriggerPreferencesMinimumThreshold: [String(trigger.minimumThreshold)] };
  switch (trigger.type) {
    case "threshold":
      return {
        alertTriggerPreferences: ["threshold"],
        alertTriggerPreferencesOperator: [trigger.operator],
        alertTriggerPreferencesValue: [String(trigger.value)],
        alertTriggerPreferencesShortWindow: [trigger.window],
        ...minimum,
      };
    case "anomaly":
      return {
        alertTriggerPreferences: [ZSCORE_ALGORITHMS[trigger.direction]],
        alertTriggerPreferencesOperator: ["<"],
        alertTriggerPreferencesValue: [String(trigger.zScore)],
        alertTriggerPreferencesShortWindow: [trigger.window],
        alertTriggerPreferencesLongWindow: [trigger.baselineWindow],
        ...minimum,
      };
    case "slo":
      return {
        alertTriggerPreferences: ["slo"],
        alertTriggerPreferencesOperator: ["<"],
        alertTriggerPreferencesValue: [String(trigger.target)],
        alertTriggerPreferencesShortWindow: [trigger.shortWindow],
        alertTriggerPreferencesLongWindow: [trigger.longWindow],
        ...minimum,
      };
  }
};

const toAttributes = (observed: ObservedPolicy, accountId: string): CustomAlertAttributes => ({
  policyId: observed.id,
  accountId,
  name: observed.name ?? "",
  enabled: observed.enabled ?? true,
  created: observed.created,
  modified: observed.modified,
});