sailfork / t3code-github / .repos/ alchemy-effect/ packages/ aws/ src/ Amplify/ Branch.ts

import * as amplify from "@distilled.cloud/aws/amplify";
import { Unowned } from "alchemy/AdoptPolicy";
import { isResolved, somePropsAreDifferent } from "alchemy/Diff";
import { createPhysicalName } from "alchemy/PhysicalName";
import * as Provider from "alchemy/Provider";
import { Resource } from "alchemy/Resource";
import { createInternalTags, diffTags, hasAlchemyTags, tagRecord } from "alchemy/Tags";
import { toWireSeconds } from "alchemy/Util/Duration";
import type * as Duration from "effect/Duration";
import * as Effect from "effect/Effect";
import type * as Redacted from "effect/Redacted";
import * as Schedule from "effect/Schedule";
import * as Stream from "effect/Stream";
import type { Providers } from "../Providers.ts";

/**
 * Deployment stage of an Amplify branch.
 */
export type BranchStage = "PRODUCTION" | "BETA" | "DEVELOPMENT" | "EXPERIMENTAL" | "PULL_REQUEST";

export interface BranchProps {
  /**
   * ID of the Amplify {@link App} the branch belongs to. Changing it replaces
   * the branch.
   */
  appId: string;
  /**
   * Name of the branch (e.g. `main`). For an app without a connected
   * repository this is just a label for manual deployments. If omitted, a
   * unique name is generated. Changing it replaces the branch.
   */
  branchName?: string;
  /**
   * Description of the branch.
   */
  description?: string;
  /**
   * Display name shown in the Amplify console.
   */
  displayName?: string;
  /**
   * Deployment stage of the branch.
   */
  stage?: BranchStage;
  /**
   * Framework label for the branch (e.g. `React`, `Next.js`).
   */
  framework?: string;
  /**
   * Whether pushing to the (repo-connected) branch automatically triggers a
   * build. Branches of repo-less apps should set this to `false`.
   */
  enableAutoBuild?: boolean;
  /**
   * Whether to enable deployment skew protection for the branch.
   */
  enableSkewProtection?: boolean;
  /**
   * Whether to enable performance mode (longer edge cache intervals).
   */
  enablePerformanceMode?: boolean;
  /**
   * Environment variables available to builds of this branch.
   */
  environmentVariables?: Record<string, string>;
  /**
   * Whether to require basic auth to view the branch's site.
   */
  enableBasicAuth?: boolean;
  /**
   * Basic auth credentials for the branch, as base64 of `user:password`.
   */
  basicAuthCredentials?: Redacted.Redacted<string>;
  /**
   * Build specification (amplify.yml contents) overriding the app's.
   */
  buildSpec?: string;
  /**
   * Content Time-To-Live for the branch's website (wire unit: seconds).
   */
  ttl?: Duration.Input;
  /**
   * Whether pull requests to the (repo-connected) branch create previews.
   */
  enablePullRequestPreview?: boolean;
  /**
   * Amplify environment name used for pull request previews.
   */
  pullRequestEnvironmentName?: string;
  /**
   * User-defined tags to apply to the branch.
   */
  tags?: Record<string, string>;
}

export interface Branch extends Resource<
  "AWS.Amplify.Branch",
  BranchProps,
  {
    appId: string;
    branchName: string;
    branchArn: string;
    tags: Record<string, string>;
  },
  never,
  Providers
> {}

/**
 * A branch of an AWS Amplify Hosting app.
 *
 * For apps without a connected Git repository, a branch is the target of the
 * manual-deploy pipeline: stage a zip with `CreateDeployment`, upload it to
 * the pre-signed URL, and release it with `StartDeployment`.
 *
 * ### Creating Branches
 * **Example:** Manual-Deploy Branch
 * ```typescript
 * const app = yield* App("MySite", { platform: "WEB" });
 * const branch = yield* Branch("Main", {
 *   appId: app.appId,
 *   branchName: "main",
 *   stage: "PRODUCTION",
 *   enableAutoBuild: false,
 * });
 * ```
 *
 * **Example:** Password-Protected Branch with Content TTL
 * ```typescript
 * const branch = yield* Branch("Preview", {
 *   appId: app.appId,
 *   branchName: "preview",
 *   stage: "DEVELOPMENT",
 *   ttl: "10 minutes",
 *   enableBasicAuth: true,
 *   // base64 of "user:password"
 *   basicAuthCredentials: Redacted.make(credentials),
 * });
 * ```
 *
 * @resource
 */
