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

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

const TypeId = "Cloudflare.Speed.TestSchedule" as const;
type TypeId = typeof TypeId;

/**
 * Region a scheduled Observatory (speed) test runs from. GCP-style region
 * identifiers — Cloudflare keys schedules per `(url, region)` pair.
 */
export type TestRegion =
  | "asia-east1"
  | "asia-northeast1"
  | "asia-northeast2"
  | "asia-south1"
  | "asia-southeast1"
  | "australia-southeast1"
  | "europe-north1"
  | "europe-southwest1"
  | "europe-west1"
  | "europe-west2"
  | "europe-west3"
  | "europe-west4"
  | "europe-west8"
  | "europe-west9"
  | "me-west1"
  | "southamerica-east1"
  | "us-central1"
  | "us-east1"
  | "us-east4"
  | "us-south1"
  | "us-west1";

/**
 * How often a scheduled test runs.
 */
export type TestFrequency = "DAILY" | "WEEKLY";

export interface TestScheduleProps {
  /**
   * Zone the scheduled test belongs to.
   *
   * Immutable — moving a schedule to a different zone triggers a
   * replacement.
   */
  zoneId: string;
  /**
   * The page URL to test, e.g. `example.com/` or `example.com/pricing`.
   * Must be a page on the zone. Cloudflare normalizes a bare hostname to
   * `host/` (trailing slash).
   *
   * Immutable — the URL is the schedule's identity (path parameter), so
   * changing it triggers a replacement. Deliberately a plain `string` (not
   * `string`) so it is statically knowable inside `diff`.
   */
  url: string;
  /**
   * Region the test runs from. Schedules are keyed per `(url, region)` —
   * changing the region triggers a replacement (a new schedule in the new
   * region is created and the old one deleted).
   * @default "us-central1"
   */
  region?: TestRegion;
  /**
   * How often the test runs. The API has no update call, so changing the
   * frequency is converged in place by deleting and re-creating the
   * schedule (same identity — not a replacement).
   * @default WEEKLY for free plans, DAILY for paid plans (API default)
   */
  frequency?: TestFrequency;
}

export interface TestScheduleAttributes {
  /** Zone the schedule belongs to. */
  zoneId: string;
  /** The tested page URL as normalized by Cloudflare (e.g. `example.com/`). */
  url: string;
  /** Region the test runs from. */
  region: TestRegion;
  /** How often the test runs. */
  frequency: TestFrequency;
}

export type TestSchedule = Resource<
  TypeId,
  TestScheduleProps,
  TestScheduleAttributes,
  never,
  Providers
>;

/**
 * A recurring Cloudflare Observatory (Speed) test schedule — Cloudflare runs
 * a Lighthouse test against a page on your zone on a `DAILY` or `WEEKLY`
 * cadence from a region of your choice.
 *
 * A schedule's identity is the `(zoneId, url, region)` triple: the API keys
 * schedules per URL and region, rejects duplicates, and has no update call.
 * Changing `url`, `region`, or `zoneId` therefore replaces the schedule,
 * while a `frequency` change is converged in place (delete + re-create under
 * the same identity). Creating a schedule implicitly enqueues an initial
 * test run.
 *
 * Plan quota applies: the number of allowed schedules per zone depends on
 * the zone's plan (e.g. 5 on Free/Pro) — see the Observatory availabilities
 * endpoint for the zone's remaining quota.
 *
 * Safety: schedules carry no ownership markers. When there is no prior
 * state, `read` reports an existing schedule for the same `(url, region)` as
 * `Unowned`, so the engine refuses to take it over unless `--adopt` (or
 * `adopt(true)`) is set.
 * ### Scheduling a test
 * **Example:** Weekly test of the home page
 * ```typescript
 * yield* Cloudflare.Speed.TestSchedule("HomePageSpeed", {
 *   zoneId: zone.zoneId,
 *   url: "example.com/",
 *   frequency: "WEEKLY",
 * });
 * ```
 *
 * **Example:** Daily test of a specific page from Europe
 * ```typescript
 * yield* Cloudflare.Speed.TestSchedule("PricingSpeedEU", {
 *   zoneId: zone.zoneId,
 *   url: "example.com/pricing",
 *   region: "europe-west2",
 *   frequency: "DAILY",
 * });
 * ```
 *
 * @see https://developers.cloudflare.com/speed/speed-test/
 *
 * @resource
 * @product Speed
 * @category Performance & Reliability
 */
