sailfork / t3code-github / .repos/ alchemy-effect/ packages/ cloudflare/ src/ ApiShield/ Operation.ts

import * as apiGateway from "@distilled.cloud/cloudflare/api-gateway";
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";
import { listAllZones } from "../Zone/lookup.ts";

const TypeId = "Cloudflare.ApiShield.Operation" as const;
type TypeId = typeof TypeId;

/**
 * HTTP method of an API Shield operation.
 */
export type OperationMethod =
  | "GET"
  | "POST"
  | "HEAD"
  | "OPTIONS"
  | "PUT"
  | "DELETE"
  | "CONNECT"
  | "PATCH"
  | "TRACE";

export interface OperationProps {
  /**
   * Zone the operation is registered on.
   *
   * Immutable — moving an operation between zones triggers a replacement.
   */
  zoneId: string;
  /**
   * The HTTP method used to access the endpoint.
   *
   * Immutable — an operation is the `(method, host, endpoint)` tuple, so
   * changing the method triggers a replacement.
   */
  method: OperationMethod;
  /**
   * RFC3986-compliant host the endpoint lives on (e.g. `api.example.com`).
   * Must belong to the zone.
   *
   * Immutable — changing the host triggers a replacement.
   */
  host: string;
  /**
   * The endpoint path, which may contain path-parameter templates in curly
   * braces (e.g. `/api/v1/users/{id}`). Cloudflare normalizes variable
   * names left-to-right to `{var1}`, `{var2}`, … on insertion.
   *
   * Immutable — changing the (normalized) endpoint triggers a replacement.
   */
  endpoint: string;
}

export interface OperationAttributes {
  /** Cloudflare-assigned UUID of the operation. */
  operationId: string;
  /** Zone the operation is registered on. */
  zoneId: string;
  /** The HTTP method used to access the endpoint. */
  method: OperationMethod;
  /** RFC3986-compliant host the endpoint lives on. */
  host: string;
  /**
   * The endpoint path as stored by Cloudflare — variable names are
   * normalized left-to-right to `{var1}`, `{var2}`, …
   */
  endpoint: string;
  /** ISO8601 timestamp of the last update. */
  lastUpdated: string;
}

export type Operation = Resource<TypeId, OperationProps, OperationAttributes, never, Providers>;

/**
 * A Cloudflare API Shield operation — a registered API endpoint on a zone,
 * identified by the `(method, host, endpoint)` tuple. Registered operations
 * are the unit other API Shield features (schema validation, rate limiting
 * recommendations, API Discovery) attach to.
 *
 * An operation is pure identity: there is no update API, so changing any
 * property triggers a replacement. Cloudflare upserts by identity — creating
 * an already-registered tuple returns the existing operation — which makes
 * reconciliation race-free.
 *
 * Endpoint paths may contain `{placeholder}` templates; Cloudflare
 * normalizes the variable names left-to-right to `{var1}`, `{var2}`, … and
 * the normalized form is what is stored and diffed.
 * ### Registering an Operation
 * **Example:** Register a GET endpoint
 * ```typescript
 * const op = yield* Cloudflare.ApiShield.Operation("GetUser", {
 *   zoneId: zone.zoneId,
 *   method: "GET",
 *   host: "api.example.com",
 *   endpoint: "/api/v1/users/{id}",
 * });
 * // op.endpoint === "/api/v1/users/{var1}"
 * ```
 *
 * **Example:** Register a POST endpoint
 * ```typescript
 * yield* Cloudflare.ApiShield.Operation("CreateUser", {
 *   zoneId: zone.zoneId,
 *   method: "POST",
 *   host: "api.example.com",
 *   endpoint: "/api/v1/users",
 * });
 * ```
 *
 * @see https://developers.cloudflare.com/api-shield/management-and-monitoring/endpoint-management/
 *
 * @resource
 * @product API Shield
 * @category Application Security
 */
export const Operation = Resource<Operation>(TypeId);

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

