sailfork / t3code-github / .repos/ alchemy-effect/ packages/ cloudflare/ src/ LogsControl/ RetentionFlag.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";
import { listAllZones } from "../Zone/lookup.ts";

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

export type LogsRetentionFlagProps = {
  /**
   * Zone whose Logpull retention flag is managed. The flag is a zone-level
   * singleton, so the zone is the resource's identity — changing it
   * triggers a replacement (the old zone's flag is restored to the value
   * it had before Alchemy managed it).
   */
  zoneId: string;
  /**
   * Whether Logpull log retention is enabled for the zone. Mutable —
   * re-posted in place.
   */
  flag: boolean;
};

export type LogsRetentionFlagAttributes = {
  /** Zone the retention flag belongs to. */
  zoneId: string;
  /** Whether Logpull log retention is enabled. */
  flag: boolean;
  /**
   * The value the flag had before Alchemy first managed it. Restored on
   * destroy, so deleting the resource puts the zone back the way it was
   * found.
   */
  initialFlag: boolean;
};

export type LogsRetentionFlag = Resource<
  TypeId,
  LogsRetentionFlagProps,
  LogsRetentionFlagAttributes,
  never,
  Providers
>;

/**
 * The zone-level Logpull retention flag
 * (`/zones/{zone_id}/logs/control/retention/flag`) pinned to a desired
 * value.
 *
 * The flag is a singleton that always exists on every zone, so this
 * resource never creates or deletes anything physical. Reconcile re-posts
 * the flag when the observed value differs from the desired one; destroy
 * restores the value the flag had before Alchemy first managed it
 * (captured as `initialFlag`) — there is no DELETE endpoint.
 *
 * Logpull is an Enterprise feature — on unentitled zones every operation
 * fails with the typed `LogsControlNotAuthorized` error.
 * ### Managing log retention
 * **Example:** Enable Logpull retention on a zone
 * ```typescript
 * const retention = yield* Cloudflare.LogsControl.LogsRetentionFlag("Retention", {
 *   zoneId: zone.zoneId,
 *   flag: true,
 * });
 * ```
 *
 * **Example:** Explicitly disable retention
 * ```typescript
 * yield* Cloudflare.LogsControl.LogsRetentionFlag("Retention", {
 *   zoneId: zone.zoneId,
 *   flag: false,
 * });
 * ```
 *
 * @see https://developers.cloudflare.com/logs/logpull/enabling-log-retention/
 *
 * @resource
 * @product Logs
 * @category Observability & Analytics
 */
export const LogsRetentionFlag = Resource<LogsRetentionFlag>(TypeId);

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

export const LogsRetentionFlagProvider = () =>
  Provider.succeed(LogsRetentionFlag, {
    stables: ["zoneId", "initialFlag"],

    list: Effect.fn(function* () {
      const { accountId } = yield* yield* CloudflareEnvironment;
      // No account-wide API for this zone singleton — enumerate every
      // zone in the account and read its retention flag (every zone has
      // one). The observed value at enumeration time is the zone's
      // original, so it doubles as `initialFlag`.
      const allZones = yield* listAllZones(accountId);
      const rows = yield* Effect.forEach(
        allZones.map((zone) => zone.id),
        (zoneId) =>
          getFlag(zoneId).pipe(
            Effect.map((flag) =>
              flag === undefined
                ? undefined
                : ({
                    zoneId,
                    flag,
                    initialFlag: flag,
                  } satisfies LogsRetentionFlagAttributes),
            ),
            // Logpull is Enterprise-only; unentitled zones reject with the
            // typed error — skip them rather than fail the whole listing.
            Effect.catchTag("LogsControlNotAuthorized", () => Effect.undefined),
          ),
        { concurrency: 10 },
      );
      return rows.filter((row): row is LogsRetentionFlagAttributes => row !== undefined);
    }),

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

    read: Effect.fn(function* ({ output, olds }) {
      const zoneId = output?.zoneId ?? (typeof olds?.zoneId === "string" ? olds.zoneId : undefined);
      if (zoneId === undefined) return undefined;
      const observed = yield* getFlag(zoneId);
      // Zone deleted out-of-band — the flag is gone with it.
      if (observed === undefined) return undefined;
      // The flag is a zone singleton that always exists — there is nothing
      // to "own", so a cold read adopts freely. The observed value at
      // adoption time becomes the `initialFlag` restored on destroy.
      const initialFlag = output?.initialFlag ?? observed;
      return { zoneId, flag: observed, initialFlag };
    }),

    reconcile: Effect.fn(function* ({ news, output }) {
      // Inputs were resolved to concrete strings by Plan.
      const zoneId = news.zoneId as string;

      // 1. Observe — the flag always exists; read its live value.
      const observed = yield* logs
        .getControlRetention({ zoneId })
        .pipe(Effect.map((r) => r.flag ?? false));

      // 2. Capture — the pre-management value, restored on destroy.
      const initialFlag = output?.initialFlag ?? observed;

      // 3. Sync — re-post only when the observed value differs.
      if (observed === news.flag) {
        return { zoneId, flag: observed, initialFlag };
      }
      const updated = yield* logs.createControlRetention({
        zoneId,
        flag: news.flag,
      });
      return { zoneId, flag: updated.flag ?? news.flag, initialFlag };
    }),

    delete: Effect.fn(function* ({ output }) {
      const { zoneId, initialFlag } = output;
      // Observe — if the zone itself is gone, so is the flag.
      const observed = yield* getFlag(zoneId);
      if (observed === undefined) return;
      // Restore the pre-management value; skip the call when it already
      // matches (idempotent re-delete after a crashed run).
      if (observed === initialFlag) return;
      yield* logs
        .createControlRetention({ zoneId, flag: initialFlag })
        .pipe(Effect.catchTag("InvalidRoute", () => Effect.void));
    }),
  });

/**
 * Read the retention flag, normalizing a missing zone (`InvalidRoute`,
 * Cloudflare error code 7003) to `undefined` and a null flag to `false`.
 */
const getFlag = (zoneId: string) =>
  logs.getControlRetention({ zoneId }).pipe(
    Effect.map((r) => r.flag ?? false),
    Effect.catchTag("InvalidRoute", () => Effect.undefined),
  );