sailfork / t3code-github / .repos/ alchemy-effect/ packages/ aws/ src/ CostAndUsageReport/ ReportDefinition.ts

import * as cur from "@distilled.cloud/aws/cost-and-usage-report-service";
import { Unowned } from "alchemy/AdoptPolicy";
import { isResolved } from "alchemy/Diff";
import { createPhysicalName } from "alchemy/PhysicalName";
import * as Provider from "alchemy/Provider";
import { Resource } from "alchemy/Resource";
import { createInternalTags, diffTags, hasAlchemyTags } from "alchemy/Tags";
import * as Effect from "effect/Effect";
import * as Schedule from "effect/Schedule";
import * as Stream from "effect/Stream";
import { AWSEnvironment } from "../Environment.ts";
import type { Providers } from "../Providers.ts";
import { Region } from "../Region.ts";

// The Cost and Usage Report API (`cur`) is a global service hosted only in
// us-east-1 (the report's delivery bucket may live in any region — that is
// what `s3Region` describes). Every control-plane call is pinned there
// regardless of the ambient stack region. The distilled Region service value
// is `Effect<RegionName>`, not a raw string, hence Effect.succeed.
const CUR_REGION = "us-east-1";
const pin = <A, E, R>(effect: Effect.Effect<A, E, R>) =>
  effect.pipe(Effect.provideService(Region, Effect.succeed(CUR_REGION)));

// PutReportDefinition validates that the delivery bucket's policy grants
// billingreports.amazonaws.com access. A policy applied moments earlier (the
// usual case — the bucket is deployed in the same stack) can still be
// propagating, surfacing as a bucket-mentioning ValidationException (patched
// in distilled into the typed ReportBucketNotVerified tag). Bounded retry:
// 8 recurrences x 3s ≈ 24s. Explicit return annotation so the Retry.Return
// conditional type never leaks into declaration emit.
const retryBucketVerification = <A, E extends { readonly _tag: string }, R>(
  self: Effect.Effect<A, E, R>,
): Effect.Effect<A, E, R> =>
  Effect.retry(self, {
    while: (e) => e._tag === "ReportBucketNotVerified",
    schedule: Schedule.max([Schedule.fixed("3 seconds"), Schedule.recurs(8)]),
  });

export interface ReportDefinitionProps {
  /**
   * Name of the report (also the prefix of the report files in S3). Must be
   * unique in the account; up to 256 characters of `A-Za-z0-9!\-_.*'()`.
   * If omitted, a unique name is generated from the app, stage, and logical
   * ID.
   *
   * Changing the name replaces the report definition.
   */
  reportName?: string;
  /**
   * The granularity of line items in the report.
   */
  timeUnit: "HOURLY" | "DAILY" | "MONTHLY" | (string & {});
  /**
   * The format the report files are generated in.
   */
  format: "textORcsv" | "Parquet" | (string & {});
  /**
   * The compression applied to the report files. Must be `Parquet` when
   * `format` is `Parquet`.
   */
  compression: "ZIP" | "GZIP" | "Parquet" | (string & {});
  /**
   * Additional detail included in the report, e.g. `["RESOURCES"]` to include
   * individual resource IDs.
   * @default []
   */
  additionalSchemaElements?: (
    | "RESOURCES"
    | "SPLIT_COST_ALLOCATION_DATA"
    | "MANUAL_DISCOUNT_COMPATIBILITY"
    | (string & {})
  )[];
  /**
   * Name of the S3 bucket the report is delivered to. The bucket policy must
   * allow `billingreports.amazonaws.com` to call `s3:GetBucketAcl`,
   * `s3:GetBucketPolicy`, and `s3:PutObject`.
   */
  s3Bucket: string;
  /**
   * S3 key prefix the report files are delivered under.
   */
  s3Prefix: string;
  /**
   * The region the delivery bucket lives in, e.g. `us-east-1`.
   */
  s3Region: string;
  /**
   * Artifacts AWS additionally prepares the report for (`REDSHIFT`,
   * `QUICKSIGHT`, or `ATHENA`). `ATHENA` requires Parquet format/compression
   * and `OVERWRITE_REPORT` versioning, and cannot be combined with the other
   * artifacts.
   */
  additionalArtifacts?: ("REDSHIFT" | "QUICKSIGHT" | "ATHENA" | (string & {}))[];
  /**
   * Whether AWS updates previously delivered reports when charges are applied
   * retroactively (refunds, credits, RI fees).
   * @default true
   */
  refreshClosedReports?: boolean;
  /**
   * Whether each report update overwrites the previous version
   * (`OVERWRITE_REPORT`) or is delivered alongside it (`CREATE_NEW_REPORT`).
   * @default "CREATE_NEW_REPORT"
   */
  reportVersioning?: "CREATE_NEW_REPORT" | "OVERWRITE_REPORT" | (string & {});
  /**
   * ARN of the billing view the report is scoped to. Omit for the account's
   * primary billing view.
   *
   * Changing the billing view replaces the report definition.
   */
  billingViewArn?: string;
  /**
   * Tags to apply to the report definition.
   */
  tags?: Record<string, string>;
}

