sailfork / t3code-github / .repos/ alchemy-effect/ packages/ cloudflare/ src/ Gateway/ Location.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 { arrayEqualsUnordered } from "alchemy/Util/equal";
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.Gateway.Location" as const;
type TypeId = typeof TypeId;

/**
 * A source network range (CIDR) requests at a Gateway location may
 * originate from.
 */
export interface LocationNetwork {
  /**
   * IPv4 CIDR, e.g. `203.0.113.0/24`.
   */
  network: string;
}

/**
 * Destination endpoint configuration for a Gateway location. Re-exports
 * distilled's request shape so every server-recognised knob (DoH networks
 * and token requirement, DoT, IPv4/IPv6 toggles) is available without
 * re-declaring the structure.
 */
export type LocationEndpoints = NonNullable<zeroTrust.UpdateGatewayLocationRequest["endpoints"]>;

export interface LocationProps {
  /**
   * Display name for the location. Used as a stable identifier so the
   * provider can locate it by name during adoption / state recovery. If
   * omitted, a unique name is generated from the app, stage, and logical ID.
   *
   * @default ${app}-${stage}-${id}
   */
  name?: string;
  /**
   * Whether this location is the default for the account. Cloudflare
   * rejects demoting the current default directly — promote another
   * location instead. Mutable.
   *
   * @default false
   */
  clientDefault?: boolean;
  /**
   * Whether the location must resolve EDNS (EDNS Client Subnet) queries.
   * Mutable.
   *
   * @default false
   */
  ecsSupport?: boolean;
  /**
   * Identifier of the pair of DNS destination IPv4 addresses assigned to
   * this location. When absent, Cloudflare's shared IPv4 pair is used.
   * Mutable.
   */
  dnsDestinationIpsId?: string;
  /**
   * Destination endpoint configuration (DoH / DoT / IPv4 / IPv6 toggles
   * and source networks). Mutable.
   */
  endpoints?: LocationEndpoints;
  /**
   * Source network ranges (IPv4 CIDRs) requests at this location originate
   * from. Only takes effect when non-empty and the IPv4 endpoint is
   * enabled. Mutable.
   *
   * @default []
   */
  networks?: LocationNetwork[];
}

export interface LocationAttributes {
  /** UUID of the location, assigned by Cloudflare. */
  locationId: string;
  /** Cloudflare account that owns the location. */
  accountId: string;
  /** Display name of the location. */
  name: string;
  /** Whether this location is the account default. */
  clientDefault: boolean;
  /** Whether the location resolves EDNS queries. */
  ecsSupport: boolean;
  /**
   * Server-generated DNS-over-HTTPS subdomain that receives this
   * location's DNS requests (`https://<dohSubdomain>.cloudflare-gateway.com/dns-query`).
   */
  dohSubdomain: string | undefined;
  /** Auto-generated IPv6 destination IP assigned to this location. */
  ip: string | undefined;
  /** Primary DNS destination IPv4 address (read-only, server-assigned). */
  ipv4Destination: string | undefined;
  /** Identifier of the DNS destination IPv4 pair, if a dedicated pair is assigned. */
  dnsDestinationIpsId: string | undefined;
  /** Source network ranges configured for this location. */
  networks: LocationNetwork[];
  /** ISO8601 creation timestamp. */
  createdAt: string | undefined;
  /** ISO8601 last-update timestamp. */
  updatedAt: string | undefined;
}

export type Location = Resource<TypeId, LocationProps, LocationAttributes, never, Providers>;

/**
 * A Cloudflare Zero Trust Gateway DNS location — a configured source of
 * DNS traffic (an office, a home network, a device fleet) with its own
 * DNS-over-HTTPS endpoint and optional dedicated destination IPs.
 *
 * Cloudflare assigns each location a stable `dohSubdomain`; point your
 * network's DoH resolver at
 * `https://<dohSubdomain>.cloudflare-gateway.com/dns-query` and Gateway
 * DNS policies apply to its traffic. All declared properties converge in
 * place — nothing on a location forces a replacement.
 * ### Creating a Location
 * **Example:** DoH-only location
 * ```typescript
 * const office = yield* Cloudflare.Gateway.Location("Office", {
 *   ecsSupport: false,
 * });
 * // Point your resolver at the assigned DoH endpoint:
 * const doh = office.dohSubdomain;
 * ```
 *
 * **Example:** Location with IPv4 source networks
 * ```typescript
 * const office = yield* Cloudflare.Gateway.Location("Office", {
 *   networks: [{ network: "203.0.113.0/24" }],
 *   endpoints: {
 *     doh: { enabled: true },
 *     dot: { enabled: false },
 *     ipv4: { enabled: true },
 *     ipv6: { enabled: false },
 *   },
 * });
 * ```
 *
 * @see https://developers.cloudflare.com/cloudflare-one/connections/connect-devices/agentless/dns/locations/
 *
 * @resource
 * @product Gateway
 * @category Cloudflare One (Zero Trust)
 */
export const Location = Resource<Location>(TypeId);

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