export const TestSchedule = Resource<TestSchedule>(TypeId);

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

const DEFAULT_REGION: TestRegion = "us-central1";

/**
 * Cloudflare normalizes schedule URLs: the scheme is dropped and a bare
 * hostname gains a trailing slash (`example.com` -> `example.com/`). Apply
 * the same normalization locally so `diff` doesn't flag a replacement for a
 * cosmetic respelling of the same page.
 */
const normalizeUrl = (url: string): string => {
  const stripped = url.replace(/^https?:\/\//, "");
  return stripped.includes("/") ? stripped : `${stripped}/`;
};

export const TestScheduleProvider = () =>
  Provider.succeed(TestSchedule, {
    stables: ["zoneId", "url", "region"],

    list: Effect.fn(function* () {
      const { accountId } = yield* yield* CloudflareEnvironment;
      // Schedules live inside a zone and are keyed per `(url, region)` —
      // there is no account-wide enumeration API. Fan out over every zone,
      // enumerate the zone's Observatory pages, and resolve each page's
      // schedule with the exact `(url, region)` keying `read` uses.
      const zones = yield* listAllZones(accountId);
      const rows = yield* Effect.forEach(
        zones,
        (zone) =>
          speed.listPages.pages({ zoneId: zone.id }).pipe(
            Stream.runCollect,
            Effect.map((chunk) =>
              Array.from(chunk).flatMap((page) =>
                (page.result ?? []).flatMap((p) =>
                  p.url
                    ? [
                        {
                          url: p.url,
                          region: (p.region?.value as TestRegion | undefined) ?? DEFAULT_REGION,
                        },
                      ]
                    : [],
                ),
              ),
            ),
            Effect.flatMap((pages) =>
              Effect.forEach(
                pages,
                ({ url, region }) =>
                  getSchedule(zone.id, url, region).pipe(
                    Effect.map((observed) =>
                      observed ? toAttributes(observed, zone.id, url, region) : undefined,
                    ),
                    // Plan-gated zone rejects the schedule route; skip it.
                    Effect.catchTag("Forbidden", () => Effect.undefined),
                  ),
                { concurrency: 10 },
              ),
            ),
            Effect.map((items) =>
              items.filter((item): item is TestScheduleAttributes => item !== undefined),
            ),
            // Plan-gated / partial zones reject the pages route; skip them.
            Effect.catchTag("InvalidRoute", () => Effect.succeed([])),
          ),
        { concurrency: 10 },
      );
      return rows.flat();
    }),

    diff: Effect.fn(function* ({ olds, news }) {
      const o = olds as TestScheduleProps | undefined;
      const n = news as TestScheduleProps;
      // No prior props to compare against — let the engine decide.
      if (o?.url === undefined) return undefined;
      // The URL is the schedule's path identity.
      if (normalizeUrl(o.url) !== normalizeUrl(n.url)) {
        return { action: "replace" } as const;
      }
      // Schedules are keyed per region — a region change is a new schedule.
      if ((o.region ?? DEFAULT_REGION) !== (n.region ?? DEFAULT_REGION)) {
        return { action: "replace" } as const;
      }
      // zoneId is Input<string>; compare only once both are concrete.
      if (typeof o.zoneId === "string" && typeof n.zoneId === "string" && o.zoneId !== n.zoneId) {
        return { action: "replace" } as const;
      }
      // frequency converges in place (reconcile deletes + re-creates).
      return undefined;
    }),

    read: Effect.fn(function* ({ output, olds }) {
      const zoneId = output?.zoneId ?? (olds?.zoneId as string | undefined);
      const url = output?.url ?? olds?.url;
      const region = output?.region ?? (olds?.region as TestRegion) ?? DEFAULT_REGION;
      if (!zoneId || !url) return undefined;

      const observed = yield* getSchedule(zoneId, url, region);
      if (!observed) return undefined;

      const attrs = toAttributes(observed, zoneId, url, region);
      // Owned path: we have persisted state for this schedule.
      if (output) return attrs;
      // Adoption path: a schedule for this `(url, region)` already exists
      // but schedules carry no ownership markers, so we cannot prove we
      // created it — brand it `Unowned` so the engine refuses to take over
      // unless `adopt` is set.
      return Unowned(attrs);
    }),

    reconcile: Effect.fn(function* ({ news }) {
      // Inputs have been resolved to concrete strings by Plan.
      const zoneId = news.zoneId as string;
      const region = news.region ?? DEFAULT_REGION;

      // 1. Observe — cloud state is authoritative. `output` is only a cache
      //    of the stable identity, which `news` fully determines anyway.
      let observed = yield* getSchedule(zoneId, news.url, region);

      // 2. Ensure — create when missing. A concurrent create surfaces as
      //    `TestScheduleAlreadyExists`: converge by re-reading the schedule
      //    that won the race.
      if (!observed) {
        observed = yield* createAndObserve(zoneId, news.url, region, news.frequency);
      }

      // 3. Sync — the only mutable aspect is `frequency`, and the API has
      //    no update call: converge drift by deleting and re-creating the
      //    schedule under the same identity. Skip entirely on a no-op (or
      //    when the user left frequency to the API default).
      if (news.frequency !== undefined && observed.frequency !== news.frequency) {
        const previous = observed;
        yield* speed
          .deleteSchedule({ zoneId, url: news.url, region })
          .pipe(Effect.catchTag("TestScheduleNotFound", () => Effect.void));
        observed = yield* createAndObserve(zoneId, news.url, region, news.frequency).pipe(
          // Cloudflare caps DAILY-schedule creations per URL per day. We
          // already deleted the old schedule — restore it so a quota
          // rejection degrades to "unchanged" rather than "lost", then
          // surface the typed error.
          Effect.catchTag("TestScheduleQuotaReached", (error) =>
            createAndObserve(
              zoneId,
              news.url,
              region,
              (previous.frequency ?? undefined) as TestFrequency | undefined,
            ).pipe(Effect.flatMap(() => Effect.fail(error))),
          ),
        );
      }

      return toAttributes(observed, zoneId, news.url, region);
    }),

    delete: Effect.fn(function* ({ output }) {
      // The API is idempotent server-side (DELETE on a missing schedule
      // still answers 200), but tolerate the typed not-found anyway.
      yield* speed
        .deleteSchedule({
          zoneId: output.zoneId,
          url: output.url,
          region: output.region,
        })
        .pipe(Effect.catchTag("TestScheduleNotFound", () => Effect.void));
    }),
  });

/** The observed shape shared by get and create responses. */
interface ObservedSchedule {
  url?: string | null;
  region?: string | null;
  frequency?: string | null;
}

/**
 * Read a schedule, mapping "gone" (`TestScheduleNotFound`, Cloudflare
 * `speed.errors.schedule_not_found`) to `undefined`.
 */
const getSchedule = (zoneId: string, url: string, region: TestRegion) =>
  speed.getSchedule({ zoneId, url, region }).pipe(
    Effect.map((s): ObservedSchedule | undefined => s),
    Effect.catchTag("TestScheduleNotFound", () => Effect.undefined),
  );

/**
 * Create a schedule and return the observed result. A concurrent create
 * surfaces as `TestScheduleAlreadyExists` — converge by re-reading the
 * schedule that won the race (and fail with the original error if it
 * vanished again in between).
 */
const createAndObserve = (
  zoneId: string,
  url: string,
  region: TestRegion,
  frequency: TestFrequency | undefined,
) =>
  speed.createSchedule({ zoneId, url, region, frequency }).pipe(
    Effect.flatMap((created) =>
      created.schedule
        ? Effect.succeed(created.schedule as ObservedSchedule)
        : // The create succeeded but echoed no schedule — re-observe.
          getScheduleOrFail(zoneId, url, region),
    ),
    Effect.catchTag("TestScheduleAlreadyExists", () => getScheduleOrFail(zoneId, url, region)),
  );

const getScheduleOrFail = (zoneId: string, url: string, region: TestRegion) =>
  // Let the typed `TestScheduleNotFound` propagate — reaching this state
  // means the schedule vanished between our calls; surfacing the typed
  // error is more honest than inventing one.
  speed.getSchedule({ zoneId, url, region }).pipe(Effect.map((s): ObservedSchedule => s));

const toAttributes = (
  observed: ObservedSchedule,
  zoneId: string,
  url: string,
  region: TestRegion,
): TestScheduleAttributes => ({
  zoneId,
  // Prefer the server-normalized URL (e.g. trailing slash added).
  url: observed.url ?? normalizeUrl(url),
  region: (observed.region ?? region) as TestRegion,
  // Cloudflare always echoes a frequency for a persisted schedule; the
  // distilled type is open/nullable, so default defensively.
  frequency: (observed.frequency ?? "WEEKLY") as TestFrequency,
});