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

import * as healthchecks from "@distilled.cloud/cloudflare/healthchecks";
import { Unowned } from "alchemy/AdoptPolicy";
import { createPhysicalName } from "alchemy/PhysicalName";
import * as Provider from "alchemy/Provider";
import { Resource } from "alchemy/Resource";
import { arrayEqualsUnordered } from "alchemy/Util/equal";
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 Stream from "effect/Stream";
import { CloudflareEnvironment } from "../CloudflareEnvironment.ts";
import type { Providers } from "../Providers.ts";
import { listAllZones } from "../Zone/lookup.ts";

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

const TypeId = "Cloudflare.Healthcheck.Healthcheck" as const;
type TypeId = typeof TypeId;

/**
 * Protocol used by a standalone health check probe.
 */
export type Type = "HTTP" | "HTTPS" | "TCP";

/**
 * Region a health check can probe from. `null`/omitted lets Cloudflare pick
 * a default region; multiple regions require a Business or Enterprise plan.
 */
export type Region =
  | "WNAM"
  | "ENAM"
  | "WEU"
  | "EEU"
  | "NSAM"
  | "SSAM"
  | "OC"
  | "ME"
  | "NAF"
  | "SAF"
  | "IN"
  | "SEAS"
  | "NEAS"
  | "ALL_REGIONS";

/**
 * Health status Cloudflare reports for the monitored origin. New checks
 * start as `unknown` until the first probes complete.
 */
export type Status = "unknown" | "healthy" | "unhealthy" | "suspended";

/**
 * Parameters specific to an HTTP or HTTPS health check.
 */
export interface HttpConfig {
  /**
   * Do not validate the certificate when the health check uses HTTPS.
   * @default false
   */
  allowInsecure?: boolean;
  /**
   * A case-insensitive substring to look for in the response body. If this
   * string is not found, the origin will be marked as unhealthy.
   */
  expectedBody?: string;
  /**
   * The expected HTTP response codes (e.g. `"200"`) or code ranges
   * (e.g. `"2xx"`) of the health check.
   * @default ["200"]
   */
  expectedCodes?: string[];
  /**
   * Follow redirects if the origin returns a 3xx status code.
   * @default false
   */
  followRedirects?: boolean;
  /**
   * HTTP request headers to send in the health check. It is recommended to
   * set a `Host` header by default. The `User-Agent` header cannot be
   * overridden.
   */
  header?: Record<string, string[]>;
  /**
   * The HTTP method to use for the health check.
   * @default "GET"
   */
  method?: "GET" | "HEAD";
  /**
   * The endpoint path to health check against.
   * @default "/"
   */
  path?: string;
  /**
   * Port number to connect to for the health check.
   * @default 80 for HTTP, 443 for HTTPS
   */
  port?: number;
}

/**
 * Parameters specific to a TCP health check.
 */
export interface TcpConfig {
  /**
   * The TCP connection method to use for the health check.
   * @default "connection_established"
   */
  method?: "connection_established";
  /**
   * Port number to connect to for the health check.
   * @default 80
   */
  port?: number;
}