/**
 * Right after a location create/update, Cloudflare's edge intermittently
 * answers the write with a 401 `Unauthorized` carrying "This account does
 * not have access to this feature." even though the account is fully
 * entitled — the same transient edge/token-propagation blip the read path
 * rides out as a 403 `Forbidden`. It clears within a few hundred ms, so we
 * retry the mutation while we see exactly that message. A genuine
 * entitlement loss carries the same tag, but the bounded retry surfaces it
 * quickly instead of looping. Matching the message keeps real auth failures
 * (a bad/expired token) non-retryable.
 */
const isTransientFeatureAccessBlip = (e: {
  readonly _tag: string;
  readonly message?: string;
}): boolean =>
  e._tag === "Unauthorized" && (e.message ?? "").includes("does not have access to this feature");

export const LocationProvider = () =>
  Provider.succeed(Location, {
    stables: ["locationId", "accountId", "dohSubdomain", "ip", "createdAt"],

    // Account-scoped collection: enumerate every Gateway location in the
    // ambient account, exhaustively paginating, and hydrate each into the
    // exact `read` Attributes shape. The list response already carries the
    // full per-location state, so no follow-up get is needed.
    list: Effect.fn(function* () {
      const { accountId } = yield* yield* CloudflareEnvironment;
      return yield* zeroTrust.listGatewayLocations.pages({ accountId }).pipe(
        Stream.runCollect,
        Effect.map((chunk) =>
          Array.from(chunk).flatMap((page) =>
            (page.result ?? [])
              .map((l) => toAttributes(l, accountId))
              // The account's default location can't be deleted while it is
              // the client default (`CannotDeleteDefaultGatewayLocation`);
              // never enumerate it for account-wide teardown.
              .filter((l) => !l.clientDefault),
          ),
        ),
      );
    }),

    diff: Effect.fn(function* ({ output }) {
      const { accountId } = yield* yield* CloudflareEnvironment;
      if ((output?.accountId ?? accountId) !== accountId) {
        return { action: "replace" } as const;
      }
      // Everything declared on a location converges via PUT.
      return undefined;
    }),

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

      // Owned path — refresh by the cached location id.
      if (output?.locationId) {
        const observed = yield* getLocation(acct, output.locationId);
        if (observed) return toAttributes(observed, acct);
      }

      // Cold read — locate by deterministic name. Locations carry no
      // ownership markers, so report the match as Unowned to gate adoption.
      const name = yield* resolveName(id, olds?.name ?? output?.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* resolveName(id, news.name);

      // 1. Observe — the cached id is a hint; fall back to a name scan so
      //    out-of-band deletes / lost state converge.
      let observed = output?.locationId
        ? yield* getLocation(accountId, output.locationId)
        : undefined;
      if (!observed) {
        observed = yield* findByName(accountId, name);
      }

      // 2. Ensure — create with the full desired body when missing. Names
      //    are not unique on Cloudflare's side, so there is no
      //    AlreadyExists race to tolerate.
      if (!observed) {
        const created = yield* zeroTrust
          .createGatewayLocation({
            accountId,
            name,
            clientDefault: news.clientDefault,
            ecsSupport: news.ecsSupport,
            dnsDestinationIpsId: news.dnsDestinationIpsId,
            endpoints: news.endpoints,
            networks: news.networks,
          })
          // See `isTransientFeatureAccessBlip` — ride out the transient
          // 401 "does not have access to this feature" edge blip.
          .pipe(
            Effect.retry({
              while: isTransientFeatureAccessBlip,
              // Capped so the bounded retry stays under ~25s in total.
              schedule: Schedule.min([
                Schedule.exponential("500 millis"),
                Schedule.spaced("4 seconds"),
              ]),
              times: 8,
            }),
          );
        return toAttributes(created, accountId);
      }

      // 3. Sync — diff observed cloud state against desired; the update
      //    API is a PUT of the full mutable state, so send everything but
      //    skip the call entirely on a no-op. Networks compare as an
      //    unordered set; endpoints stringify-compare only when declared.
      const desired = {
        name,
        clientDefault: news.clientDefault ?? observed.clientDefault ?? false,
        ecsSupport: news.ecsSupport ?? observed.ecsSupport ?? false,
        dnsDestinationIpsId: news.dnsDestinationIpsId,
        endpoints: news.endpoints,
        networks: news.networks,
      };
      const dirty =
        observed.name !== desired.name ||
        (observed.clientDefault ?? false) !== desired.clientDefault ||
        (observed.ecsSupport ?? false) !== desired.ecsSupport ||
        (news.dnsDestinationIpsId !== undefined &&
          observed.dnsDestinationIpsId !== news.dnsDestinationIpsId) ||
        (news.networks !== undefined && !sameNetworks(observed.networks ?? [], news.networks)) ||
        (news.endpoints !== undefined && !sameEndpoints(observed.endpoints, news.endpoints));
      if (dirty) {
        const updated = yield* zeroTrust
          .updateGatewayLocation({
            accountId,
            locationId: observed.id!,
            name: desired.name,
            clientDefault: desired.clientDefault,
            ecsSupport: desired.ecsSupport,
            dnsDestinationIpsId: desired.dnsDestinationIpsId,
            endpoints: desired.endpoints,
            networks: desired.networks,
          })
          // See `isTransientFeatureAccessBlip` — ride out the transient
          // 401 "does not have access to this feature" edge blip.
          .pipe(
            Effect.retry({
              while: isTransientFeatureAccessBlip,
              // Capped so the bounded retry stays under ~25s in total.
              schedule: Schedule.min([
                Schedule.exponential("500 millis"),
                Schedule.spaced("4 seconds"),
              ]),
              times: 8,
            }),
          );
        return toAttributes(updated, accountId);
      }

      return toAttributes(observed, accountId);
    }),

    delete: Effect.fn(function* ({ output }) {
      // Deleting the default location while it is the client default is a
      // non-retryable 4xx (CannotDeleteDefaultGatewayLocation, code 1217)
      // and propagates. A missing location (GatewayLocationNotFound, code
      // 1103) means we're done.
      yield* zeroTrust
        .deleteGatewayLocation({
          accountId: output.accountId,
          locationId: output.locationId,
        })
        .pipe(Effect.catchTag("GatewayLocationNotFound", () => Effect.void));
    }),
  });