export const OperationProvider = () =>
  Provider.succeed(Operation, {
    // An operation has no mutable aspect — every attribute except the
    // last-updated timestamp survives any non-replacing deploy.
    stables: ["operationId", "zoneId", "method", "host", "endpoint"],

    list: Effect.fn(function* () {
      const { accountId } = yield* yield* CloudflareEnvironment;
      // Operations live inside a zone (`/zones/{id}/api_gateway/operations`)
      // with no account-wide enumeration API — fan out over every zone and
      // exhaustively paginate each zone's operations.
      const zones = yield* listAllZones(accountId);
      const rows = yield* Effect.forEach(
        zones,
        (zone) =>
          apiGateway.listOperations.pages({ zoneId: zone.id }).pipe(
            Stream.runCollect,
            Effect.map((chunk) =>
              Array.from(chunk).flatMap((page) =>
                (page.result ?? []).map((op) => toAttributes(op, zone.id)),
              ),
            ),
            // A freshly-minted scoped token can transiently 403; ride out
            // the blip, then skip zones the token genuinely can't read.
            Effect.retry({
              while: (e) => e._tag === "Forbidden",
              schedule: Schedule.exponential("500 millis"),
              times: 5,
            }),
            Effect.catchTag("Forbidden", () => Effect.succeed([] as OperationAttributes[])),
          ),
        { concurrency: 10 },
      );
      return rows.flat();
    }),

    diff: Effect.fn(function* ({ olds, news }) {
      const o = olds as OperationProps | undefined;
      const n = news as OperationProps;
      if (o?.endpoint === undefined) return undefined;
      // The tuple is the operation's identity — any change replaces.
      if (o.method !== n.method || o.host !== n.host) {
        return { action: "replace" } as const;
      }
      // Cloudflare normalizes `{name}` templates to `{varN}`; compare
      // normalized forms so `/users/{id}` -> `/users/{userId}` is a no-op.
      if (normalizeEndpoint(o.endpoint) !== normalizeEndpoint(n.endpoint)) {
        return { action: "replace" } as const;
      }
      // zoneId is Input<string>; compare only once both are concrete.
      if (typeof o.zoneId === "string" && typeof n.zoneId === "string" && o.zoneId !== n.zoneId) {
        return { action: "replace" } as const;
      }
      return undefined;
    }),

    read: Effect.fn(function* ({ output, olds }) {
      const zoneId = output?.zoneId ?? (olds?.zoneId as string | undefined);
      if (zoneId === undefined) return undefined;

      // Owned path: refresh by our persisted operation id.
      if (output?.operationId) {
        const observed = yield* getOperation(zoneId, output.operationId);
        if (observed) return toAttributes(observed, zoneId);
      }

      // Cold path: an operation with this tuple may already exist on the
      // zone (state was lost, or it was registered out-of-band). The tuple
      // is pure identity and carries no ownership markers, so report it as
      // `Unowned` and let the adopt policy gate the takeover.
      const tuple = output ?? (olds as OperationProps | undefined);
      if (tuple?.endpoint !== undefined && typeof tuple.host === "string") {
        const observed = yield* findByTuple(zoneId, {
          method: tuple.method,
          host: tuple.host,
          endpoint: tuple.endpoint,
        });
        if (observed) return Unowned(toAttributes(observed, zoneId));
      }
      return undefined;
    }),

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

      // 1. Observe — the operation id cached on `output` is a hint, not a
      //    guarantee: a missing operation falls through to ensure.
      const observed = output?.operationId
        ? yield* getOperation(zoneId, output.operationId)
        : undefined;
      if (observed) return toAttributes(observed, zoneId);

      // 2. Ensure — Cloudflare upserts by identity: registering an existing
      //    `(method, host, endpoint)` tuple returns the existing operation,
      //    so there is no AlreadyExists race to tolerate.
      const created = yield* apiGateway.createOperation({
        zoneId,
        method: news.method,
        host: news.host,
        endpoint: news.endpoint,
      });
      return toAttributes(created, zoneId);
      // 3. Sync — nothing to do: an operation is existence-only.
    }),

    delete: Effect.fn(function* ({ output }) {
      yield* apiGateway
        .deleteOperation({
          zoneId: output.zoneId,
          operationId: output.operationId,
        })
        .pipe(Effect.catchTag("OperationNotFound", () => Effect.void));
    }),
  });

type ObservedOperation = Pick<
  apiGateway.GetOperationResponse,
  "operationId" | "method" | "host" | "endpoint" | "lastUpdated"
>;

/**
 * Normalize an endpoint path the way Cloudflare does on insertion: each
 * `{placeholder}` is replaced left-to-right with `{var1}`, `{var2}`, …
 */
export const normalizeEndpoint = (endpoint: string): string => {
  let n = 0;
  return endpoint.replace(/\{[^}]*\}/g, () => {
    n += 1;
    return `{var${n}}`;
  });
};

/**
 * Read an operation by id, mapping "gone" (`OperationNotFound`, Cloudflare
 * error code 10404) to `undefined`.
 */
const getOperation = (zoneId: string, operationId: string) =>
  apiGateway.getOperation({ zoneId, operationId }).pipe(
    Effect.map((op): ObservedOperation | undefined => op),
    Effect.catchTag("OperationNotFound", () => Effect.undefined),
  );

/**
 * Find an operation by its exact `(method, host, endpoint)` tuple. The
 * tuple is the operation's identity, so at most one can match. Endpoint
 * comparison uses Cloudflare's normalized form.
 */
const findByTuple = (zoneId: string, tuple: { method: string; host: string; endpoint: string }) =>
  apiGateway.listOperations.items({ zoneId, host: [tuple.host], method: [tuple.method] }).pipe(
    Stream.runCollect,
    Effect.map((chunk) =>
      Array.from(chunk).find(
        (op): op is ObservedOperation & typeof op =>
          op.method === tuple.method &&
          op.host === tuple.host &&
          op.endpoint === normalizeEndpoint(tuple.endpoint),
      ),
    ),
  );

const toAttributes = (op: ObservedOperation, zoneId: string): OperationAttributes => ({
  operationId: op.operationId,
  zoneId,
  // Distilled widens generated string enums to open unions (`string & {}`).
  method: op.method as OperationMethod,
  host: op.host,
  endpoint: op.endpoint,
  lastUpdated: op.lastUpdated,
});