export interface Props {
  /**
   * Zone the health check belongs to. Stable — changing the zone triggers
   * a replacement.
   */
  zoneId: string;
  /**
   * A short name to identify the health check. Only alphanumeric
   * characters, hyphens and underscores are allowed. If omitted, a unique
   * name is generated from the app, stage, and logical ID.
   *
   * Mutable — Cloudflare supports renaming in place.
   * @default ${app}-${stage}-${id}
   */
  name?: string;
  /**
   * The hostname or IP address of the origin server to run health checks
   * on.
   */
  address: string;
  /**
   * The protocol to use for the health check. Currently supported
   * protocols are `HTTP`, `HTTPS` and `TCP`.
   * @default "HTTP"
   */
  type?: Type;
  /**
   * A human-readable description of the health check.
   */
  description?: string;
  /**
   * A list of regions from which to run health checks. Omitting it lets
   * Cloudflare pick a default region. Multiple regions require a Business
   * or Enterprise plan.
   */
  checkRegions?: Region[];
  /**
   * The number of consecutive fails required from a health check before
   * changing the health to unhealthy.
   * @default 1
   */
  consecutiveFails?: number;
  /**
   * The number of consecutive successes required from a health check
   * before changing the health to healthy.
   * @default 1
   */
  consecutiveSuccesses?: number;
  /**
   * The interval between each health check, in seconds. Shorter intervals
   * may give quicker notifications but increase load on the origin.
   * Plan-gated minimums apply (Pro: 60, Business: 15, Enterprise: 10).
   * @default 60
   */
  interval?: number;
  /**
   * The number of retries to attempt in case of a timeout before marking
   * the origin as unhealthy. Retries are attempted immediately.
   * @default 2
   */
  retries?: number;
  /**
   * The timeout (in seconds) before marking the health check as failed.
   * @default 5
   */
  timeout?: number;
  /**
   * If suspended, no health checks are sent to the origin.
   * @default false
   */
  suspended?: boolean;
  /**
   * Parameters specific to an HTTP or HTTPS health check. Only valid when
   * `type` is `HTTP` or `HTTPS`.
   */
  httpConfig?: HttpConfig;
  /**
   * Parameters specific to a TCP health check. Only valid when `type` is
   * `TCP`.
   */
  tcpConfig?: TcpConfig;
}

export interface Attributes {
  /** Cloudflare-assigned health check identifier. */
  healthcheckId: string;
  /** Zone that owns this health check. */
  zoneId: string;
  /** Health check name. */
  name: string;
  /** The hostname or IP address being monitored. */
  address: string;
  /** Probe protocol (`HTTP`, `HTTPS` or `TCP`). */
  type: Type;
  /** Current origin status according to the health check. */
  status: Status;
  /** The current failure reason if status is unhealthy. */
  failureReason: string | undefined;
  /** Whether probing is suspended. */
  suspended: boolean;
  /** Probe interval in seconds. */
  interval: number;
  /** Number of immediate retries on timeout. */
  retries: number;
  /** Probe timeout in seconds. */
  timeout: number;
  /** ISO8601 creation timestamp. */
  createdOn: string | undefined;
  /** ISO8601 last-modified timestamp. */
  modifiedOn: string | undefined;
}

export type Healthcheck = Resource<TypeId, Props, Attributes, never, Providers>;

/**
 * A Cloudflare standalone Health Check — monitors an origin server from
 * Cloudflare's edge and powers Health Check notifications and analytics.
 *
 * Zone-scoped and available on paid zone plans (Pro: 2 checks,
 * Business: 10, Enterprise: more). Distinct from Load Balancing
 * *Monitors*, which are account-scoped and attached to LB pools.
 *
 * Every property except `zoneId` is mutable in place (the API supports
 * full PUT updates, including renames); changing the zone triggers a
 * replacement.
 *
 * Safety: health checks carry no ownership markers, so when there is no
 * prior state `read` matches by deterministic name and reports an
 * existing check as `Unowned` — the engine refuses to take it over
 * unless `--adopt` (or `adopt(true)`) is set.
 * ### Creating a Health Check
 * **Example:** Basic HTTP health check
 * ```typescript
 * const check = yield* Cloudflare.Healthcheck.Healthcheck("origin-check", {
 *   zoneId: zone.zoneId,
 *   address: "origin.example.com",
 * });
 * ```
 *
 * **Example:** HTTPS health check with custom path and expected codes
 * ```typescript
 * const check = yield* Cloudflare.Healthcheck.Healthcheck("api-health", {
 *   zoneId: zone.zoneId,
 *   address: "api.example.com",
 *   type: "HTTPS",
 *   interval: 60,
 *   retries: 2,
 *   timeout: 5,
 *   httpConfig: {
 *     path: "/healthz",
 *     expectedCodes: ["200"],
 *     followRedirects: true,
 *   },
 * });
 * ```
 *
 * ### TCP health checks
 * **Example:** Probe a TCP port
 * ```typescript
 * const check = yield* Cloudflare.Healthcheck.Healthcheck("db-port", {
 *   zoneId: zone.zoneId,
 *   address: "db.example.com",
 *   type: "TCP",
 *   tcpConfig: { port: 5432 },
 * });
 * ```
 *
 * ### Suspending a check
 * **Example:** Temporarily stop probing the origin
 * ```typescript
 * const check = yield* Cloudflare.Healthcheck.Healthcheck("origin-check", {
 *   zoneId: zone.zoneId,
 *   address: "origin.example.com",
 *   suspended: true,
 * });
 * ```
 *
 * @see https://developers.cloudflare.com/health-checks/
 *
 * @resource
 * @product Health Checks
 * @category Performance & Reliability
 */
