sailfork / t3code-github / .repos/ alchemy-effect/ packages/ aws/ src/ DataSync/ LocationS3.ts

import * as datasync from "@distilled.cloud/aws/datasync";
import { isResolved } from "alchemy/Diff";
import * as Provider from "alchemy/Provider";
import { Resource } from "alchemy/Resource";
import { createInternalTags } from "alchemy/Tags";
import * as Effect from "effect/Effect";
import * as Stream from "effect/Stream";
import type { Providers } from "../Providers.ts";
import {
  findLocationArnByUri,
  readObservedTags,
  retryWhileRoleNotAssumable,
  syncTags,
} from "./internal.ts";

export interface LocationS3Props {
  /**
   * ARN of the S3 bucket this location points at, e.g.
   * `arn:aws:s3:::my-bucket`. Cannot be changed after creation (replacement).
   */
  s3BucketArn: string;
  /**
   * ARN of the IAM role DataSync assumes to access the bucket. The role's
   * trust policy must allow `datasync.amazonaws.com` and grant the relevant
   * S3 permissions. Cannot be changed after creation (replacement).
   */
  bucketAccessRoleArn: string;
  /**
   * Prefix within the bucket to sync, e.g. `/data`. Cannot be changed after
   * creation (replacement).
   * @default "/" (the bucket root)
   */
  subdirectory?: string;
  /**
   * S3 storage class DataSync writes objects as when this location is a
   * transfer destination. Cannot be changed after creation (replacement).
   * @default "STANDARD"
   */
  s3StorageClass?: datasync.S3StorageClass;
  /**
   * ARNs of DataSync agents used to connect to an S3-on-Outposts bucket.
   * Omit for standard S3 buckets.
   */
  agentArns?: string[];
  /**
   * Tags to apply to the location. Merged with internal Alchemy tags.
   */
  tags?: Record<string, string>;
}

export interface LocationS3 extends Resource<
  "AWS.DataSync.LocationS3",
  LocationS3Props,
  {
    /** ARN of the DataSync location. */
    locationArn: string;
    /** URI of the location (`s3://…`). */
    locationUri: string;
  },
  {},
  Providers
> {}

/**
 * A DataSync location backed by an Amazon S3 bucket. Locations are the
 * source and destination endpoints referenced by a {@link Task}.
 *
 * S3 locations are immutable apart from their tags: any change to the
 * bucket, subdirectory, storage class, or access role replaces the location.
 * Reconcile is idempotent across state loss — the location is re-discovered
 * by its deterministic `s3://…` URI.
 *
 * ### Creating S3 Locations
 * **Example:** Bucket root
 * ```typescript
 * import * as AWS from "@alchemy.run/aws";
 *
 * const source = yield* AWS.DataSync.LocationS3("Source", {
 *   s3BucketArn: bucket.bucketArn,
 *   bucketAccessRoleArn: role.roleArn,
 * });
 * ```
 *
 * **Example:** Prefix + storage class
 * ```typescript
 * const dest = yield* AWS.DataSync.LocationS3("Dest", {
 *   s3BucketArn: bucket.bucketArn,
 *   bucketAccessRoleArn: role.roleArn,
 *   subdirectory: "/archive",
 *   s3StorageClass: "STANDARD_IA",
 * });
 * ```
 *
 * @resource
 */
export const LocationS3 = Resource<LocationS3>("AWS.DataSync.LocationS3");

const bucketNameOf = (bucketArn: string) => bucketArn.split(":::")[1] ?? "";

const expectedUriOf = (props: LocationS3Props): string => {
  const name = bucketNameOf(props.s3BucketArn);
  const sub = props.subdirectory ?? "/";
  const normalized = sub.startsWith("/") ? sub : `/${sub}`;
  return `s3://${name}${normalized}`;
};

export const LocationS3Provider = () =>
  Provider.effect(
    LocationS3,
    Effect.gen(function* () {
      const describe = Effect.fn(function* (locationArn: string) {
        return yield* datasync
          .describeLocationS3({ LocationArn: locationArn })
          .pipe(Effect.catchTag("LocationNotFound", () => Effect.undefined));
      });

      return LocationS3.Provider.of({
        stables: ["locationArn", "locationUri"],

        list: () =>
          datasync.listLocations.pages({}).pipe(
            Stream.runCollect,
            Effect.map((chunk) =>
              Array.from(chunk)
                .flatMap((p) => p.Locations ?? [])
                .filter((l) => l.LocationUri?.startsWith("s3://"))
                .map((l) => ({
                  locationArn: l.LocationArn!,
                  locationUri: l.LocationUri!,
                })),
            ),
          ),

        read: Effect.fn(function* ({ olds, output }) {
          const arn = output?.locationArn ?? (yield* findLocationArnByUri(expectedUriOf(olds)));
          if (arn === undefined) return undefined;
          const loc = yield* describe(arn);
          if (loc === undefined) return undefined;
          return {
            locationArn: loc.LocationArn!,
            locationUri: loc.LocationUri!,
          };
        }),

        diff: Effect.fn(function* ({ news, olds }) {
          if (!isResolved(news)) return undefined;
          const replaced =
            news.s3BucketArn !== olds.s3BucketArn ||
            news.bucketAccessRoleArn !== olds.bucketAccessRoleArn ||
            (news.subdirectory ?? "/") !== (olds.subdirectory ?? "/") ||
            (news.s3StorageClass ?? "STANDARD") !== (olds.s3StorageClass ?? "STANDARD");
          if (replaced) return { action: "replace" } as const;
        }),

        reconcile: Effect.fn(function* ({ id, news, output, session }) {
          const internalTags = yield* createInternalTags(id);
          const desiredTags = { ...news.tags, ...internalTags };

          // 1. OBSERVE — output cache, else re-discover by deterministic URI.
          let arn = output?.locationArn ?? (yield* findLocationArnByUri(expectedUriOf(news)));
          let loc = arn ? yield* describe(arn) : undefined;

          // 2. ENSURE — create if missing.
          if (loc === undefined) {
            const created = yield* retryWhileRoleNotAssumable(
              datasync.createLocationS3({
                S3BucketArn: news.s3BucketArn,
                S3Config: { BucketAccessRoleArn: news.bucketAccessRoleArn },
                Subdirectory: news.subdirectory,
                S3StorageClass: news.s3StorageClass,
                AgentArns: news.agentArns,
                Tags: Object.entries(desiredTags).map(([Key, Value]) => ({
                  Key,
                  Value,
                })),
              }),
            );
            arn = created.LocationArn!;
            loc = yield* describe(arn);
          }

          // 3. SYNC tags against observed cloud state.
          const observed = yield* readObservedTags(arn!);
          yield* syncTags(arn!, observed, desiredTags);

          yield* session.note(arn!);
          return {
            locationArn: loc!.LocationArn!,
            locationUri: loc!.LocationUri!,
          };
        }),

        delete: Effect.fn(function* ({ output }) {
          yield* datasync
            .deleteLocation({ LocationArn: output.locationArn })
            .pipe(Effect.catchTag("LocationNotFound", () => Effect.void));
        }),
      });
    }),
  );