export interface ReportDefinition extends Resource<
  "AWS.CostAndUsageReport.ReportDefinition",
  ReportDefinitionProps,
  {
    /** Name of the report definition. */
    reportName: string;
    /** ARN of the report definition. */
    reportArn: string;
    /** Granularity of the report (`HOURLY`, `DAILY`, `MONTHLY`). */
    timeUnit: string;
    /** File format of the report (`textORcsv` or `Parquet`). */
    format: string;
    /** Compression applied to report files (`ZIP`, `GZIP`, `Parquet`). */
    compression: string;
    /** Name of the S3 bucket the report is delivered to. */
    s3Bucket: string;
    /** S3 key prefix the report is delivered under. */
    s3Prefix: string;
    /** Region of the delivery S3 bucket. */
    s3Region: string;
  },
  never,
  Providers
> {}

/**
 * An AWS Cost and Usage Report (CUR) definition — the most granular billing
 * data AWS offers, delivered as CSV or Parquet files to an S3 bucket you own.
 *
 * The CUR API is a global service hosted only in `us-east-1`; this resource
 * pins every control-plane call there regardless of the stack region. The
 * delivery bucket may live in any region (declared via `s3Region`) but its
 * bucket policy must grant `billingreports.amazonaws.com` the
 * `s3:GetBucketAcl`, `s3:GetBucketPolicy`, and `s3:PutObject` permissions —
 * report creation fails validation otherwise.
 *
 * Report definitions are free; you pay only for the S3 storage of delivered
 * reports.
 *
 * ### Creating a Report
 * **Example:** Daily CSV report with resource IDs
 * ```typescript
 * import * as AWS from "@alchemy.run/aws";
 *
 * const bucket = yield* AWS.S3.Bucket("ReportBucket", {
 *   bucketName: "my-cur-reports",
 *   policy: [
 *     {
 *       Effect: "Allow",
 *       Principal: { Service: "billingreports.amazonaws.com" },
 *       Action: ["s3:GetBucketAcl", "s3:GetBucketPolicy"],
 *       Resource: "arn:aws:s3:::my-cur-reports",
 *     },
 *     {
 *       Effect: "Allow",
 *       Principal: { Service: "billingreports.amazonaws.com" },
 *       Action: ["s3:PutObject"],
 *       Resource: "arn:aws:s3:::my-cur-reports/*",
 *     },
 *   ],
 * });
 *
 * const report = yield* AWS.CostAndUsageReport.ReportDefinition("Costs", {
 *   timeUnit: "DAILY",
 *   format: "textORcsv",
 *   compression: "GZIP",
 *   additionalSchemaElements: ["RESOURCES"],
 *   s3Bucket: bucket.bucketName,
 *   s3Prefix: "cur",
 *   s3Region: bucket.region,
 * });
 * ```
 *
 * **Example:** Athena-ready Parquet report
 * ```typescript
 * const report = yield* AWS.CostAndUsageReport.ReportDefinition("Athena", {
 *   timeUnit: "HOURLY",
 *   format: "Parquet",
 *   compression: "Parquet",
 *   additionalArtifacts: ["ATHENA"],
 *   reportVersioning: "OVERWRITE_REPORT",
 *   s3Bucket: bucket.bucketName,
 *   s3Prefix: "athena-cur",
 *   s3Region: bucket.region,
 * });
 * ```
 *
 * @resource
 */