export const Healthcheck = Resource<Healthcheck>(TypeId, {
  aliases: ["Cloudflare.Healthcheck"],
});

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

export const HealthcheckProvider = () =>
  Provider.succeed(Healthcheck, {
    stables: ["healthcheckId", "zoneId", "createdOn"],

    diff: Effect.fn(function* ({ olds = {}, news }) {
      const o = olds as Props;
      const n = news as Props;
      // zoneId is Input<string>; by diff time both sides are concrete
      // strings when statically known.
      if (typeof o.zoneId === "string" && typeof n.zoneId === "string" && o.zoneId !== n.zoneId) {
        return { action: "replace" } as const;
      }
    }),

    read: Effect.fn(function* ({ id, output, olds }) {
      // Owned path: we have persisted state (our own id) — refresh it.
      if (output?.healthcheckId) {
        const observed = yield* getHealthcheck(output.zoneId, output.healthcheckId);
        if (observed) return toAttributes(observed, output.zoneId);
        return undefined;
      }
      // Adoption path: no state of our own, but a check with our
      // deterministic name may already exist. Health checks carry no
      // ownership markers we can inspect, so we cannot prove we created
      // it — brand it `Unowned` so the engine refuses to take over
      // unless `adopt` is set.
      const zoneId = olds?.zoneId as string | undefined;
      if (!zoneId) return undefined;
      const name = yield* createHealthcheckName(id, olds?.name);
      const match = yield* findByName(zoneId, name);
      if (match) {
        const attrs = toAttributes(match, zoneId);
        if (attrs) return Unowned(attrs);
      }
      return undefined;
    }),

    reconcile: Effect.fn(function* ({ id, news, output }) {
      // Inputs have been resolved to concrete strings by Plan.
      const zoneId = news.zoneId as string;
      const name = yield* createHealthcheckName(id, news.name);
      const desired = buildDesiredBody(news, name);

      // 1. Observe — the id cached on `output` is a hint, not a
      //    guarantee: a 404 falls through to "missing".
      let observed: ObservedHealthcheck | undefined;
      if (output?.healthcheckId) {
        observed = yield* getHealthcheck(zoneId, output.healthcheckId);
      }
      // Fall back to matching by name (names are unique per zone), which
      // also recovers from lost ids after the adopt gate has passed.
      if (!observed) {
        observed = yield* findByName(zoneId, name);
      }

      // 2. Ensure — create when missing; a concurrent create of the same
      //    name surfaces as `HealthcheckAlreadyExists`, which we treat as
      //    a race: re-read by name and converge via update below.
      let justCreated = false;
      if (!observed) {
        observed = yield* healthchecks.createHealthcheck({ zoneId, ...desired }).pipe(
          Effect.map((created): ObservedHealthcheck | undefined => created),
          Effect.catchTag("HealthcheckAlreadyExists", () => findByName(zoneId, name)),
        );
        justCreated = observed !== undefined;
      }

      // 3. Sync — the update endpoint is a PUT that takes the full body;
      //    diff observed cloud state against desired and skip the call
      //    entirely on a no-op.
      if (observed?.id && !justCreated && !desiredEqualsObserved(desired, observed)) {
        observed = yield* healthchecks.updateHealthcheck({
          zoneId,
          healthcheckId: observed.id,
          ...desired,
        });
      }

      // 4. Return.
      const attrs = observed ? toAttributes(observed, zoneId) : undefined;
      if (!attrs) {
        return yield* new HealthcheckUnexpectedResponse({
          message: `Cloudflare did not return a usable health check for "${name}"`,
        });
      }
      return attrs;
    }),

    delete: Effect.fn(function* ({ output }) {
      yield* healthchecks
        .deleteHealthcheck({
          zoneId: output.zoneId,
          healthcheckId: output.healthcheckId,
        })
        .pipe(
          // Already gone — deletion is idempotent.
          Effect.catchTag("HealthcheckNotFound", () => Effect.void),
        );
    }),

    // Health checks are zone-scoped (`/zones/{zone_id}/healthchecks`) with no
    // account-wide enumeration API, so fan out over every zone and list per
    // zone. A scoped token may lack permission on a zone (eventual consistency)
    // or a zone may be partially provisioned — skip those zones (-> []) rather
    // than failing the whole enumeration.
    list: Effect.fn(function* () {
      const { accountId } = yield* yield* CloudflareEnvironment;
      const zones = yield* listAllZones(accountId);
      const rows = yield* Effect.forEach(
        zones,
        (zone) =>
          healthchecks.listHealthchecks.pages({ zoneId: zone.id }).pipe(
            Stream.runCollect,
            Effect.map((chunk) =>
              Array.from(chunk).flatMap((page) =>
                (page.result ?? []).flatMap((h) => {
                  const attrs = toAttributes(h, zone.id);
                  return attrs ? [attrs] : [];
                }),
              ),
            ),
            Effect.catchTag("Forbidden", () => Effect.succeed([] as Attributes[])),
          ),
        { concurrency: 10 },
      );
      return rows.flat();
    }),
  });

