sailfork / t3code-github / .repos/ alchemy-effect/ packages/ cloudflare/ src/ Pages/ Deployment.ts

import * as pages from "@distilled.cloud/cloudflare/pages";
import { isResolved } from "alchemy/Diff";
import * as Provider from "alchemy/Provider";
import { Resource } from "alchemy/Resource";
import * as Data from "effect/Data";
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.Pages.Deployment" as const;
type TypeId = typeof TypeId;

/**
 * Raised when a Pages deployment reaches a `failure`/`canceled` stage, or
 * does not reach a successful `deploy` stage within the bounded wait.
 */
export class DeploymentFailed extends Data.TaggedError("DeploymentFailed")<{
  readonly projectName: string;
  readonly deploymentId: string;
  readonly stageName: string;
  readonly stageStatus: string;
}> {}

export interface DeploymentProps {
  /**
   * Name of the Pages project to deploy to (e.g. `project.name`).
   * Deployments are immutable and belong to exactly one project —
   * changing the project triggers a replacement.
   */
  projectName: string;
  /**
   * The branch the deployment is attributed to. Deploying to the project's
   * production branch produces a production deployment; any other branch
   * produces a preview deployment. Deployments are immutable — changing
   * the branch triggers a replacement (a new deployment).
   * @default the project's production branch
   */
  branch?: string;
}

export interface DeploymentAttributes {
  /**
   * Cloudflare-assigned UUID of the deployment.
   */
  deploymentId: string;
  /**
   * Short (8-character) id of the deployment. Forms the deployment's
   * preview URL (`<shortId>.<project>.pages.dev`).
   */
  shortId: string;
  /**
   * The Cloudflare account the project belongs to.
   */
  accountId: string;
  /**
   * Name of the Pages project the deployment belongs to.
   */
  projectName: string;
  /**
   * Whether this is a `production` or `preview` deployment, derived from
   * the branch it was created on.
   */
  environment: string;
  /**
   * The live URL serving this specific deployment.
   */
  url: string;
  /**
   * The branch the deployment was created from.
   */
  branch: string;
  /**
   * Name of the deployment's latest pipeline stage (e.g. `deploy`).
   */
  latestStageName: string;
  /**
   * Status of the deployment's latest pipeline stage (e.g. `success`).
   */
  latestStageStatus: string;
  /**
   * When the deployment was created.
   */
  createdOn: string;
}

export type Deployment = Resource<TypeId, DeploymentProps, DeploymentAttributes, never, Providers>;

/**
 * A direct-upload deployment on a Cloudflare Pages project.
 *
 * Creating the resource POSTs a new deployment to the project and waits
 * (bounded) for it to reach a successful `deploy` stage. Deployments are
 * immutable — every prop change triggers a replacement (a brand-new
 * deployment that supersedes the previous one).
 *
 * The deployment is created with an **empty asset manifest**: the full
 * direct-upload protocol (asset upload sessions driven by
 * `wrangler pages deploy`) is not part of the public REST surface, so this
 * resource cannot push file contents. It is useful for provisioning an
 * initial/placeholder deployment on a direct-upload project (so the
 * project's `*.pages.dev` subdomain starts serving) and for rolling the
 * active deployment from IaC. For deploying real static sites prefer
 * `Cloudflare.Website` (Workers Assets).
 *
 * Deleting the resource deletes the deployment (with `force`), except when
 * it is the project's active production deployment — Cloudflare refuses to
 * delete the live deployment, so delete tolerates that case and the
 * deployment is cleaned up when the project itself is deleted.
 * ### Creating a Deployment
 * **Example:** Production deployment on a direct-upload project
 * ```typescript
 * const project = yield* Cloudflare.Pages.Project("site", {});
 *
 * const deployment = yield* Cloudflare.Pages.Deployment("site-deploy", {
 *   projectName: project.name,
 * });
 * // deployment.url === "https://<shortId>.<project>.pages.dev"
 * // deployment.environment === "production"
 * ```
 *
 * **Example:** Preview deployment from a non-production branch
 * ```typescript
 * const preview = yield* Cloudflare.Pages.Deployment("site-preview", {
 *   projectName: project.name,
 *   branch: "feature-x",
 * });
 * // preview.environment === "preview"
 * ```
 *
 * @see https://developers.cloudflare.com/pages/
 *
 * @resource
 * @product Pages
 * @category Workers & Compute
 */
