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

import * as amplify from "@distilled.cloud/aws/amplify";
import { Unowned } from "alchemy/AdoptPolicy";
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 * 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";

/**
 * Hosting platform for the Amplify app. `WEB` = static site, `WEB_DYNAMIC` =
 * server-side rendered, `WEB_COMPUTE` = SSR with compute (Next.js 12+).
 */
export type Platform = "WEB" | "WEB_DYNAMIC" | "WEB_COMPUTE";

/**
 * A URL redirect/rewrite rule for the Amplify app.
 */
export interface CustomRule {
  /** Source URL pattern. */
  source: string;
  /** Target URL. */
  target: string;
  /** HTTP status / rule type (e.g. `"200"`, `"301"`, `"404"`). */
  status?: string;
  /** Condition (e.g. country code) for the rule to apply. */
  condition?: string;
}

export interface AppProps {
  /**
   * Name of the app. If omitted, a unique name is generated.
   */
  name?: string;
  /**
   * Description of the app.
   */
  description?: string;
  /**
   * Hosting platform.
   * @default "WEB"
   */
  platform?: Platform;
  /**
   * Environment variables available to the build.
   */
  environmentVariables?: Record<string, string>;
  /**
   * Build specification (amplify.yml contents) for the app.
   */
  buildSpec?: string;
  /**
   * URL redirect and rewrite rules.
   */
  customRules?: CustomRule[];
  /**
   * Whether to require basic auth to view the app's branches by default.
   */
  enableBasicAuth?: boolean;
  /**
   * Default basic auth credentials for the app's branches, as base64 of
   * `user:password`.
   */
  basicAuthCredentials?: Redacted.Redacted<string>;
  /**
   * User-defined tags to apply to the app.
   */
  tags?: Record<string, string>;
}

export interface App extends Resource<
  "AWS.Amplify.App",
  AppProps,
  {
    appId: string;
    appArn: string;
    name: string;
    platform: Platform;
    defaultDomain: string;
    tags: Record<string, string>;
  },
  never,
  Providers
> {}

/**
 * An AWS Amplify Hosting app. This resource provisions the app container; it
 * does **not** connect a Git repository.
 *
 * Connecting a repository requires an OAuth handshake (via CodeConnections or a
 * personal access token) that is inherently human-in-the-loop and cannot be
 * automated from infrastructure code. To wire a repo, create the app with this
 * resource, then connect the repository from the Amplify console or CLI.
 * Manual-deploy branches (no repo required) are code-driven via the
 * {@link Branch} resource plus the `CreateDeployment`/`StartDeployment`
 * bindings. For a fully code-driven static/SSR site on AWS, prefer Alchemy's
 * own `Website` composites (S3 + CloudFront).
 *
 * ### Creating Amplify Apps
 * **Example:** Basic App
 * ```typescript
 * const app = yield* App("MyApp", {
 *   description: "Marketing site",
 *   platform: "WEB",
 * });
 * ```
 *
 * **Example:** App with Build Config and Redirects
 * ```typescript
 * const app = yield* App("MyApp", {
 *   platform: "WEB_COMPUTE",
 *   environmentVariables: { NODE_ENV: "production" },
 *   customRules: [
 *     { source: "/<*>", target: "/index.html", status: "404-200" },
 *   ],
 *   buildSpec: "version: 1\nfrontend:\n  phases:\n    build:\n      commands: []\n",
 * });
 * ```
 *
 * ### Deploying and Observing From a Function
 * **Example:** Manual Deploy Pipeline (CreateDeployment + StartDeployment)
 * ```typescript
 * // init — bind the deployment operations to the app
 * const createDeployment = yield* AWS.Amplify.CreateDeployment(app);
 * const startDeployment = yield* AWS.Amplify.StartDeployment(app);
 *
 * // runtime — stage, upload, release
 * const { jobId, zipUploadUrl } = yield* createDeployment({
 *   branchName: "main",
 * });
 * // PUT the site zip to zipUploadUrl, then:
 * yield* startDeployment({ branchName: "main", jobId });
 * ```
 *
 * **Example:** React to Deployment Status Changes
 * ```typescript
 * yield* AWS.Amplify.consumeDeploymentStatusChanges(
 *   { jobStatus: ["FAILED"] },
 *   (events) =>
 *     Stream.runForEach(events, (event) =>
 *       Effect.log(`build failed on ${event.detail.branchName}`),
 *     ),
 * );
 * ```
 *
 * @resource
 */
export const App = Resource<App>("AWS.Amplify.App");