type ObservedHealthcheck = healthchecks.GetHealthcheckResponse;

/**
 * Read a health check by id, mapping "gone" (`HealthcheckNotFound`,
 * HTTP 404) to `undefined`.
 */
const getHealthcheck = (zoneId: string, healthcheckId: string) =>
  healthchecks
    .getHealthcheck({ zoneId, healthcheckId })
    .pipe(Effect.catchTag("HealthcheckNotFound", () => Effect.undefined));

/**
 * Find a health check by exact name. Names are unique per zone, so the
 * first exact match is the resource.
 */
const findByName = (zoneId: string, name: string) =>
  healthchecks.listHealthchecks.items({ zoneId }).pipe(
    Stream.filter((h) => h.name === name),
    Stream.runHead,
    Effect.map((h): ObservedHealthcheck | undefined => Option.getOrUndefined(h)),
  );

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

interface DesiredBody {
  name: string;
  address: string;
  type: Type;
  description?: string;
  checkRegions?: Region[];
  consecutiveFails: number;
  consecutiveSuccesses: number;
  interval: number;
  retries: number;
  timeout: number;
  suspended: boolean;
  httpConfig?: HttpConfig;
  tcpConfig?: TcpConfig;
}

/**
 * The full desired body sent on both create and PUT update. Documented
 * Cloudflare defaults are filled in so the observed-vs-desired diff is
 * exact and removing a prop converges back to the default.
 */
const buildDesiredBody = (news: Props, name: string): DesiredBody => ({
  name,
  address: news.address,
  type: news.type ?? "HTTP",
  description: news.description ?? "",
  checkRegions: news.checkRegions,
  consecutiveFails: news.consecutiveFails ?? 1,
  consecutiveSuccesses: news.consecutiveSuccesses ?? 1,
  interval: news.interval ?? 60,
  retries: news.retries ?? 2,
  timeout: news.timeout ?? 5,
  suspended: news.suspended ?? false,
  httpConfig: news.httpConfig,
  tcpConfig: news.tcpConfig,
});