export const Deployment = Resource<Deployment>(TypeId);

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

export const DeploymentProvider = () =>
  Provider.succeed(Deployment, {
    stables: [
      "deploymentId",
      "shortId",
      "accountId",
      "projectName",
      "environment",
      "url",
      "branch",
      "createdOn",
    ],
    diff: Effect.fn(function* ({ olds, news, output }) {
      const { accountId } = yield* yield* CloudflareEnvironment;
      if (!isResolved(news)) return undefined;
      if ((output?.accountId ?? accountId) !== accountId) {
        return { action: "replace" } as const;
      }
      // Deployments are immutable: a different project or branch means a
      // brand-new deployment.
      const oldProject =
        output?.projectName ??
        (typeof olds?.projectName === "string" ? olds.projectName : undefined);
      if (oldProject !== undefined && oldProject !== news.projectName) {
        return { action: "replace" } as const;
      }
      const oldBranch = olds?.branch;
      if (oldBranch !== news.branch) {
        return { action: "replace" } as const;
      }
      return undefined;
    }),
    read: Effect.fn(function* ({ output }) {
      // Deployment ids are server-assigned and carry no deterministic
      // identity, so there is no cold lookup — without persisted state the
      // deployment is reported missing and reconcile creates a fresh one.
      if (!output?.deploymentId) return undefined;
      const observed = yield* getDeployment(
        output.accountId,
        output.projectName,
        output.deploymentId,
      );
      return observed ? toAttributes(observed, output.accountId, output.projectName) : undefined;
    }),
    list: Effect.fn(function* () {
      const { accountId } = yield* yield* CloudflareEnvironment;
      // Deployments are sub-resources keyed by Pages project, with no
      // account-wide deployment enumeration API. Enumerate every project
      // (account-scoped) first, then fan out and list each project's
      // deployments, paginating exhaustively.
      const projects = yield* pages.listProjects.pages({ accountId }).pipe(
        Stream.runCollect,
        Effect.map((chunk) => Array.from(chunk).flatMap((page) => page.result ?? [])),
        // Account without a Pages entitlement can't list projects → nothing.
        Effect.catchTag("Forbidden", () => Effect.succeed([])),
      );
      const rows = yield* Effect.forEach(
        projects,
        (project) =>
          pages.listProjectDeployments.pages({ accountId, projectName: project.name }).pipe(
            Stream.runCollect,
            Effect.map((chunk) =>
              Array.from(chunk).flatMap((page) =>
                (page.result ?? []).map((deployment) =>
                  toAttributes(deployment, accountId, project.name),
                ),
              ),
            ),
          ),
        { concurrency: 10 },
      );
      return rows.flat();
    }),
    reconcile: Effect.fn(function* ({ news, output }) {
      const { accountId } = yield* yield* CloudflareEnvironment;
      // Inputs have been resolved to concrete strings by Plan.
      const projectName = news.projectName as string;

      // 1. Observe — `output.deploymentId` is a cache of the only handle we
      //    have on the deployment; a vanished deployment falls through to
      //    "missing" and we create a fresh one.
      let observed = output?.deploymentId
        ? yield* getDeployment(accountId, projectName, output.deploymentId)
        : undefined;

      // 2. Ensure — create the deployment when missing. Deployments are
      //    immutable, so there is no sync step beyond waiting for the
      //    pipeline to finish; an empty manifest means no assets to upload.
      if (!observed) {
        observed = yield* pages.createProjectDeployment({
          accountId,
          projectName,
          branch: news.branch,
          manifest: "{}",
        });
      }

      // 3. Wait (bounded) for the deployment to reach a terminal stage and
      //    fail with a typed error if it didn't succeed.
      observed = yield* awaitDeployment(accountId, projectName, observed);

      // 4. Return fresh attributes.
      return toAttributes(observed, accountId, projectName);
    }),
    delete: Effect.fn(function* ({ output }) {
      // Idempotent: the deployment may already be gone (DeploymentNotFound)
      // or the whole project deleted (ProjectNotFound) — both are success.
      // The active production deployment cannot be deleted even with
      // `force` (Cloudflare error 8000034) — it is removed when the project
      // itself is deleted, so tolerate and move on.
      yield* pages
        .deleteProjectDeployment({
          accountId: output.accountId,
          projectName: output.projectName,
          deploymentId: output.deploymentId,
          force: true,
        })
        .pipe(
          Effect.catchTags({
            DeploymentNotFound: () => Effect.void,
            ProjectNotFound: () => Effect.void,
            ActiveProductionDeployment: () =>
              Effect.logWarning(
                `Pages deployment ${output.deploymentId} is the active production deployment of project ${output.projectName}; it will be deleted with the project.`,
              ),
          }),
        );
    }),
  });

