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

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

const TypeId = "Cloudflare.Devices.DexTest" as const;
type TypeId = typeof TypeId;

/**
 * What the WARP client probes when the test runs.
 */
export interface DeviceDexTestData {
  /**
   * The URL (for `http` tests) or hostname/IP (for `traceroute` tests)
   * to probe.
   */
  host: string;
  /** The kind of synthetic test the WARP client runs. */
  kind: "http" | "traceroute";
  /** The HTTP method to use — only `GET` is supported. */
  method?: "GET" | (string & {});
}

/**
 * A device-profile (DEX rule) targeted by the test.
 */
export interface DeviceDexTestTargetPolicy {
  /** The id of the device settings profile. */
  id: string;
  /** Whether the profile is the account default. */
  default?: boolean;
  /** The name of the device settings profile. */
  name?: string;
}

export interface DeviceDexTestProps {
  /**
   * Name of the DEX test. Must be unique within the account. If omitted,
   * a unique name is generated from the app, stage, and logical ID.
   * @default ${app}-${stage}-${id}
   */
  name?: string;
  /**
   * The synthetic probe the WARP client runs.
   */
  data: DeviceDexTestData;
  /**
   * How often the test runs, as a duration string (e.g. `0h30m0s`).
   */
  interval: string;
  /**
   * Whether the test is active.
   * @default true
   */
  enabled?: boolean;
  /**
   * Additional details about the test.
   */
  description?: string;
  /**
   * Device settings profiles (DEX rules) targeted by this test.
   */
  targetPolicies?: DeviceDexTestTargetPolicy[];
  /**
   * Whether the test only runs for devices matching `targetPolicies`.
   */
  targeted?: boolean;
}

export type DeviceDexTestAttributes = {
  /** API UUID of the DEX test. */
  testId: string;
  /** Account that owns the test. */
  accountId: string;
  /** Observed test name. */
  name: string;
  /** Observed probe configuration. */
  data: DeviceDexTestData;
  /** Observed run interval. */
  interval: string;
  /** Whether the test is active. */
  enabled: boolean;
  /** Observed description, if any. */
  description: string | undefined;
};

export type DeviceDexTest = Resource<
  TypeId,
  DeviceDexTestProps,
  DeviceDexTestAttributes,
  never,
  Providers
>;

/**
 * A Cloudflare Zero Trust **DEX synthetic test** — an HTTP or traceroute
 * probe that enrolled WARP devices run on a schedule so the Digital
 * Experience Monitoring dashboard can chart reachability and latency to
 * your critical applications.
 *
 * Requires the DEX entitlement on the account (the API rejects writes
 * with `Forbidden` / `dex.api.entitlements.missing` otherwise).
 * ### Creating a DEX test
 * **Example:** HTTP probe every 30 minutes
 * ```typescript
 * const test = yield* Cloudflare.Devices.DeviceDexTest("AppHealth", {
 *   data: { host: "https://app.example.com/health", kind: "http", method: "GET" },
 *   interval: "0h30m0s",
 *   description: "Internal app reachability",
 * });
 * ```
 *
 * **Example:** Traceroute probe targeting specific device profiles
 * ```typescript
 * const trace = yield* Cloudflare.Devices.DeviceDexTest("OriginTrace", {
 *   data: { host: "203.0.113.10", kind: "traceroute" },
 *   interval: "0h30m0s",
 *   targeted: true,
 *   targetPolicies: [{ id: profile.policyId }],
 * });
 * ```
 *
 * @see https://developers.cloudflare.com/cloudflare-one/insights/dex/tests/
 *
 * @resource
 * @product Devices
 * @category Cloudflare One (Zero Trust)
 */
export const DeviceDexTest = Resource<DeviceDexTest>(TypeId);

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

