sailfork / t3code-github / .repos/ alchemy-effect/ packages/ aws/ src/ Athena/ WorkGroup.ts

import * as athena from "@distilled.cloud/aws/athena";
import { isResolved } from "alchemy/Diff";
import { createPhysicalName } from "alchemy/PhysicalName";
import * as Provider from "alchemy/Provider";
import { Resource } from "alchemy/Resource";
import { createInternalTags, diffTags } from "alchemy/Tags";
import * as Effect from "effect/Effect";
import * as Stream from "effect/Stream";
import { AWSEnvironment, type AccountID } from "../Environment.ts";
import type { Providers } from "../Providers.ts";
import type { RegionID } from "../Region.ts";

export type WorkGroupName = string;
export type WorkGroupArn = `arn:aws:athena:${RegionID}:${AccountID}:workgroup/${WorkGroupName}`;

export interface WorkGroupProps {
  /**
   * Name of the workgroup. If omitted, a unique name is generated.
   * Changing this replaces the workgroup. Up to 128 characters.
   */
  workGroupName?: string;
  /**
   * Human-readable description of the workgroup.
   */
  description?: string;
  /**
   * S3 URI (`s3://bucket/prefix/`) where query results are written.
   * Applied as the workgroup's `ResultConfiguration.OutputLocation`.
   */
  outputLocation?: string;
  /**
   * Server-side encryption for query results written to S3.
   */
  encryptionOption?: "SSE_S3" | "SSE_KMS" | "CSE_KMS";
  /**
   * KMS key ARN/ID — required when `encryptionOption` is `SSE_KMS` or `CSE_KMS`.
   */
  kmsKey?: string;
  /**
   * Force queries to use this workgroup's result configuration (output
   * location, encryption) instead of client-side settings.
   * @default true
   */
  enforceWorkGroupConfiguration?: boolean;
  /**
   * Per-query data-scanned cutoff in bytes. Queries scanning more are
   * cancelled. Minimum is 10 MB (10_000_000).
   */
  bytesScannedCutoffPerQuery?: number;
  /**
   * Publish per-query CloudWatch metrics for this workgroup.
   * @default false
   */
  publishCloudWatchMetricsEnabled?: boolean;
  /**
   * Charge S3 data-transfer/request costs to the query requester.
   * @default false
   */
  requesterPaysEnabled?: boolean;
  /**
   * Selected Athena engine version (e.g. `"Athena engine version 3"`).
   * If omitted, Athena picks the account default (AUTO).
   */
  engineVersion?: string;
  /**
   * Whether the workgroup accepts queries.
   * @default "ENABLED"
   */
  state?: "ENABLED" | "DISABLED";
  /**
   * User-defined tags to apply to the workgroup.
   */
  tags?: Record<string, string>;
}

export interface WorkGroup extends Resource<
  "AWS.Athena.WorkGroup",
  WorkGroupProps,
  {
    /**
     * Name of the workgroup.
     */
    workGroupName: WorkGroupName;
    /**
     * ARN of the workgroup.
     */
    workGroupArn: WorkGroupArn;
    /**
     * Whether the workgroup accepts queries.
     */
    state: "ENABLED" | "DISABLED";
    /**
     * S3 location query results are written to (`s3://bucket/prefix/`).
     */
    outputLocation: string | undefined;
    /**
     * Tags on the workgroup.
     */
    tags: Record<string, string>;
  },
  never,
  Providers
> {}

/**
 * An Amazon Athena workgroup — an isolation boundary for queries that pins the
 * S3 result-output location, result encryption, a bytes-scanned cutoff, and
 * whether that configuration is enforced over per-query client settings.
 *
 * ### Creating Workgroups
 * **Example:** Workgroup with an enforced result location
 * ```typescript
 * const results = yield* AWS.S3.Bucket("AthenaResults", {});
 * const wg = yield* AWS.Athena.WorkGroup("Analytics", {
 *   outputLocation: results.bucketName.pipe(
 *     Output.map((b) => `s3://${b}/results/`),
 *   ),
 *   enforceWorkGroupConfiguration: true,
 * });
 * ```
 *
 * **Example:** Workgroup with a bytes-scanned cost guardrail
 * ```typescript
 * const wg = yield* AWS.Athena.WorkGroup("Guarded", {
 *   outputLocation: "s3://my-results-bucket/prefix/",
 *   bytesScannedCutoffPerQuery: 10_000_000, // 10 MB per query
 *   publishCloudWatchMetricsEnabled: true,
 * });
 * ```
 *
 * @resource
 */
