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

import * as loadBalancers from "@distilled.cloud/cloudflare/load-balancers";
import { Unowned } from "alchemy/AdoptPolicy";
import { createPhysicalName } from "alchemy/PhysicalName";
import * as Provider from "alchemy/Provider";
import { Resource } from "alchemy/Resource";
import * as Effect from "effect/Effect";
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.LoadBalancer.MonitorGroup" as const;
type TypeId = typeof TypeId;

/**
 * A monitor membership within a monitor group.
 */
export interface MonitorGroupMember {
  /**
   * The ID of the {@link Monitor} to include in the group.
   */
  monitorId: string;
  /**
   * Whether this member's health check is active.
   * @default true
   */
  enabled?: boolean;
  /**
   * If true, the member's results are recorded but do not affect the
   * group's aggregate health.
   * @default false
   */
  monitoringOnly?: boolean;
  /**
   * Whether this member must report healthy for the group to be healthy.
   * @default true
   */
  mustBeHealthy?: boolean;
}

export interface MonitorGroupProps {
  /**
   * A short description of the monitor group. Monitor groups have no name
   * field, so the description doubles as the group's identity for state
   * recovery — if omitted, a unique name is generated from the app, stage,
   * and logical ID.
   * @default ${app}-${stage}-${id}
   */
  description?: string;
  /**
   * List of monitors in this group.
   */
  members: ReadonlyArray<MonitorGroupMember>;
}

export interface MonitorGroupAttributes {
  /** Cloudflare-assigned monitor group identifier. */
  monitorGroupId: string;
  /** The Cloudflare account the monitor group belongs to. */
  accountId: string;
  /** Monitor group description (carries the physical name when generated). */
  description: string;
  /** ISO8601 creation timestamp. */
  createdOn: string | undefined;
  /** ISO8601 last-modified timestamp. */
  modifiedOn: string | undefined;
}

export type MonitorGroup = Resource<
  TypeId,
  MonitorGroupProps,
  MonitorGroupAttributes,
  never,
  Providers
>;

/**
 * A Cloudflare Load Balancing monitor group — aggregates several
 * {@link Monitor}s into one health signal that a
 * {@link Pool} can reference via `monitorGroup` (mutually
 * exclusive with `monitor`).
 *
 * Monitor groups are an Enterprise-only feature; on non-entitled accounts
 * creation fails with the typed `MonitorGroupsNotEnabled` error.
 * ### Creating a Monitor Group
 * **Example:** Group of two monitors
 * ```typescript
 * const group = yield* Cloudflare.LoadBalancer.MonitorGroup("ApiChecks", {
 *   members: [
 *     { monitorId: httpsMonitor.monitorId },
 *     { monitorId: tcpMonitor.monitorId, mustBeHealthy: false },
 *   ],
 * });
 * ```
 *
 * ### Using with a Pool
 * **Example:** Attach the group to a pool
 * ```typescript
 * yield* Cloudflare.LoadBalancer.Pool("ApiPool", {
 *   origins: [{ name: "origin-1", address: "203.0.113.10" }],
 *   monitorGroup: group.monitorGroupId,
 * });
 * ```
 *
 * @see https://developers.cloudflare.com/load-balancing/monitors/
 *
 * @resource
 * @product Load Balancers
 * @category Performance & Reliability
 */
export const MonitorGroup = Resource<MonitorGroup>(TypeId);

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