export const Branch = Resource<Branch>("AWS.Amplify.Branch");

// Amplify throttles control-plane writes account-wide in roughly per-minute
// buckets and surfaces it as a BadRequestException with a "Rate exceeded"
// message (not a throttling error class). A burst elsewhere in the account
// (e.g. a mass delete) can keep the bucket exhausted for most of a minute, so
// spread bounded retries evenly across ~80s instead of front-loading an
// exponential that spends its whole budget in the first few seconds.
const amplifyWriteRetrySchedule = Schedule.max([Schedule.spaced("8 seconds"), Schedule.recurs(10)]);

export const BranchProvider = () =>
  Provider.effect(
    Branch,
    Effect.gen(function* () {
      const toName = (id: string, props: { branchName?: string } = {}) =>
        props.branchName
          ? Effect.succeed(props.branchName)
          : createPhysicalName({ id, maxLength: 100 });

      const observe = (appId: string, branchName: string) =>
        amplify.getBranch({ appId, branchName }).pipe(
          Effect.map((r) => r.branch),
          // Amplify's API Gateway front door can time out a slow
          // control-plane call ("Endpoint request timed out"); reads are
          // side-effect free, so retry the typed tag with bounded backoff.
          Effect.retry({
            while: (e): boolean => e._tag === "TimeoutException",
            schedule: Schedule.exponential("2 seconds"),
            times: 3,
          }),
          Effect.catchTag("NotFoundException", () => Effect.undefined),
        );

      const syncTags = Effect.fn(function* (
        branchArn: string,
        desiredTags: Record<string, string>,
        observedTags: Record<string, string>,
      ) {
        const { removed, upsert } = diffTags(observedTags, desiredTags);
        if (upsert.length > 0) {
          yield* amplify.tagResource({
            resourceArn: branchArn,
            tags: Object.fromEntries(upsert.map((t) => [t.Key, t.Value])),
          });
        }
        if (removed.length > 0) {
          yield* amplify.untagResource({
            resourceArn: branchArn,
            tagKeys: removed,
          });
        }
      });

      return {
        stables: ["appId", "branchName", "branchArn"],
        diff: Effect.fn(function* ({ news, olds }) {
          if (!isResolved(news)) return;
          if (somePropsAreDifferent(olds, news, ["appId", "branchName"])) {
            return { action: "replace" };
          }
        }),
        read: Effect.fn(function* ({ id, output }) {
          if (!output?.appId || !output.branchName) return undefined;
          const branch = yield* observe(output.appId, output.branchName);
          if (!branch) return undefined;
          const attrs = {
            appId: output.appId,
            branchName: branch.branchName,
            branchArn: branch.branchArn,
            tags: tagRecord(branch.tags),
          };
          return (yield* hasAlchemyTags(id, branch.tags)) ? attrs : Unowned(attrs);
        }),
        reconcile: Effect.fn(function* ({ id, news, session }) {
          const branchName = yield* toName(id, news);
          const internalTags = yield* createInternalTags(id);
          const desiredTags = { ...internalTags, ...news.tags };
          const ttl = news.ttl === undefined ? undefined : String(toWireSeconds(news.ttl));

          const settings = {
            description: news.description,
            displayName: news.displayName,
            stage: news.stage,
            framework: news.framework,
            enableAutoBuild: news.enableAutoBuild,
            enableSkewProtection: news.enableSkewProtection,
            enablePerformanceMode: news.enablePerformanceMode,
            environmentVariables: news.environmentVariables,
            enableBasicAuth: news.enableBasicAuth,
            basicAuthCredentials: news.basicAuthCredentials,
            buildSpec: news.buildSpec,
            ttl,
            enablePullRequestPreview: news.enablePullRequestPreview,
            pullRequestEnvironmentName: news.pullRequestEnvironmentName,
          };

          let branch = yield* observe(news.appId, branchName);

          if (!branch) {
            // CreateBranch is subject to the account-wide "Rate exceeded"
            // throttle (see amplifyWriteRetrySchedule). Its API Gateway
            // front door can also time out a slow CreateBranch (typed
            // TimeoutException, "Endpoint request timed out") with the
            // outcome unknown — re-observe before every (re)try so a
            // retry converges on the branch the timed-out call created.
            branch = yield* observe(news.appId, branchName).pipe(
              Effect.flatMap((existing) =>
                existing
                  ? Effect.succeed(existing)
                  : amplify
                      .createBranch({
                        appId: news.appId,
                        branchName,
                        ...settings,
                        tags: desiredTags,
                      })
                      .pipe(Effect.map((r) => r.branch)),
              ),
              Effect.retry({
                while: (e): boolean =>
                  e._tag === "TimeoutException" ||
                  (e._tag === "BadRequestException" && (e.message ?? "").includes("Rate exceeded")),
                schedule: amplifyWriteRetrySchedule,
              }),
            );
          } else {
            // UpdateBranch is idempotent — retry front-door timeouts and
            // the "Rate exceeded" throttle with bounded backoff.
            const updated = yield* amplify
              .updateBranch({
                appId: news.appId,
                branchName,
                ...settings,
              })
              .pipe(
                Effect.retry({
                  while: (e): boolean =>
                    e._tag === "TimeoutException" ||
                    (e._tag === "BadRequestException" &&
                      (e.message ?? "").includes("Rate exceeded")),
                  schedule: amplifyWriteRetrySchedule,
                }),
              );
            yield* syncTags(updated.branch.branchArn, desiredTags, tagRecord(branch.tags));
            branch = updated.branch;
          }

          yield* session.note(branch.branchArn);
          return {
            appId: news.appId,
            branchName: branch.branchName,
            branchArn: branch.branchArn,
            tags: desiredTags,
          };
        }),
        list: () =>
          Effect.gen(function* () {
            const apps = yield* amplify.listApps.pages({}).pipe(
              Stream.runCollect,
              Effect.map((chunk) => Array.from(chunk).flatMap((page) => page.apps ?? [])),
            );
            const branches: Array<{
              appId: string;
              branchName: string;
              branchArn: string;
              tags: Record<string, string>;
            }> = [];
            for (const app of apps) {
              const appBranches = yield* amplify.listBranches.pages({ appId: app.appId }).pipe(
                Stream.runCollect,
                Effect.map((chunk) => Array.from(chunk).flatMap((page) => page.branches ?? [])),
              );
              for (const branch of appBranches) {
                branches.push({
                  appId: app.appId,
                  branchName: branch.branchName,
                  branchArn: branch.branchArn,
                  tags: tagRecord(branch.tags),
                });
              }
            }
            return branches;
          }),
        delete: Effect.fn(function* ({ output }) {
          // DeleteBranch is idempotent — retry front-door timeouts and the
          // account-wide "Rate exceeded" throttle; a timed-out delete that
          // actually landed resolves to NotFoundException on the retry,
          // which is swallowed below.
          yield* amplify
            .deleteBranch({
              appId: output.appId,
              branchName: output.branchName,
            })
            .pipe(
              Effect.retry({
                while: (e): boolean =>
                  e._tag === "TimeoutException" ||
                  (e._tag === "BadRequestException" && (e.message ?? "").includes("Rate exceeded")),
                schedule: amplifyWriteRetrySchedule,
              }),
              Effect.catchTag("NotFoundException", () => Effect.void),
            );
        }),
      };
    }),
  );