export const ReportDefinition = Resource<ReportDefinition>(
  "AWS.CostAndUsageReport.ReportDefinition",
);

const toTagRecord = (tags: cur.Tag[] | undefined): Record<string, string> =>
  Object.fromEntries((tags ?? []).map((t) => [t.Key, t.Value]));

const setEquals = (
  left: readonly string[] | undefined,
  right: readonly string[] | undefined,
): boolean => {
  const l = [...(left ?? [])].sort();
  const r = [...(right ?? [])].sort();
  return l.length === r.length && l.every((v, i) => v === r[i]);
};

export const ReportDefinitionProvider = () =>
  Provider.effect(
    ReportDefinition,
    Effect.gen(function* () {
      const createName = Effect.fn(function* (
        id: string,
        props: { reportName?: string | undefined },
      ) {
        return props.reportName ?? (yield* createPhysicalName({ id, maxLength: 256 }));
      });

      const reportArn = (accountId: string, name: string) =>
        `arn:aws:cur:${CUR_REGION}:${accountId}:definition/${name}`;

      // There is no Get operation — observe by scanning the (small,
      // account-max ~10 entries) paginated list.
      const findReport = Effect.fn(function* (name: string) {
        const pages = yield* pin(cur.describeReportDefinitions.pages({}).pipe(Stream.runCollect));
        return Array.from(pages)
          .flatMap((page) => page.ReportDefinitions ?? [])
          .find((r) => r.ReportName === name);
      });

      const readTags = (name: string) =>
        pin(cur.listTagsForResource({ ReportName: name })).pipe(
          Effect.map((r) => toTagRecord(r.Tags)),
          Effect.catchTag("ResourceNotFoundException", () =>
            Effect.succeed({} as Record<string, string>),
          ),
        );

      const buildDefinition = (
        name: string,
        props: ReportDefinitionProps,
      ): cur.ReportDefinition => ({
        ReportName: name,
        TimeUnit: props.timeUnit,
        Format: props.format,
        Compression: props.compression,
        AdditionalSchemaElements: props.additionalSchemaElements ?? [],
        S3Bucket: props.s3Bucket,
        S3Prefix: props.s3Prefix,
        S3Region: props.s3Region,
        AdditionalArtifacts: props.additionalArtifacts,
        RefreshClosedReports: props.refreshClosedReports,
        ReportVersioning: props.reportVersioning,
        BillingViewArn: props.billingViewArn,
      });

      const needsModify = (
        observed: cur.ReportDefinition,
        desired: cur.ReportDefinition,
      ): boolean =>
        observed.TimeUnit !== desired.TimeUnit ||
        observed.Format !== desired.Format ||
        observed.Compression !== desired.Compression ||
        observed.S3Bucket !== desired.S3Bucket ||
        observed.S3Prefix !== desired.S3Prefix ||
        observed.S3Region !== desired.S3Region ||
        !setEquals(observed.AdditionalSchemaElements, desired.AdditionalSchemaElements) ||
        !setEquals(observed.AdditionalArtifacts, desired.AdditionalArtifacts) ||
        (desired.RefreshClosedReports !== undefined &&
          observed.RefreshClosedReports !== desired.RefreshClosedReports) ||
        (desired.ReportVersioning !== undefined &&
          observed.ReportVersioning !== desired.ReportVersioning);

      const toAttributes = (accountId: string, observed: cur.ReportDefinition) => ({
        reportName: observed.ReportName,
        reportArn: reportArn(accountId, observed.ReportName),
        timeUnit: observed.TimeUnit,
        format: observed.Format,
        compression: observed.Compression,
        s3Bucket: observed.S3Bucket,
        s3Prefix: observed.S3Prefix,
        s3Region: observed.S3Region,
      });

      const syncTags = Effect.fn(function* (name: string, desiredTags: Record<string, string>) {
        // Diff against OBSERVED cloud tags — adoption may bring foreign tags.
        const observedTags = yield* readTags(name);
        const { upsert, removed } = diffTags(observedTags, desiredTags);
        if (upsert.length > 0) {
          yield* pin(cur.tagResource({ ReportName: name, Tags: upsert }));
        }
        if (removed.length > 0) {
          yield* pin(cur.untagResource({ ReportName: name, TagKeys: removed }));
        }
      });

      return ReportDefinition.Provider.of({
        stables: ["reportName", "reportArn"],
        list: () =>
          Effect.gen(function* () {
            const { accountId } = yield* AWSEnvironment.current;
            const pages = yield* pin(
              cur.describeReportDefinitions.pages({}).pipe(Stream.runCollect),
            );
            return Array.from(pages)
              .flatMap((page) => page.ReportDefinitions ?? [])
              .map((r) => toAttributes(accountId, r));
          }),
        read: Effect.fn(function* ({ id, olds, output }) {
          const { accountId } = yield* AWSEnvironment.current;
          const name = output?.reportName ?? (yield* createName(id, olds ?? {}));
          const observed = yield* findReport(name);
          if (!observed) return undefined;
          const attrs = toAttributes(accountId, observed);
          const tags = yield* readTags(name);
          return (yield* hasAlchemyTags(id, tags)) ? attrs : Unowned(attrs);
        }),
        diff: Effect.fn(function* ({ id, olds, news }) {
          if (!isResolved(news)) return;
          const oldName = yield* createName(id, olds ?? {});
          const newName = yield* createName(id, news);
          if (oldName !== newName) return { action: "replace" } as const;
          if (olds && olds.billingViewArn !== news.billingViewArn) {
            return { action: "replace" } as const;
          }
        }),
        reconcile: Effect.fn(function* ({ id, news, output, session }) {
          const { accountId } = yield* AWSEnvironment.current;
          const name = output?.reportName ?? (yield* createName(id, news));
          const internalTags = yield* createInternalTags(id);
          const desiredTags = { ...news.tags, ...internalTags };
          const desired = buildDefinition(name, news);

          // OBSERVE — cloud state is authoritative; output is only a name cache.
          const observed = yield* findReport(name);

          if (!observed) {
            // ENSURE — create; tolerate the duplicate-name race by converging
            // through modify instead.
            yield* cur
              .putReportDefinition({
                ReportDefinition: desired,
                Tags: Object.entries(desiredTags).map(([Key, Value]) => ({
                  Key,
                  Value,
                })),
              })
              .pipe(
                pin,
                retryBucketVerification,
                Effect.catchTag("DuplicateReportNameException", () =>
                  pin(
                    cur.modifyReportDefinition({
                      ReportName: name,
                      ReportDefinition: desired,
                    }),
                  ),
                ),
              );
          } else if (needsModify(observed, desired)) {
            // SYNC — apply the delta only; skip the API entirely on no-op.
            yield* cur
              .modifyReportDefinition({
                ReportName: name,
                ReportDefinition: desired,
              })
              .pipe(pin, retryBucketVerification);
          }

          // SYNC TAGS — against observed cloud tags.
          yield* syncTags(name, desiredTags);

          yield* session.note(name);
          const final = yield* findReport(name);
          return toAttributes(accountId, final ?? desired);
        }),
        delete: Effect.fn(function* ({ output }) {
          // Idempotent: DeleteReportDefinition's error semantics for a missing
          // report are undocumented, so observe first and treat absent as done.
          const observed = yield* findReport(output.reportName);
          if (!observed) return;
          yield* pin(cur.deleteReportDefinition({ ReportName: output.reportName }));
        }),
      });
    }),
  );