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

import * as alerting from "@distilled.cloud/cloudflare/alerting";
import { Unowned } from "alchemy/AdoptPolicy";
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 Schedule from "effect/Schedule";
import * as Stream from "effect/Stream";
import { CloudflareEnvironment } from "../CloudflareEnvironment.ts";
import type { Providers } from "../Providers.ts";

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

export interface SilenceProps {
  /**
   * The notification policy to silence. References a
   * {@link NotificationPolicy} id. Changing the policy triggers a
   * replacement — the silence update API cannot move a silence to a
   * different policy.
   */
  policyId: string;
  /**
   * When the silence window starts, as an RFC3339/ISO8601 timestamp (e.g.
   * `2026-07-01T00:00:00Z`). Must be within 90 days of now — Cloudflare
   * rejects windows further out with `InvalidSilence`. Pass an explicit,
   * deterministic value; the provider never derives times from the clock.
   * Mutable — updated in place.
   */
  startTime: string;
  /**
   * When the silence window ends, as an RFC3339/ISO8601 timestamp. Must be
   * after `startTime` (`InvalidSilence` otherwise).
   * Mutable — updated in place.
   */
  endTime: string;
}

export interface SilenceAttributes {
  /** Cloudflare-assigned silence id. */
  silenceId: string;
  /** Account that owns this silence. */
  accountId: string;
  /** The notification policy this silence applies to. */
  policyId: string;
  /** When the silence window starts (ISO8601). */
  startTime: string;
  /** When the silence window ends (ISO8601). */
  endTime: string;
  /** ISO8601 creation timestamp. */
  createdAt: string | undefined;
  /** ISO8601 last-modified timestamp. */
  updatedAt: string | undefined;
}

export type Silence = Resource<TypeId, SilenceProps, SilenceAttributes, never, Providers>;

/**
 * A Cloudflare Notifications silence window.
 *
 * A silence suppresses notification dispatches for a
 * {@link NotificationPolicy} between `startTime` and `endTime` — e.g.
 * during a planned maintenance window. The window times are explicit
 * ISO8601 props supplied by you; Cloudflare requires the start time to be
 * within 90 days of now.
 *
 * Note: the create API returns no id, so the provider resolves the created
 * silence by listing and matching on `(policyId, startTime, endTime)`. Two
 * silences sharing the exact same policy and window are indistinguishable.
 * ### Creating a silence
 * **Example:** Silence a policy during a maintenance window
 * ```typescript
 * const policy = yield* Cloudflare.Alerting.NotificationPolicy("SslAlerts", {
 *   alertType: "universal_ssl_event_type",
 *   mechanisms: { email: [{ id: "ops@example.com" }] },
 * });
 *
 * yield* Cloudflare.Alerting.Silence("MaintenanceWindow", {
 *   policyId: policy.policyId,
 *   startTime: "2026-07-01T00:00:00Z",
 *   endTime: "2026-07-01T04:00:00Z",
 * });
 * ```
 *
 * ### Updating the window
 * **Example:** Extend the silence end time in place
 * Window times are mutable — changing them updates the existing silence.
 * ```typescript
 * yield* Cloudflare.Alerting.Silence("MaintenanceWindow", {
 *   policyId: policy.policyId,
 *   startTime: "2026-07-01T00:00:00Z",
 *   endTime: "2026-07-01T08:00:00Z",
 * });
 * ```
 *
 * @see https://developers.cloudflare.com/notifications/
 *
 * @resource
 * @product Alerting
 * @category Observability & Analytics
 */
export const Silence = Resource<Silence>(TypeId);

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

