sailfork / t3code-github / .repos/ alchemy-effect/ packages/ aws/ src/ Logs/ Destination.ts

import * as logs from "@distilled.cloud/aws/cloudwatch-logs";
import { isResolved } from "alchemy/Diff";
import { createPhysicalName } from "alchemy/PhysicalName";
import * as Provider from "alchemy/Provider";
import { Resource } from "alchemy/Resource";
import * as Effect from "effect/Effect";
import * as Option from "effect/Option";
import * as Schedule from "effect/Schedule";
import * as Stream from "effect/Stream";
import type { PolicyDocument } from "../IAM/Policy.ts";
import type { Providers } from "../Providers.ts";

export interface DestinationProps {
  /**
   * Name of the destination. The destination name is its identity within the
   * account and region (put semantics upsert by name). If omitted, a unique
   * name is generated. Changing this value replaces the destination.
   */
  destinationName?: string;
  /**
   * ARN of the physical target that receives the log events — a Kinesis
   * stream in this account.
   */
  targetArn: string;
  /**
   * ARN of an IAM role that CloudWatch Logs assumes to write to the target.
   * The role must trust `logs.amazonaws.com`.
   */
  roleArn: string;
  /**
   * Access policy governing which accounts may create subscription filters
   * against this destination, either as a JSON string or a structured
   * document. Required before another account can subscribe.
   */
  accessPolicy?: PolicyDocument | string;
}

export interface Destination extends Resource<
  "AWS.Logs.Destination",
  DestinationProps,
  {
    destinationName: string;
    destinationArn: string;
    targetArn: string;
    roleArn: string;
    accessPolicy?: string;
  },
  never,
  Providers
> {}

/**
 * A CloudWatch Logs destination — a cross-account subscription target that
 * forwards log events to a Kinesis stream. Producers in other accounts create
 * subscription filters whose `destinationArn` points at this destination;
 * the `accessPolicy` controls which accounts may subscribe.
 * ### Cross-Account Log Fan-Out
 * **Example:** Kinesis-Backed Destination
 * ```typescript
 * const destination = yield* Destination("CentralLogs", {
 *   targetArn: stream.streamArn,
 *   roleArn: role.roleArn,
 *   accessPolicy: {
 *     Version: "2012-10-17",
 *     Statement: [
 *       {
 *         Effect: "Allow",
 *         Principal: { AWS: "123456789012" },
 *         Action: ["logs:PutSubscriptionFilter"],
 *         Resource: "*",
 *       },
 *     ],
 *   },
 * });
 * ```
 *
 * @resource
 */
export const Destination = Resource<Destination>("AWS.Logs.Destination");

/**
 * `putDestination` validates that CloudWatch Logs can assume the delivery role
 * at call time; when the role was created in the same deploy this fails with
 * `InvalidParameterException` until IAM propagates. Bounded retry.
 *
 * NOTE: explicit return annotation is load-bearing — an inlined `Effect.retry`
 * in provider lifecycle code widens the provider layer during declaration emit
 * (see PATTERNS.md §7).
 */
const retryThroughRolePropagation = <A, E extends { _tag: string }, R>(
  self: Effect.Effect<A, E, R>,
): Effect.Effect<A, E, R> =>
  Effect.retry(self, {
    while: (e) => e._tag === "InvalidParameterException" || e._tag === "OperationAbortedException",
    schedule: Schedule.max([Schedule.fixed("3 seconds"), Schedule.recurs(9)]),
  });

export const DestinationProvider = () =>
  Provider.effect(
    Destination,
    Effect.gen(function* () {
      const toDestinationName = (id: string, props: { destinationName?: string } = {}) =>
        props.destinationName
          ? Effect.succeed(props.destinationName)
          : createPhysicalName({ id, maxLength: 512 });

      const toPolicyString = (policy: PolicyDocument | string | undefined) =>
        policy === undefined
          ? undefined
          : typeof policy === "string"
            ? policy
            : JSON.stringify(policy);

      const observe = Effect.fn(function* (destinationName: string) {
        return yield* logs.describeDestinations
          .items({ DestinationNamePrefix: destinationName })
          .pipe(
            Stream.filter((destination) => destination.destinationName === destinationName),
            Stream.runHead,
            Effect.map(Option.getOrUndefined),
          );
      });

      return {
        stables: ["destinationName", "destinationArn"],
        list: () =>
          logs.describeDestinations.pages({}).pipe(
            Stream.runCollect,
            Effect.map((chunk) =>
              Array.from(chunk)
                .flatMap((page) => page.destinations ?? [])
                .filter(
                  (
                    destination,
                  ): destination is logs.Destination & {
                    destinationName: string;
                    arn: string;
                  } => destination.destinationName != null && destination.arn != null,
                )
                .map((destination) => ({
                  destinationName: destination.destinationName,
                  destinationArn: destination.arn,
                  targetArn: destination.targetArn ?? "",
                  roleArn: destination.roleArn ?? "",
                  accessPolicy: destination.accessPolicy,
                })),
            ),
          ),
        diff: Effect.fn(function* ({ id, olds, news }) {
          if (!isResolved(news)) return;
          if ((yield* toDestinationName(id, olds)) !== (yield* toDestinationName(id, news))) {
            return { action: "replace" } as const;
          }
        }),
        read: Effect.fn(function* ({ id, olds, output }) {
          const destinationName =
            output?.destinationName ?? (yield* toDestinationName(id, olds ?? {}));
          const observed = yield* observe(destinationName);
          if (!observed?.arn) return undefined;
          return {
            destinationName,
            destinationArn: observed.arn,
            targetArn: observed.targetArn ?? "",
            roleArn: observed.roleArn ?? "",
            accessPolicy: observed.accessPolicy,
          };
        }),
        reconcile: Effect.fn(function* ({ id, news, output, session }) {
          const destinationName = output?.destinationName ?? (yield* toDestinationName(id, news));
          const desiredPolicy = toPolicyString(news.accessPolicy);

          // Observe — putDestination upserts by name; skip when target/role
          // already match.
          let observed = yield* observe(destinationName);
          if (observed?.targetArn !== news.targetArn || observed?.roleArn !== news.roleArn) {
            const put = yield* retryThroughRolePropagation(
              logs.putDestination({
                destinationName,
                targetArn: news.targetArn,
                roleArn: news.roleArn,
              }),
            );
            observed = put.destination ?? (yield* observe(destinationName));
          }

          // Sync access policy against the observed policy.
          if (desiredPolicy !== undefined && observed?.accessPolicy !== desiredPolicy) {
            yield* retryThroughRolePropagation(
              logs.putDestinationPolicy({
                destinationName,
                accessPolicy: desiredPolicy,
              }),
            );
          }

          yield* session.note(destinationName);

          return {
            destinationName,
            destinationArn: observed?.arn ?? "",
            targetArn: news.targetArn,
            roleArn: news.roleArn,
            accessPolicy: desiredPolicy,
          };
        }),
        delete: Effect.fn(function* ({ output }) {
          yield* logs.deleteDestination({ destinationName: output.destinationName }).pipe(
            Effect.retry({
              while: (error) =>
                error._tag === "OperationAbortedException" ||
                error._tag === "ServiceUnavailableException",
              schedule: Schedule.exponential(100),
              times: 8,
            }),
            Effect.catchTag("ResourceNotFoundException", () => Effect.void),
          );
        }),
      };
    }),
  );