export const DeviceDexTestProvider = () =>
  Provider.succeed(DeviceDexTest, {
    stables: ["testId", "accountId"],

    // Account-scoped collection: paginate the DEX tests list and hydrate each
    // row (which already carries the full read shape) into Attributes. DEX
    // requires the Digital Experience Monitoring entitlement; on unentitled
    // accounts the list rejects with the typed `Forbidden`
    // (dex.api.entitlements.missing), so treat that as "nothing to enumerate".
    list: Effect.fn(function* () {
      const { accountId } = yield* yield* CloudflareEnvironment;
      return yield* zeroTrust.listDeviceDexTests.pages({ accountId }).pipe(
        Stream.runCollect,
        Effect.map((chunk) =>
          Array.from(chunk).flatMap((page) =>
            (page.result ?? [])
              .filter((t) => t.testId != null)
              .map((t) => toAttributes(t, accountId)),
          ),
        ),
        Effect.catchTag("Forbidden", () => Effect.succeed([])),
      );
    }),

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

      if (output?.testId) {
        const observed = yield* observeTest(acct, output.testId);
        return observed ? toAttributes(observed, acct) : undefined;
      }

      // Cold lookup: DEX test names are unique per account, but carry no
      // ownership markers — brand the match `Unowned`.
      const name = yield* createTestName(id, olds?.name);
      const match = yield* findByName(acct, name);
      if (match) return Unowned(toAttributes(match, acct));
      return undefined;
    }),

    reconcile: Effect.fn(function* ({ id, news, output }) {
      const { accountId } = yield* yield* CloudflareEnvironment;
      const name = yield* createTestName(id, news.name);

      // 1. Observe — cached id is a hint; fall back to a name scan.
      let observed = output?.testId ? yield* observeTest(accountId, output.testId) : undefined;
      if (!observed) {
        observed = yield* findByName(accountId, name);
      }

      // 2. Ensure — create when missing.
      if (!observed) {
        const created = yield* zeroTrust.createDeviceDexTest({
          accountId,
          name,
          enabled: news.enabled ?? true,
          interval: news.interval,
          data: encodeData(news.data),
          ...(news.description !== undefined ? { description: news.description } : {}),
          ...(news.targeted !== undefined ? { targeted: news.targeted } : {}),
          ...(news.targetPolicies !== undefined ? { targetPolicies: news.targetPolicies } : {}),
        });
        return toAttributes(created, accountId);
      }

      // 3. Sync — PUT the full desired state when the observed state
      //    differs; skip the call on a no-op.
      const dirty =
        (observed.name ?? "") !== name ||
        (observed.interval ?? "") !== news.interval ||
        (observed.enabled ?? true) !== (news.enabled ?? true) ||
        (observed.description ?? undefined) !== news.description ||
        !sameData(observed.data, news.data);
      if (!dirty) {
        return toAttributes(observed, accountId);
      }
      const updated = yield* zeroTrust.updateDeviceDexTest({
        accountId,
        dexTestId: observed.testId!,
        name,
        enabled: news.enabled ?? true,
        interval: news.interval,
        data: encodeData(news.data),
        ...(news.description !== undefined ? { description: news.description } : {}),
        ...(news.targeted !== undefined ? { targeted: news.targeted } : {}),
        ...(news.targetPolicies !== undefined ? { targetPolicies: news.targetPolicies } : {}),
      });
      return toAttributes(updated, accountId);
    }),

    delete: Effect.fn(function* ({ output }) {
      yield* zeroTrust
        .deleteDeviceDexTest({
          accountId: output.accountId,
          dexTestId: output.testId,
        })
        .pipe(Effect.catchTag("DexTestNotFound", () => Effect.void));
    }),
  });

/**
 * Structural shape shared by get/list/create/update responses.
 */
type ObservedDexTest = {
  data: {
    host: string;
    kind: "http" | "traceroute" | (string & {});
    method?: "GET" | (string & {}) | null;
  };
  enabled: boolean;
  interval: string;
  name: string;
  description?: string | null;
  testId?: string | null;
};

/**
 * Read a DEX test by id, mapping "gone" to `undefined`.
 */
const observeTest = (accountId: string, dexTestId: string) =>
  zeroTrust
    .getDeviceDexTest({ accountId, dexTestId })
    .pipe(Effect.catchTag("DexTestNotFound", () => Effect.undefined));

/**
 * Find a DEX test by exact name (names are unique per account).
 */
const findByName = (accountId: string, name: string) =>
  zeroTrust
    .listDeviceDexTests({ accountId })
    .pipe(
      Effect.map((list) => (list.result ?? []).find((t) => t.name === name && t.testId != null)),
    );

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

const encodeData = (
  data: DeviceDexTestData,
): {
  host: string;
  kind: "http" | "traceroute";
  method?: "GET" | (string & {});
} => ({
  host: data.host,
  kind: data.kind,
  ...(data.method !== undefined ? { method: data.method } : {}),
});

const sameData = (observed: ObservedDexTest["data"], desired: DeviceDexTestData): boolean =>
  observed.host === desired.host &&
  observed.kind === desired.kind &&
  (observed.method ?? undefined) === desired.method;

const toAttributes = (test: ObservedDexTest, accountId: string): DeviceDexTestAttributes => ({
  testId: test.testId ?? "",
  accountId,
  name: test.name,
  data: {
    host: test.data.host,
    kind: test.data.kind === "traceroute" ? "traceroute" : "http",
    ...(test.data.method != null ? { method: test.data.method } : {}),
  },
  interval: test.interval,
  enabled: test.enabled,
  description: test.description ?? undefined,
});