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

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

const TypeId = "Cloudflare.Rum.Site" as const;
type TypeId = typeof TypeId;

export type SiteProps = {
  /**
   * The hostname to measure, for gray-clouded sites (sites that are not
   * proxied through Cloudflare). Embed the produced `snippet` (or the
   * `siteToken`) in the page yourself.
   *
   * Exactly one of `host` or `zoneTag` must be provided. Switching between
   * the two identity models triggers a replacement; changing the hostname
   * itself is an in-place update.
   */
  host?: string;
  /**
   * The zone identifier, for orange-clouded sites (zones proxied through
   * Cloudflare). Web Analytics attaches to the zone, and `autoInstall` can
   * inject the measurement snippet at the edge. Changing this property
   * triggers a replacement.
   */
  zoneTag?: string;
  /**
   * If enabled, the JavaScript measurement snippet is automatically
   * injected for orange-clouded sites — no manual embed needed.
   * @default false
   */
  autoInstall?: boolean;
  /**
   * Enables or disables RUM measurement. Only valid when `autoInstall` is
   * `true`.
   * @default true
   */
  enabled?: boolean;
  /**
   * If enabled, the JavaScript snippet will not be injected for visitors
   * from the EU.
   * @default false
   */
  lite?: boolean;
};

export type SiteAttributes = {
  /**
   * The Web Analytics site identifier. Stable for the lifetime of the site.
   */
  siteTag: string;
  /**
   * The Web Analytics site token used by the JavaScript beacon.
   */
  siteToken: string;
  /**
   * Encoded JavaScript snippet to embed in pages of gray-clouded sites.
   */
  snippet: string | undefined;
  /**
   * The identifier of the site's implicit ruleset. Rules that include or
   * exclude traffic from measurement live under this ruleset.
   */
  rulesetId: string | undefined;
  /**
   * The Cloudflare account the site belongs to.
   */
  accountId: string;
  /**
   * The measured hostname (gray-clouded sites only).
   */
  host: string | undefined;
  /**
   * The zone identifier (orange-clouded sites only).
   */
  zoneTag: string | undefined;
  /**
   * Whether the JavaScript snippet is automatically injected for
   * orange-clouded sites.
   */
  autoInstall: boolean;
  /**
   * When the site was created.
   */
  created: string | undefined;
};

export type Site = Resource<TypeId, SiteProps, SiteAttributes, never, Providers>;

/**
 * A Cloudflare Web Analytics (RUM) site.
 *
 * A site measures real-user performance for either a plain hostname
 * (gray-clouded — embed the produced `snippet` yourself) or a Cloudflare
 * zone (orange-clouded — set `autoInstall` to inject the snippet at the
 * edge). The site is identified by its auto-assigned `siteTag`; `host` and
 * `autoInstall` are mutable in place, while switching between `host` and
 * `zoneTag` identity models (or changing `zoneTag`) triggers a replacement.
 *
 * Web Analytics is available on free accounts.
 * ### Measuring a hostname
 * **Example:** Gray-clouded site (manual snippet embed)
 * ```typescript
 * const site = yield* Cloudflare.Rum.Site("Analytics", {
 *   host: "example.com",
 * });
 *
 * // Embed in your HTML — contains the site token:
 * const snippet = site.snippet;
 * ```
 *
 * ### Measuring a zone
 * **Example:** Orange-clouded site with automatic snippet injection
 * ```typescript
 * const zone = yield* Cloudflare.Zone.Zone("Zone", { name: "example.com" });
 *
 * yield* Cloudflare.Rum.Site("ZoneAnalytics", {
 *   zoneTag: zone.zoneId,
 *   autoInstall: true,
 * });
 * ```
 *
 * **Example:** Skip injection for EU visitors
 * ```typescript
 * yield* Cloudflare.Rum.Site("ZoneAnalytics", {
 *   zoneTag: zone.zoneId,
 *   autoInstall: true,
 *   lite: true,
 * });
 * ```
 *
 * @see https://developers.cloudflare.com/web-analytics/
 *
 * @resource
 * @product RUM
 * @category Observability & Analytics
 */
export const Site = Resource<Site>(TypeId);

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