export const SilenceProvider = () =>
  Provider.succeed(Silence, {
    stables: ["silenceId", "accountId", "policyId", "createdAt"],

    // Silences are account-scoped; listSilences enumerates every silence in
    // the account and the response carries the full attribute shape, so no
    // per-item hydration is needed.
    list: Effect.fn(function* () {
      const { accountId } = yield* yield* CloudflareEnvironment;
      return yield* alerting.listSilences.pages({ accountId }).pipe(
        Stream.runCollect,
        Effect.map((chunk) =>
          Array.from(chunk).flatMap((page) =>
            (page.result ?? [])
              .map(narrowSilence)
              .filter((s): s is ObservedSilence => s !== undefined)
              .map((s) => toSilenceAttributes(s, accountId)),
          ),
        ),
      );
    }),

    diff: Effect.fn(function* ({ olds = {}, news, output }) {
      const { accountId } = yield* yield* CloudflareEnvironment;
      if ((output?.accountId ?? accountId) !== accountId) {
        return { action: "replace" } as const;
      }
      // The silence update body carries no policyId — a silence cannot be
      // moved to a different policy, so a policy change is a replacement.
      // policyId is Input<string>; compare only once both are concrete.
      const o = olds as SilenceProps;
      const n = news as SilenceProps;
      const oldPolicyId =
        output?.policyId ?? (typeof o.policyId === "string" ? o.policyId : undefined);
      if (
        oldPolicyId !== undefined &&
        typeof n.policyId === "string" &&
        oldPolicyId !== n.policyId
      ) {
        return { action: "replace" } as const;
      }
    }),

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

      // Owned path: refresh by the persisted silence id.
      if (output?.silenceId) {
        const observed = yield* observeSilence(acct, output.silenceId);
        if (observed) return toSilenceAttributes(observed, acct);
        return undefined;
      }

      // Cold read: no persisted id (state-persistence failure) — match on
      // the silence identity `(policyId, startTime, endTime)`. Silences
      // carry no ownership markers, so we cannot prove we created a match:
      // brand it `Unowned` so the engine gates takeover behind adoption.
      const o = olds as SilenceProps | undefined;
      const policyId = typeof o?.policyId === "string" ? o.policyId : undefined;
      if (policyId && o?.startTime && o?.endTime) {
        const match = yield* findSilence(acct, policyId, o.startTime, o.endTime);
        if (match) return Unowned(toSilenceAttributes(match, acct));
      }
      return undefined;
    }),

    reconcile: Effect.fn(function* ({ news, output }) {
      const { accountId } = yield* yield* CloudflareEnvironment;
      // Inputs are resolved to concrete values by the engine before
      // reconcile runs.
      const policyId = news.policyId as string;

      // 1. Observe — by cached id first, then by silence identity.
      let observed: ObservedSilence | undefined;
      if (output?.silenceId) {
        observed = yield* observeSilence(accountId, output.silenceId);
      }
      if (!observed) {
        observed = yield* findSilence(accountId, policyId, news.startTime, news.endTime);
      }

      // 2. Ensure — create when missing. The create response carries no
      //    id, so resolve the created silence by listing and matching on
      //    `(policyId, startTime, endTime)` with a short bounded retry for
      //    read-after-write consistency. A concurrent create of the same
      //    window surfaces as `SilenceAlreadyExists`: converge by reusing
      //    the silence that won the race.
      if (!observed) {
        yield* alerting
          .createSilence({
            accountId,
            body: [
              {
                policyId,
                startTime: news.startTime,
                endTime: news.endTime,
              },
            ],
          })
          .pipe(
            Effect.catchTag("SilenceAlreadyExists", (error) =>
              findSilence(accountId, policyId, news.startTime, news.endTime).pipe(
                Effect.flatMap((existing) => (existing ? Effect.void : Effect.fail(error))),
              ),
            ),
          );
        observed = yield* findSilence(accountId, policyId, news.startTime, news.endTime).pipe(
          Effect.flatMap((found) =>
            found ? Effect.succeed(found) : Effect.fail(new SilencePending()),
          ),
          Effect.retry({
            while: (e) => e._tag === "SilencePending",
            schedule: Schedule.max([Schedule.exponential("500 millis"), Schedule.recurs(8)]),
          }),
        );
        return toSilenceAttributes(observed, accountId);
      }

      // 3. Sync — diff the observed window against the desired one
      //    (instant-equal, so `00:00:00Z` matches `00:00:00+00:00`) and
      //    PUT only on drift.
      if (
        !sameInstant(observed.startTime, news.startTime) ||
        !sameInstant(observed.endTime, news.endTime)
      ) {
        yield* alerting.updateSilence({
          accountId,
          body: [
            {
              id: observed.id,
              startTime: news.startTime,
              endTime: news.endTime,
            },
          ],
        });
        const fresh = yield* observeSilence(accountId, observed.id);
        return toSilenceAttributes(fresh ?? observed, accountId);
      }

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

    delete: Effect.fn(function* ({ output }) {
      yield* alerting
        .deleteSilence({
          accountId: output.accountId,
          silenceId: output.silenceId,
        })
        .pipe(Effect.catchTag("SilenceNotFound", () => Effect.void));
    }),
  });

/** Created silence not yet visible in the list — retried internally. */
class SilencePending extends Data.TaggedError("SilencePending") {}

interface ObservedSilence {
  readonly id: string;
  readonly policyId?: string;
  readonly startTime?: string;
  readonly endTime?: string;
  readonly createdAt?: string;
  readonly updatedAt?: string;
}

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

const narrowSilence = (raw: {
  id?: string | null;
  policyId?: string | null;
  startTime?: string | null;
  endTime?: string | null;
  createdAt?: string | null;
  updatedAt?: string | null;
}): ObservedSilence | undefined =>
  raw.id == null
    ? undefined
    : {
        id: raw.id,
        policyId: undef(raw.policyId),
        startTime: undef(raw.startTime),
        endTime: undef(raw.endTime),
        createdAt: undef(raw.createdAt),
        updatedAt: undef(raw.updatedAt),
      };

const observeSilence = (accountId: string, silenceId: string) =>
  alerting.getSilence({ accountId, silenceId }).pipe(
    Effect.map((s) => narrowSilence({ ...s, id: s.id ?? silenceId })),
    Effect.catchTag("SilenceNotFound", () => Effect.undefined),
  );

/**
 * Locate a silence by its identity `(policyId, startTime, endTime)`.
 * Timestamps are compared as instants so formatting differences (trailing
 * `Z` vs `+00:00`, fractional seconds) don't defeat the match.
 */
const findSilence = (accountId: string, policyId: string, startTime: string, endTime: string) =>
  alerting.listSilences.items({ accountId }).pipe(
    Stream.filter(
      (s) =>
        s.id != null &&
        s.policyId === policyId &&
        sameInstant(undef(s.startTime), startTime) &&
        sameInstant(undef(s.endTime), endTime),
    ),
    Stream.runHead,
    Effect.map(Option.getOrUndefined),
    Effect.map((s) => (s === undefined ? undefined : narrowSilence(s))),
  );

/** Compare two ISO8601 timestamps by the instant they denote. */
const sameInstant = (a: string | undefined, b: string | undefined): boolean => {
  if (a === undefined || b === undefined) return a === b;
  const ta = Date.parse(a);
  const tb = Date.parse(b);
  if (Number.isNaN(ta) || Number.isNaN(tb)) return a === b;
  return ta === tb;
};

const toSilenceAttributes = (observed: ObservedSilence, accountId: string): SilenceAttributes => ({
  silenceId: observed.id,
  accountId,
  policyId: observed.policyId ?? "",
  startTime: observed.startTime ?? "",
  endTime: observed.endTime ?? "",
  createdAt: observed.createdAt,
  updatedAt: observed.updatedAt,
});