export const MonitorGroupProvider = () =>
  Provider.succeed(MonitorGroup, {
    stables: ["monitorGroupId", "accountId", "createdOn"],

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

    // Monitor groups are an account-scoped collection — paginate the
    // account-wide list and hydrate each into the exact `read` Attributes
    // shape (pattern (b) in processes/list-support.md).
    list: Effect.fn(function* () {
      const { accountId } = yield* yield* CloudflareEnvironment;
      return yield* loadBalancers.listMonitorGroups.pages({ accountId }).pipe(
        Stream.runCollect,
        Effect.map((chunk) =>
          Array.from(chunk).flatMap((page) =>
            (page.result ?? []).map((g) => toAttributes(g, accountId)),
          ),
        ),
      );
    }),

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

      if (output?.monitorGroupId) {
        const observed = yield* getMonitorGroup(acct, output.monitorGroupId);
        return observed ? toAttributes(observed, acct) : undefined;
      }
      // Cold read — recover from lost state by matching the deterministic
      // description (our physical name). Monitor groups carry no ownership
      // marker, so report the match as Unowned.
      const description = yield* createDescription(id, olds?.description);
      const match = yield* findByDescription(acct, description);
      if (match) return Unowned(toAttributes(match, acct));
      return undefined;
    }),

    reconcile: Effect.fn(function* ({ id, news, output }) {
      const { accountId } = yield* yield* CloudflareEnvironment;
      const description = yield* createDescription(id, news.description);
      const members = buildMembers(news);

      // 1. Observe — output.monitorGroupId is a cache hint.
      const observed = output?.monitorGroupId
        ? yield* getMonitorGroup(output.accountId ?? accountId, output.monitorGroupId)
        : undefined;

      // 2. Ensure — missing: create with the full desired body.
      if (!observed) {
        const created = yield* loadBalancers.createMonitorGroup({
          accountId,
          description,
          members,
        });
        return toAttributes(created, accountId);
      }

      // 3. Sync — PUT the full desired body when anything drifts; skip
      //    the call on a no-op.
      const dirty =
        observed.description !== description ||
        JSON.stringify(
          observed.members.map((m) => ({
            monitorId: m.monitorId,
            enabled: m.enabled,
            monitoringOnly: m.monitoringOnly,
            mustBeHealthy: m.mustBeHealthy,
          })),
        ) !== JSON.stringify(members);
      if (!dirty) {
        return toAttributes(observed, accountId);
      }
      const updated = yield* loadBalancers.updateMonitorGroup({
        accountId,
        monitorGroupId: observed.id,
        description,
        members,
      });
      return toAttributes(updated, accountId);
    }),

    delete: Effect.fn(function* ({ output }) {
      // A group still referenced by a pool cannot be deleted — retry the
      // typed MonitorGroupInUse tag with bounded backoff while the engine
      // tears down dependents.
      yield* loadBalancers
        .deleteMonitorGroup({
          accountId: output.accountId,
          monitorGroupId: output.monitorGroupId,
        })
        .pipe(
          Effect.retry({
            while: (e) => e._tag === "MonitorGroupInUse",
            schedule: Schedule.max([Schedule.exponential("1 second"), Schedule.recurs(6)]),
          }),
          Effect.catchTag("MonitorGroupNotFound", () => Effect.void),
        );
    }),
  });

type ObservedMonitorGroup =
  | loadBalancers.GetMonitorGroupResponse
  | loadBalancers.CreateMonitorGroupResponse
  | loadBalancers.UpdateMonitorGroupResponse
  | loadBalancers.ListMonitorGroupsResponse["result"][number];

/**
 * Read a monitor group by id, mapping "gone" (`MonitorGroupNotFound`,
 * HTTP 404 code 1001) to `undefined`.
 */
const getMonitorGroup = (accountId: string, monitorGroupId: string) =>
  loadBalancers
    .getMonitorGroup({ accountId, monitorGroupId })
    .pipe(Effect.catchTag("MonitorGroupNotFound", () => Effect.undefined));

/**
 * Find a monitor group by exact description. If several carry the same
 * description, pick the oldest for determinism.
 */
const findByDescription = (accountId: string, description: string) =>
  loadBalancers.listMonitorGroups.items({ accountId }).pipe(
    Stream.filter((g) => g.description === description),
    Stream.runCollect,
    Effect.map((chunk) =>
      Array.from(chunk)
        .sort((a, b) => (a.createdOn ?? "").localeCompare(b.createdOn ?? ""))
        .at(0),
    ),
  );

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

const buildMembers = (news: MonitorGroupProps) =>
  news.members.map((m) => ({
    // Inputs are resolved to concrete strings by Plan.
    monitorId: m.monitorId as string,
    enabled: m.enabled ?? true,
    monitoringOnly: m.monitoringOnly ?? false,
    mustBeHealthy: m.mustBeHealthy ?? true,
  }));

const toAttributes = (group: ObservedMonitorGroup, accountId: string): MonitorGroupAttributes => ({
  monitorGroupId: group.id,
  accountId,
  description: group.description,
  createdOn: group.createdOn ?? undefined,
  modifiedOn: group.modifiedOn ?? undefined,
});