export const SiteProvider = () =>
  Provider.succeed(Site, {
    stables: ["siteTag", "siteToken", "accountId", "rulesetId", "created"],

    diff: Effect.fn(function* ({ olds = {}, news, output }) {
      const { accountId } = yield* yield* CloudflareEnvironment;
      const o = olds as SiteProps;
      const n = news as SiteProps;
      if ((output?.accountId ?? accountId) !== accountId) {
        return { action: "replace" } as const;
      }
      // Switching between host-based (gray-clouded) and zone-based
      // (orange-clouded) measurement changes the site's identity model.
      if ((o.zoneTag === undefined) !== (n.zoneTag === undefined)) {
        return { action: "replace" } as const;
      }
      // zoneTag is Input<string>; compare only once both are concrete.
      if (
        typeof o.zoneTag === "string" &&
        typeof n.zoneTag === "string" &&
        o.zoneTag !== n.zoneTag
      ) {
        return { action: "replace" } as const;
      }
      return undefined;
    }),

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

      // Owned path: refresh by our persisted site tag.
      if (output?.siteTag) {
        const observed = yield* getSite(acct, output.siteTag);
        if (observed) return toAttributes(observed, acct);
      }

      // Adoption path: a site measuring the same host/zone may already
      // exist. Web Analytics sites carry no ownership markers (and
      // Cloudflare happily creates duplicates), so we cannot prove we
      // created it — brand it `Unowned` so the engine refuses to take
      // over unless `adopt` is set.
      const host = output?.host ?? olds?.host;
      const zoneTag =
        output?.zoneTag ?? (typeof olds?.zoneTag === "string" ? olds.zoneTag : undefined);
      if (host !== undefined || zoneTag !== undefined) {
        const match = yield* findSite(acct, host, zoneTag);
        if (match) return Unowned(toAttributes(match, acct));
      }
      return undefined;
    }),

    reconcile: Effect.fn(function* ({ news, output }) {
      const { accountId } = yield* yield* CloudflareEnvironment;
      // Inputs have been resolved to concrete strings by Plan.
      const zoneTag = news.zoneTag as string | undefined;

      // 1. Observe — the siteTag cached on `output` is a hint, not a
      //    guarantee: a missing site falls through to create.
      let observed = output?.siteTag
        ? yield* getSite(output.accountId ?? accountId, output.siteTag)
        : undefined;

      // 2. Ensure — create when missing. Cloudflare allows duplicate
      //    sites for the same host/zone, so there is no AlreadyExists
      //    race to tolerate. The create response omits `snippet` and
      //    `ruleset`, so re-read the full site state afterwards (riding
      //    out read-after-write lag on the freshly minted siteTag).
      if (!observed) {
        const created = yield* rum.createSiteInfo({
          accountId,
          host: news.host,
          zoneTag,
          autoInstall: news.autoInstall,
        });
        const siteTag = created.siteTag ?? "";
        observed = yield* rum.getSiteInfo({ accountId, siteId: siteTag }).pipe(
          Effect.retry({
            while: (e) => e._tag === "SiteNotFound",
            schedule: Schedule.exponential("250 millis"),
            times: 5,
          }),
        );
        // Greenfield with no post-create settings to apply — done.
        if (news.enabled === undefined && news.lite === undefined) {
          return toAttributes(observed, accountId);
        }
      }

      // 3. Sync — diff observed cloud state against desired. The update
      //    API is a PUT that requires the full body (host/zoneTag/
      //    autoInstall must be re-sent). `enabled` and `lite` are write-
      //    only (never echoed back by the API), so they are applied
      //    whenever specified — observation cannot prove them converged.
      const dirty =
        (news.host !== undefined && observed.host !== news.host) ||
        (observed.autoInstall ?? false) !== (news.autoInstall ?? false) ||
        news.enabled !== undefined ||
        news.lite !== undefined;
      if (!dirty) {
        return toAttributes(observed, accountId);
      }

      const updated = yield* rum.updateSiteInfo({
        accountId,
        siteId: observed.siteTag ?? "",
        host: news.host,
        zoneTag,
        autoInstall: news.autoInstall,
        enabled: news.enabled,
        lite: news.lite,
      });
      return toAttributes(updated, accountId);
    }),

    delete: Effect.fn(function* ({ output }) {
      yield* rum
        .deleteSiteInfo({
          accountId: output.accountId,
          siteId: output.siteTag,
        })
        .pipe(Effect.catchTag("SiteNotFound", () => Effect.void));
    }),

    // Account collection: Web Analytics sites are enumerated account-wide
    // via the paginated site-info list. Hydrate each row into the exact
    // `read` Attributes shape — the list response carries the same fields
    // (siteTag/siteToken/snippet/ruleset/host) so no per-item re-read is
    // needed.
    list: Effect.fn(function* () {
      const { accountId } = yield* yield* CloudflareEnvironment;
      return yield* rum.listSiteInfos.pages({ accountId }).pipe(
        Stream.runCollect,
        Effect.map((chunk) =>
          Array.from(chunk).flatMap((page) =>
            (page.result ?? []).map((site) => toAttributes(site, accountId)),
          ),
        ),
      );
    }),
  });

type ObservedSite =
  | rum.GetSiteInfoResponse
  | rum.UpdateSiteInfoResponse
  | rum.ListSiteInfosResponse["result"][number];

/**
 * Read a site by tag, mapping "gone" (`SiteNotFound`, Cloudflare error code
 * 10015 `web_analytics.configuration.api.notFound`) to `undefined`.
 */
const getSite = (accountId: string, siteTag: string) =>
  rum.getSiteInfo({ accountId, siteId: siteTag }).pipe(
    Effect.map((site): ObservedSite | undefined => site),
    Effect.catchTag("SiteNotFound", () => Effect.undefined),
  );

/**
 * Find a site measuring the given host (gray-clouded) or zone
 * (orange-clouded). Cloudflare allows several sites for the same target, so
 * pick the oldest for determinism.
 */
const findSite = (accountId: string, host: string | undefined, zoneTag: string | undefined) =>
  rum.listSiteInfos.items({ accountId }).pipe(
    Stream.runCollect,
    Effect.map((chunk) =>
      Array.from(chunk)
        .filter((site) =>
          host !== undefined
            ? site.host === host
            : // A zone-identity site has no `host`. Host-scoped sites on the
              // zone's subdomains ALSO carry `ruleset.zoneTag`, so a zone
              // probe must only match true zone sites — otherwise an
              // unrelated host site satisfies the probe and the engine
              // refuses adoption with OwnedBySomeoneElse.
              zoneTag !== undefined && !site.host && site.ruleset?.zoneTag === zoneTag,
        )
        .sort((a, b) => (a.created ?? "").localeCompare(b.created ?? ""))
        .at(0),
    ),
  );

const toAttributes = (site: ObservedSite, accountId: string): SiteAttributes => ({
  siteTag: site.siteTag ?? "",
  siteToken: site.siteToken ?? "",
  snippet: site.snippet ?? undefined,
  rulesetId: site.ruleset?.id ?? undefined,
  accountId,
  host: site.host ?? undefined,
  zoneTag: site.ruleset?.zoneTag ?? undefined,
  autoInstall: site.autoInstall ?? false,
  created: site.created ?? undefined,
});