// 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 AppProvider = () =>
  Provider.effect(
    App,
    Effect.gen(function* () {
      const toName = (id: string, props: { name?: string } = {}) =>
        props.name ? Effect.succeed(props.name) : createPhysicalName({ id, maxLength: 100 });

      const observe = (appId: string) =>
        amplify.getApp({ appId }).pipe(
          Effect.map((r) => r.app),
          // 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),
        );

      // Find an app we own (matching physical name + internal Alchemy tags).
      // Used to recover from a timed-out CreateApp whose outcome is unknown —
      // the backend may have created the app even though the front door gave
      // up on the response.
      const findOwnApp = Effect.fn(function* (id: string, name: string) {
        const apps = yield* amplify.listApps.pages({}).pipe(
          Stream.runCollect,
          Effect.map((chunk) => Array.from(chunk).flatMap((page) => page.apps ?? [])),
        );
        for (const app of apps) {
          if (app.name !== name) continue;
          if (yield* hasAlchemyTags(id, app.tags)) return app;
        }
        return undefined;
      });

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

      return {
        stables: ["appId", "appArn"],
        read: Effect.fn(function* ({ id, output }) {
          if (!output?.appId) return undefined;
          const app = yield* observe(output.appId);
          if (!app) return undefined;
          const attrs = {
            appId: app.appId,
            appArn: app.appArn,
            name: app.name,
            platform: (app.platform as Platform) ?? "WEB",
            defaultDomain: app.defaultDomain ?? "",
            tags: tagRecord(app.tags),
          };
          return (yield* hasAlchemyTags(id, app.tags)) ? attrs : Unowned(attrs);
        }),
        reconcile: Effect.fn(function* ({ id, news, output, session }) {
          const name = yield* toName(id, news);
          const internalTags = yield* createInternalTags(id);
          const desiredTags = { ...internalTags, ...news.tags };

          let app = output?.appId ? yield* observe(output.appId) : undefined;

          if (!app) {
            // CreateApp is subject to the account-wide "Rate exceeded"
            // throttle (see amplifyWriteRetrySchedule). Its API Gateway
            // front door can also time out a slow CreateApp (typed
            // TimeoutException, "Endpoint request timed out") with the
            // outcome unknown — the backend may still have created the
            // app. Observe by name + internal tags before every (re)try so
            // a retry never creates a duplicate app.
            app = yield* findOwnApp(id, name).pipe(
              Effect.flatMap((existing) =>
                existing
                  ? Effect.succeed(existing)
                  : amplify
                      .createApp({
                        name,
                        description: news.description,
                        platform: news.platform ?? "WEB",
                        environmentVariables: news.environmentVariables,
                        buildSpec: news.buildSpec,
                        customRules: news.customRules,
                        enableBasicAuth: news.enableBasicAuth,
                        basicAuthCredentials: news.basicAuthCredentials,
                        tags: desiredTags,
                      })
                      .pipe(Effect.map((r) => r.app)),
              ),
              Effect.retry({
                while: (e): boolean =>
                  e._tag === "TimeoutException" ||
                  (e._tag === "BadRequestException" && (e.message ?? "").includes("Rate exceeded")),
                schedule: amplifyWriteRetrySchedule,
              }),
            );
          } else {
            // UpdateApp is idempotent — retry front-door timeouts and the
            // "Rate exceeded" throttle with bounded backoff.
            yield* amplify
              .updateApp({
                appId: app.appId,
                name,
                description: news.description,
                platform: news.platform ?? "WEB",
                environmentVariables: news.environmentVariables,
                buildSpec: news.buildSpec,
                customRules: news.customRules,
                enableBasicAuth: news.enableBasicAuth,
                basicAuthCredentials: news.basicAuthCredentials,
              })
              .pipe(
                Effect.retry({
                  while: (e): boolean =>
                    e._tag === "TimeoutException" ||
                    (e._tag === "BadRequestException" &&
                      (e.message ?? "").includes("Rate exceeded")),
                  schedule: amplifyWriteRetrySchedule,
                }),
              );
            yield* syncTags(app.appArn, desiredTags, tagRecord(app.tags));
          }

          yield* session.note(app.appArn);
          return {
            appId: app.appId,
            appArn: app.appArn,
            name,
            platform: (news.platform as Platform) ?? "WEB",
            defaultDomain: app.defaultDomain ?? "",
            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 ?? [])),
            );
            return apps.map((app) => ({
              appId: app.appId,
              appArn: app.appArn,
              name: app.name,
              platform: (app.platform as Platform) ?? "WEB",
              defaultDomain: app.defaultDomain ?? "",
              tags: tagRecord(app.tags),
            }));
          }),
        delete: Effect.fn(function* ({ output }) {
          // DeleteApp 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.deleteApp({ appId: output.appId }).pipe(
            Effect.retry({
              while: (e): boolean =>
                e._tag === "TimeoutException" ||
                (e._tag === "BadRequestException" && (e.message ?? "").includes("Rate exceeded")),
              schedule: amplifyWriteRetrySchedule,
            }),
            Effect.catchTag("NotFoundException", () => Effect.void),
          );
        }),
      };
    }),
  );