export const WorkGroup = Resource<WorkGroup>("AWS.Athena.WorkGroup");

const observedTagsOf = (tags: readonly athena.Tag[] | undefined) =>
  Object.fromEntries(
    (tags ?? []).flatMap((t) =>
      t.Key !== undefined && t.Value !== undefined ? [[t.Key, t.Value]] : [],
    ),
  );

const outputLocationOf = (wg: athena.WorkGroup | undefined) =>
  wg?.Configuration?.ResultConfiguration?.OutputLocation;

export const WorkGroupProvider = () =>
  Provider.effect(
    WorkGroup,
    Effect.gen(function* () {
      const toName = (id: string, props: WorkGroupProps = {}) =>
        props.workGroupName
          ? Effect.succeed(props.workGroupName)
          : createPhysicalName({ id, maxLength: 128 });

      const getOne = (name: string) =>
        athena.getWorkGroup({ WorkGroup: name }).pipe(
          Effect.map((res) => res.WorkGroup),
          Effect.catchTag("WorkGroupNotFound", () => Effect.undefined),
        );

      const fetchTags = (arn: string) =>
        athena.listTagsForResource.items({ ResourceARN: arn }).pipe(
          Stream.runCollect,
          Effect.map((chunk) => observedTagsOf(Array.from(chunk))),
          Effect.orElseSucceed(() => ({}) as Record<string, string>),
        );

      return {
        stables: ["workGroupName", "workGroupArn"],
        diff: Effect.fn(function* ({ id, olds, news }) {
          if (!isResolved(news)) return;
          if ((yield* toName(id, olds ?? {})) !== (yield* toName(id, news ?? {}))) {
            return { action: "replace" } as const;
          }
        }),
        read: Effect.fn(function* ({ id, olds, output }) {
          const { accountId, region } = yield* AWSEnvironment.current;
          const name = output?.workGroupName ?? (yield* toName(id, olds ?? {}));
          const wg = yield* getOne(name);
          if (!wg) return undefined;
          const arn = `arn:aws:athena:${region}:${accountId}:workgroup/${name}` as WorkGroupArn;
          return {
            workGroupName: name,
            workGroupArn: arn,
            state: (wg.State ?? "ENABLED") as "ENABLED" | "DISABLED",
            outputLocation: outputLocationOf(wg),
            tags: yield* fetchTags(arn),
          };
        }),
        list: () =>
          Effect.gen(function* () {
            const { accountId, region } = yield* AWSEnvironment.current;
            const pages = yield* athena.listWorkGroups.pages({}).pipe(Stream.runCollect);
            return Array.from(pages)
              .flatMap((page) => page.WorkGroups ?? [])
              .flatMap((wg) =>
                // `primary` is the account's built-in default workgroup;
                // DeleteWorkGroup always rejects it, so keep it out of
                // enumeration for account-wide teardown (nuke).
                wg.Name && wg.Name !== "primary"
                  ? [
                      {
                        workGroupName: wg.Name,
                        workGroupArn:
                          `arn:aws:athena:${region}:${accountId}:workgroup/${wg.Name}` as WorkGroupArn,
                        state: (wg.State ?? "ENABLED") as "ENABLED" | "DISABLED",
                        outputLocation: undefined,
                        tags: {} as Record<string, string>,
                      },
                    ]
                  : [],
              );
          }),
        reconcile: Effect.fn(function* ({ id, news = {}, output, session }) {
          const { accountId, region } = yield* AWSEnvironment.current;
          const name = output?.workGroupName ?? (yield* toName(id, news));
          const arn = `arn:aws:athena:${region}:${accountId}:workgroup/${name}` as WorkGroupArn;
          const internalTags = yield* createInternalTags(id);
          const desiredTags = { ...internalTags, ...news.tags };
          const desiredState = news.state ?? "ENABLED";
          const enforce = news.enforceWorkGroupConfiguration ?? true;
          const encryption = news.encryptionOption
            ? {
                EncryptionOption: news.encryptionOption,
                KmsKey: news.kmsKey,
              }
            : undefined;

          // Observe — cloud state is authoritative.
          let wg = yield* getOne(name);

          // Ensure — create if missing.
          if (!wg) {
            yield* athena.createWorkGroup({
              Name: name,
              Description: news.description,
              Configuration: {
                ResultConfiguration: news.outputLocation
                  ? {
                      OutputLocation: news.outputLocation,
                      EncryptionConfiguration: encryption,
                    }
                  : undefined,
                EnforceWorkGroupConfiguration: enforce,
                PublishCloudWatchMetricsEnabled: news.publishCloudWatchMetricsEnabled,
                BytesScannedCutoffPerQuery: news.bytesScannedCutoffPerQuery,
                RequesterPaysEnabled: news.requesterPaysEnabled,
                EngineVersion: news.engineVersion
                  ? { SelectedEngineVersion: news.engineVersion }
                  : undefined,
              },
              Tags: Object.entries(desiredTags).map(([Key, Value]) => ({
                Key,
                Value,
              })),
            });
            wg = yield* getOne(name);
          } else {
            // Sync — diff observed configuration against desired, apply the
            // delta via UpdateWorkGroup (which takes a ConfigurationUpdates
            // shape distinct from CreateWorkGroup's Configuration).
            const cfg = wg.Configuration;
            const updates: athena.WorkGroupConfigurationUpdates = {};
            let dirty = false;

            if ((cfg?.EnforceWorkGroupConfiguration ?? false) !== enforce) {
              updates.EnforceWorkGroupConfiguration = enforce;
              dirty = true;
            }
            if (
              news.outputLocation !== undefined &&
              cfg?.ResultConfiguration?.OutputLocation !== news.outputLocation
            ) {
              updates.ResultConfigurationUpdates = {
                ...updates.ResultConfigurationUpdates,
                OutputLocation: news.outputLocation,
              };
              dirty = true;
            }
            if (
              encryption &&
              cfg?.ResultConfiguration?.EncryptionConfiguration?.EncryptionOption !==
                encryption.EncryptionOption
            ) {
              updates.ResultConfigurationUpdates = {
                ...updates.ResultConfigurationUpdates,
                EncryptionConfiguration: encryption,
              };
              dirty = true;
            }
            if (
              (cfg?.PublishCloudWatchMetricsEnabled ?? false) !==
              (news.publishCloudWatchMetricsEnabled ?? false)
            ) {
              updates.PublishCloudWatchMetricsEnabled =
                news.publishCloudWatchMetricsEnabled ?? false;
              dirty = true;
            }
            if ((cfg?.RequesterPaysEnabled ?? false) !== (news.requesterPaysEnabled ?? false)) {
              updates.RequesterPaysEnabled = news.requesterPaysEnabled ?? false;
              dirty = true;
            }
            if (
              (cfg?.BytesScannedCutoffPerQuery ?? undefined) !== news.bytesScannedCutoffPerQuery
            ) {
              if (news.bytesScannedCutoffPerQuery === undefined) {
                updates.RemoveBytesScannedCutoffPerQuery = true;
              } else {
                updates.BytesScannedCutoffPerQuery = news.bytesScannedCutoffPerQuery;
              }
              dirty = true;
            }
            if (
              news.engineVersion !== undefined &&
              cfg?.EngineVersion?.SelectedEngineVersion !== news.engineVersion
            ) {
              updates.EngineVersion = {
                SelectedEngineVersion: news.engineVersion,
              };
              dirty = true;
            }

            const stateChange = (wg.State ?? "ENABLED") !== desiredState ? desiredState : undefined;
            const descChange =
              news.description !== undefined && wg.Description !== news.description
                ? news.description
                : undefined;

            if (dirty || stateChange || descChange) {
              yield* athena.updateWorkGroup({
                WorkGroup: name,
                Description: descChange,
                State: stateChange,
                ConfigurationUpdates: dirty ? updates : undefined,
              });
            }
          }

          // Sync tags — diff against OBSERVED cloud tags.
          const observed = yield* fetchTags(arn);
          const { upsert, removed } = diffTags(observed, desiredTags);
          if (upsert.length > 0) {
            yield* athena.tagResource({
              ResourceARN: arn,
              Tags: upsert.map((t) => ({ Key: t.Key, Value: t.Value })),
            });
          }
          if (removed.length > 0) {
            yield* athena.untagResource({ ResourceARN: arn, TagKeys: removed });
          }

          const final = (yield* getOne(name)) ?? wg;
          yield* session.note(arn);
          return {
            workGroupName: name,
            workGroupArn: arn,
            state: (final?.State ?? desiredState) as "ENABLED" | "DISABLED",
            outputLocation: outputLocationOf(final) ?? news.outputLocation,
            tags: desiredTags,
          };
        }),
        delete: Effect.fn(function* ({ output }) {
          // Idempotent: DeleteWorkGroup succeeds (no error) when the workgroup
          // is already gone. RecursiveDeleteOption tears down any named
          // queries / prepared statements still saved in it.
          yield* athena.deleteWorkGroup({
            WorkGroup: output.workGroupName,
            RecursiveDeleteOption: true,
          });
        }),
      };
    }),
  );