// ---------------------------------------------------------------------------
// Observation
// ---------------------------------------------------------------------------

type ObservedDeployment =
  | pages.GetProjectDeploymentResponse
  | pages.CreateProjectDeploymentResponse;

/**
 * Read a deployment by id, mapping "gone" to `undefined` — either the
 * deployment was deleted (`DeploymentNotFound`, code 8000009) or the whole
 * project no longer exists (`ProjectNotFound`, code 8000007).
 */
const getDeployment = (accountId: string, projectName: string, deploymentId: string) =>
  pages.getProjectDeployment({ accountId, projectName, deploymentId }).pipe(
    Effect.catchTags({
      DeploymentNotFound: () => Effect.undefined,
      ProjectNotFound: () => Effect.undefined,
    }),
  );

const isTerminalStage = (stage: ObservedDeployment["latestStage"]): boolean =>
  (stage.name === "deploy" && stage.status === "success") ||
  stage.status === "failure" ||
  stage.status === "canceled";

/**
 * Poll the deployment until its pipeline reaches a terminal stage —
 * bounded so a stuck deployment fails fast instead of hanging the engine.
 * Anything other than a successful `deploy` stage is a typed failure.
 */
const awaitDeployment = (accountId: string, projectName: string, created: ObservedDeployment) =>
  Effect.gen(function* () {
    const observed: ObservedDeployment = isTerminalStage(created.latestStage)
      ? created
      : yield* pages
          .getProjectDeployment({
            accountId,
            projectName,
            deploymentId: created.id,
          })
          .pipe(
            Effect.repeat({
              schedule: Schedule.spaced("2 seconds"),
              until: (d) => isTerminalStage(d.latestStage),
              times: 25,
            }),
          );
    if (observed.latestStage.status !== "success" || observed.latestStage.name !== "deploy") {
      return yield* new DeploymentFailed({
        projectName,
        deploymentId: observed.id,
        stageName: observed.latestStage.name,
        stageStatus: observed.latestStage.status,
      });
    }
    return observed;
  });

/**
 * Minimal structural shape `toAttributes` reads — satisfied by both the
 * get/create deployment responses and a `listProjectDeployments` row.
 */
type DeploymentAttributesSource = {
  readonly id: string;
  readonly shortId: string;
  readonly environment: string;
  readonly url: string;
  readonly deploymentTrigger: {
    readonly metadata: { readonly branch: string };
  };
  readonly latestStage: { readonly name: string; readonly status: string };
  readonly createdOn: string;
};

const toAttributes = (
  deployment: DeploymentAttributesSource,
  accountId: string,
  projectName: string,
): DeploymentAttributes => ({
  deploymentId: deployment.id,
  shortId: deployment.shortId,
  accountId,
  projectName,
  environment: deployment.environment,
  url: deployment.url,
  branch: deployment.deploymentTrigger.metadata.branch,
  latestStageName: deployment.latestStage.name,
  latestStageStatus: deployment.latestStage.status,
  createdOn: deployment.createdOn,
});