const desiredEqualsObserved = (desired: DesiredBody, observed: ObservedHealthcheck): boolean => {
  if (desired.name !== observed.name) return false;
  if (desired.address !== observed.address) return false;
  if (desired.type !== observed.type) return false;
  if (desired.description !== (observed.description ?? "")) return false;
  if (
    desired.checkRegions !== undefined &&
    !arrayEqualsUnordered(desired.checkRegions, observed.checkRegions ?? [])
  ) {
    return false;
  }
  if (desired.consecutiveFails !== (observed.consecutiveFails ?? 1)) {
    return false;
  }
  if (desired.consecutiveSuccesses !== (observed.consecutiveSuccesses ?? 1)) {
    return false;
  }
  if (desired.interval !== (observed.interval ?? 60)) return false;
  if (desired.retries !== (observed.retries ?? 2)) return false;
  if (desired.timeout !== (observed.timeout ?? 5)) return false;
  if (desired.suspended !== (observed.suspended ?? false)) return false;
  if (
    desired.httpConfig !== undefined &&
    !httpConfigEquals(desired.httpConfig, observed.httpConfig ?? undefined)
  ) {
    return false;
  }
  if (
    desired.tcpConfig !== undefined &&
    !tcpConfigEquals(desired.tcpConfig, observed.tcpConfig ?? undefined)
  ) {
    return false;
  }
  return true;
};

/**
 * Compare only the http_config fields the user actually specified —
 * Cloudflare fills the rest with plan/type-dependent defaults we should
 * not fight.
 */
const httpConfigEquals = (
  desired: HttpConfig,
  observed: NonNullable<ObservedHealthcheck["httpConfig"]> | undefined,
): boolean => {
  if (observed === undefined) return false;
  if (
    desired.allowInsecure !== undefined &&
    desired.allowInsecure !== (observed.allowInsecure ?? false)
  ) {
    return false;
  }
  if (
    desired.expectedBody !== undefined &&
    desired.expectedBody !== (observed.expectedBody ?? "")
  ) {
    return false;
  }
  if (
    desired.expectedCodes !== undefined &&
    !arrayEqualsUnordered(desired.expectedCodes, observed.expectedCodes ?? [])
  ) {
    return false;
  }
  if (
    desired.followRedirects !== undefined &&
    desired.followRedirects !== (observed.followRedirects ?? false)
  ) {
    return false;
  }
  if (desired.method !== undefined && desired.method !== observed.method) {
    return false;
  }
  if (desired.path !== undefined && desired.path !== observed.path) {
    return false;
  }
  if (desired.port !== undefined && desired.port !== observed.port) {
    return false;
  }
  if (desired.header !== undefined && !headerEquals(desired.header, observed.header)) {
    return false;
  }
  return true;
};

const headerEquals = (
  desired: Record<string, string[]>,
  observed: Record<string, unknown> | null | undefined,
): boolean => {
  const obs = observed ?? {};
  const keys = Object.keys(desired);
  if (keys.length !== Object.keys(obs).length) return false;
  return keys.every((k) => {
    const o = obs[k];
    return Array.isArray(o) && arrayEqualsUnordered(desired[k] ?? [], o.map(String));
  });
};

const tcpConfigEquals = (
  desired: TcpConfig,
  observed: NonNullable<ObservedHealthcheck["tcpConfig"]> | undefined,
): boolean => {
  if (observed === undefined) return false;
  if (
    desired.method !== undefined &&
    desired.method !== (observed.method ?? "connection_established")
  ) {
    return false;
  }
  if (desired.port !== undefined && desired.port !== observed.port) {
    return false;
  }
  return true;
};

const toAttributes = (observed: ObservedHealthcheck, zoneId: string): Attributes | undefined => {
  if (!observed.id || !observed.name || !observed.address || !observed.type) {
    return undefined;
  }
  return {
    healthcheckId: observed.id,
    zoneId,
    name: observed.name,
    address: observed.address,
    type: observed.type as Type,
    status: (observed.status ?? "unknown") as Status,
    failureReason: observed.failureReason ?? undefined,
    suspended: observed.suspended ?? false,
    interval: observed.interval ?? 60,
    retries: observed.retries ?? 2,
    timeout: observed.timeout ?? 5,
    createdOn: observed.createdOn ?? undefined,
    modifiedOn: observed.modifiedOn ?? undefined,
  };
};