sailfork / t3code-github / .repos/ alchemy-effect/ packages/ cloudflare/ src/ LogsControl/ CmbConfig.ts

import * as logs from "@distilled.cloud/cloudflare/logs";
import { isResolved } from "alchemy/Diff";
import * as Provider from "alchemy/Provider";
import { Resource } from "alchemy/Resource";
import * as Effect from "effect/Effect";
import * as Predicate from "effect/Predicate";
import { CloudflareEnvironment } from "../CloudflareEnvironment.ts";
import type { Providers } from "../Providers.ts";

const TypeId = "Cloudflare.Logs.CmbConfig" as const;
type TypeId = typeof TypeId;

export type CmbConfigProps = {
  /**
   * The Cloudflare account whose Customer Metadata Boundary (CMB) log
   * configuration is managed. The config is an account-level singleton, so
   * the account is the resource's identity — changing it triggers a
   * replacement.
   * @default the account from the active Cloudflare profile
   */
  accountId?: string;
  /**
   * Name of the region log data is restricted to (e.g. `"eu"`).
   *
   * Changing the CMB region affects where ALL logs for the account are
   * stored and processed — treat this as a destructive, account-wide
   * setting.
   */
  regions?: string;
  /**
   * Whether log data may be accessed from outside the configured region.
   * @default false
   */
  allowOutOfRegionAccess?: boolean;
};

export type CmbConfigAttributes = {
  /** The Cloudflare account the CMB config belongs to. */
  accountId: string;
  /** Name of the region log data is restricted to. */
  regions: string | undefined;
  /** Whether log data may be accessed from outside the configured region. */
  allowOutOfRegionAccess: boolean | undefined;
};

export type CmbConfig = Resource<TypeId, CmbConfigProps, CmbConfigAttributes, never, Providers>;

/**
 * The account-level Customer Metadata Boundary (CMB) configuration for
 * Cloudflare Logs (`/accounts/{account_id}/logs/control/cmb/config`).
 *
 * The CMB config is a true account singleton with PUT/DELETE semantics: the
 * POST endpoint is a full upsert, and DELETE removes the configuration
 * entirely (an account with no CMB config reads back as empty). Identity is
 * the account itself.
 *
 * CMB is part of Cloudflare's Data Localization Suite and requires an
 * Enterprise plan — on unentitled accounts every operation fails with the
 * typed `LogsControlNotAuthorized` error.
 *
 * :::warning
 * Changing the CMB region changes where ALL logs for the account are stored
 * and processed, and deleting the config lifts the boundary. Handle with
 * care in production accounts.
 * :::
 * ### Restricting logs to a region
 * **Example:** Keep all account logs in the EU
 * ```typescript
 * const cmb = yield* Cloudflare.LogsControl.CmbConfig("EuLogs", {
 *   regions: "eu",
 * });
 * ```
 *
 * **Example:** Allow out-of-region access
 * ```typescript
 * const cmb = yield* Cloudflare.LogsControl.CmbConfig("EuLogs", {
 *   regions: "eu",
 *   allowOutOfRegionAccess: true,
 * });
 * ```
 *
 * @see https://developers.cloudflare.com/data-localization/metadata-boundary/
 *
 * @resource
 * @product Logs
 * @category Observability & Analytics
 */
export const CmbConfig = Resource<CmbConfig>(TypeId);

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

export const CmbConfigProvider = () =>
  Provider.succeed(CmbConfig, {
    stables: ["accountId"],

    diff: Effect.fn(function* ({ news, output }) {
      if (!isResolved(news)) return undefined;
      const { accountId } = yield* yield* CloudflareEnvironment;
      const newAccountId = news.accountId ?? accountId;
      // The account is the singleton's identity.
      if (output !== undefined && output.accountId !== newAccountId) {
        return { action: "replace" } as const;
      }
      return undefined;
    }),

    read: Effect.fn(function* ({ output, olds }) {
      const { accountId: envAccountId } = yield* yield* CloudflareEnvironment;
      const accountId =
        output?.accountId ?? (typeof olds?.accountId === "string" ? olds.accountId : envAccountId);
      const observed = yield* getCmbConfig(accountId);
      // Unconfigured account — the singleton does not currently exist.
      if (observed === undefined) return undefined;
      // The config is an account singleton — there is no foreign instance
      // to protect, so a cold read adopts freely.
      return toAttributes(accountId, observed);
    }),

    // Account singleton: there is no account-wide collection API, only the
    // single `/logs/control/cmb/config` GET. Mirror `read` exactly — return a
    // one-element array when the config is set, `[]` when the account is
    // unconfigured.
    list: Effect.fn(function* () {
      const { accountId } = yield* yield* CloudflareEnvironment;
      const observed = yield* getCmbConfig(accountId);
      return observed === undefined ? [] : [toAttributes(accountId, observed)];
    }),

    reconcile: Effect.fn(function* ({ news }) {
      const { accountId: envAccountId } = yield* yield* CloudflareEnvironment;
      // Inputs were resolved to concrete values by Plan.
      const accountId = (news.accountId as string | undefined) ?? envAccountId;

      // Observe — read the live config (undefined = unconfigured).
      const observed = yield* getCmbConfig(accountId);

      // Sync — POST is a full upsert; skip the call when the observed
      // config already matches the desired one.
      const desiredAllowOutOfRegionAccess = news.allowOutOfRegionAccess;
      const inSync =
        observed !== undefined &&
        (observed.regions ?? undefined) === news.regions &&
        (desiredAllowOutOfRegionAccess === undefined ||
          (observed.allowOutOfRegionAccess ?? false) === desiredAllowOutOfRegionAccess);
      if (inSync) {
        return toAttributes(accountId, observed);
      }

      const created = yield* logs.createControlCmbConfig({
        accountId,
        regions: news.regions,
        allowOutOfRegionAccess: news.allowOutOfRegionAccess,
      });
      return toAttributes(accountId, created);
    }),

    delete: Effect.fn(function* ({ output }) {
      // Observe — already unconfigured (or gone with the account) means
      // there is nothing to delete; re-delete after a crashed run is a
      // no-op.
      const observed = yield* getCmbConfig(output.accountId).pipe(
        Effect.catchTag("InvalidRoute", () => Effect.undefined),
      );
      if (observed === undefined) return;
      yield* logs
        .deleteControlCmbConfig({ accountId: output.accountId })
        .pipe(Effect.catchTag(["CmbConfigNotFound", "InvalidRoute"], () => Effect.void));
    }),
  });

/**
 * Read the CMB config, normalizing "not configured" to `undefined`. An
 * unconfigured account answers with `result: null` (decoded as an empty
 * struct) or a 404 (`CmbConfigNotFound`).
 */
const getCmbConfig = (accountId: string) =>
  logs.getControlCmbConfig({ accountId }).pipe(
    Effect.map((config) =>
      config.regions === undefined || config.regions === null ? undefined : config,
    ),
    // Accounts without the Compliance/CMB entitlement get
    // `LogsControlNotAuthorized` — treat as unconfigured (nothing to manage).
    Effect.catchTag(["CmbConfigNotFound", "LogsControlNotAuthorized"], () => Effect.undefined),
  );

const toAttributes = (
  accountId: string,
  config: logs.GetControlCmbConfigResponse | logs.CreateControlCmbConfigResponse,
): CmbConfigAttributes => ({
  accountId,
  regions: config.regions ?? undefined,
  allowOutOfRegionAccess: config.allowOutOfRegionAccess ?? undefined,
});