type ObservedLocation = zeroTrust.GetGatewayLocationResponse;

/**
 * Read a location by id, mapping "gone" (`GatewayLocationNotFound`,
 * Cloudflare error code 1103) to `undefined`.
 */
const getLocation = (accountId: string, locationId: string) =>
  zeroTrust.getGatewayLocation({ accountId, locationId }).pipe(
    Effect.map((l): ObservedLocation | undefined => l),
    Effect.catchTag("GatewayLocationNotFound", () => Effect.undefined),
  );

/**
 * Find a location by exact name. Names are not unique on Cloudflare's
 * side; pick the oldest match for determinism.
 */
const findByName = (accountId: string, name: string) =>
  zeroTrust.listGatewayLocations.items({ accountId }).pipe(
    Stream.filter((l) => l.name === name),
    Stream.runCollect,
    Effect.map(
      (chunk): ObservedLocation | undefined =>
        Array.from(chunk)
          .sort((a, b) => (a.createdAt ?? "").localeCompare(b.createdAt ?? ""))
          .at(0) as ObservedLocation | undefined,
    ),
  );

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

const sameNetworks = (
  observed: ReadonlyArray<LocationNetwork>,
  desired: ReadonlyArray<LocationNetwork>,
): boolean =>
  arrayEqualsUnordered(
    observed.map((n) => n.network),
    desired.map((n) => n.network),
  );

/**
 * Endpoints are a deeply nested object whose server echo includes extra
 * `null`/default fields. Compare only the fields the caller declared.
 */
const sameEndpoints = (
  observed: ObservedLocation["endpoints"],
  desired: LocationEndpoints,
): boolean => {
  if (!observed) return false;
  const sameNetworkList = (
    o: ReadonlyArray<{ network: string }> | null | undefined,
    d: ReadonlyArray<{ network: string }> | null | undefined,
  ) =>
    d === undefined ||
    arrayEqualsUnordered(
      (o ?? []).map((n) => n.network),
      (d ?? []).map((n) => n.network),
    );
  const sameToggle = (o: boolean | null | undefined, d: boolean | undefined) =>
    d === undefined || (o ?? false) === d;
  return (
    sameToggle(observed.doh.enabled, desired.doh.enabled) &&
    sameToggle(observed.doh.requireToken, desired.doh.requireToken) &&
    sameNetworkList(observed.doh.networks, desired.doh.networks) &&
    sameToggle(observed.dot.enabled, desired.dot.enabled) &&
    sameNetworkList(observed.dot.networks, desired.dot.networks) &&
    sameToggle(observed.ipv4.enabled, desired.ipv4.enabled) &&
    sameToggle(observed.ipv6.enabled, desired.ipv6.enabled) &&
    sameNetworkList(observed.ipv6.networks, desired.ipv6.networks)
  );
};

type ListedLocation = NonNullable<zeroTrust.ListGatewayLocationsResponse["result"]>[number];

const toAttributes = (
  location: ObservedLocation | zeroTrust.UpdateGatewayLocationResponse | ListedLocation,
  accountId: string,
): LocationAttributes => ({
  locationId: location.id ?? "",
  accountId,
  name: location.name ?? "",
  clientDefault: location.clientDefault ?? false,
  ecsSupport: location.ecsSupport ?? false,
  dohSubdomain: location.dohSubdomain ?? undefined,
  ip: location.ip ?? undefined,
  ipv4Destination: location.ipv4Destination ?? undefined,
  dnsDestinationIpsId: location.dnsDestinationIpsId ?? undefined,
  networks: (location.networks ?? []).map((n) => ({ network: n.network })),
  createdAt: location.createdAt ?? undefined,
  updatedAt: location.updatedAt ?? undefined,
});