sailfork / t3code-github / .repos/ alchemy-effect/ packages/ aws/ src/ EC2/ FlowLog.ts

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

export type FlowLogId<ID extends string = string> = `fl-${ID}`;

export type FlowLogArn<ID extends FlowLogId = FlowLogId> =
  `arn:aws:ec2:${RegionID}:${AccountID}:vpc-flow-log/${ID}`;

/**
 * Raised when `createFlowLogs`/`deleteFlowLogs` report an item in the
 * `Unsuccessful` array (these APIs never throw for per-resource failures).
 */
export class FlowLogOperationFailed extends Data.TaggedError("FlowLogOperationFailed")<{
  readonly code: string;
  readonly message: string;
}> {}

export interface FlowLogProps {
  /**
   * The type of resource to monitor.
   */
  resourceType: "VPC" | "Subnet" | "NetworkInterface";

  /**
   * The ID of the VPC, subnet, or network interface to capture flow logs for.
   * Immutable — changing it replaces the flow log.
   */
  resourceId: string;

  /**
   * The type of traffic to capture.
   * @default "ALL"
   */
  trafficType?: "ACCEPT" | "REJECT" | "ALL";

  /**
   * Where to deliver the flow logs.
   * @default "cloud-watch-logs"
   */
  logDestinationType?: "cloud-watch-logs" | "s3" | "kinesis-data-firehose";

  /**
   * The name of the CloudWatch Logs log group. Required (and only valid) when
   * `logDestinationType` is `cloud-watch-logs`.
   */
  logGroupName?: string;

  /**
   * The ARN of the IAM role that permits EC2 to publish flow logs to the
   * CloudWatch Logs group. Required when `logDestinationType` is
   * `cloud-watch-logs`.
   */
  deliverLogsPermissionArn?: string;

  /**
   * The ARN of the destination for the flow logs when `logDestinationType` is
   * `s3` (a bucket ARN, optionally with a key prefix) or
   * `kinesis-data-firehose` (a delivery stream ARN).
   */
  logDestination?: string;

  /**
   * The maximum interval, in seconds, during which a flow of packets is
   * captured and aggregated into a flow log record. Either `60` or `600`.
   * @default 600
   */
  maxAggregationInterval?: 60 | 600;

  /**
   * A custom format string for the flow log records. If omitted, the default
   * format is used.
   */
  logFormat?: string;

  /**
   * Tags to assign to the flow log.
   */
  tags?: Record<string, string>;
}

export interface FlowLog extends Resource<
  "AWS.EC2.FlowLog",
  FlowLogProps,
  {
    /**
     * The ID of the flow log (prefixed `fl-`).
     */
    flowLogId: FlowLogId;

    /**
     * The Amazon Resource Name (ARN) of the flow log.
     */
    flowLogArn: FlowLogArn;

    /**
     * The ID of the monitored resource.
     */
    resourceId: string;

    /**
     * The type of traffic captured.
     */
    trafficType: "ACCEPT" | "REJECT" | "ALL";

    /**
     * Where the flow logs are delivered.
     */
    logDestinationType: "cloud-watch-logs" | "s3" | "kinesis-data-firehose";
  },
  never,
  Providers
> {}

/**
 * A flow log captures information about the IP traffic going to and from a VPC,
 * subnet, or network interface, and publishes it to CloudWatch Logs, S3, or a
 * Kinesis Data Firehose delivery stream. Use it for network monitoring, traffic
 * analysis, and troubleshooting security-group / NACL rules.
 *
 * A flow log is immutable: every property except `tags` is fixed at creation,
 * so changing the monitored resource, destination, or traffic type replaces the
 * flow log. For CloudWatch Logs delivery you must supply a `logGroupName` and a
 * `deliverLogsPermissionArn` — an IAM role that EC2's `vpc-flow-logs` service
 * principal can assume to write to the group.
 *
 * ### Creating a Flow Log
 * **Example:** VPC Flow Log to CloudWatch Logs
 * ```typescript
 * const logGroup = yield* AWS.Logs.LogGroup("FlowLogs", {});
 *
 * const role = yield* AWS.IAM.Role("FlowLogRole", {
 *   assumeRolePolicyDocument: {
 *     Version: "2012-10-17",
 *     Statement: [{
 *       Effect: "Allow",
 *       Principal: { Service: "vpc-flow-logs.amazonaws.com" },
 *       Action: "sts:AssumeRole",
 *     }],
 *   },
 *   inlinePolicies: {
 *     deliver: {
 *       Version: "2012-10-17",
 *       Statement: [{
 *         Effect: "Allow",
 *         Action: [
 *           "logs:CreateLogStream",
 *           "logs:PutLogEvents",
 *           "logs:DescribeLogStreams",
 *         ],
 *         Resource: "*",
 *       }],
 *     },
 *   },
 * });
 *
 * const flowLog = yield* AWS.EC2.FlowLog("VpcFlowLog", {
 *   resourceType: "VPC",
 *   resourceId: myVpc.vpcId,
 *   logGroupName: logGroup.logGroupName,
 *   deliverLogsPermissionArn: role.roleArn,
 * });
 * ```
 * Captures all traffic for the VPC and delivers it to the CloudWatch Logs
 * group via the delivery role.
 *
 * **Example:** S3 Flow Log for Rejected Traffic
 * ```typescript
 * const flowLog = yield* AWS.EC2.FlowLog("RejectedTraffic", {
 *   resourceType: "Subnet",
 *   resourceId: mySubnet.subnetId,
 *   trafficType: "REJECT",
 *   logDestinationType: "s3",
 *   logDestination: bucket.bucketArn,
 * });
 * ```
 * Delivers only rejected-traffic records for a subnet directly to an S3 bucket
 * (no IAM role required for S3 delivery).
 *
 * @resource
 */
export const FlowLog = Resource<FlowLog>("AWS.EC2.FlowLog");

export const FlowLogProvider = () =>
  Provider.effect(
    FlowLog,
    Effect.gen(function* () {
      const createTags = Effect.fn(function* (id: string, tags?: Record<string, string>) {
        return {
          Name: id,
          ...(yield* createInternalTags(id)),
          ...tags,
        };
      });

      const describeFlowLog = (flowLogId: string) =>
        ec2.describeFlowLogs({ FlowLogIds: [flowLogId] }).pipe(
          Effect.map((r) => r.FlowLogs?.[0]),
          Effect.catchTag("InvalidFlowLogId.NotFound", () => Effect.undefined),
        );

      const toAttrs = (fl: ec2.FlowLog) =>
        AWSEnvironment.current.pipe(
          Effect.map((env) => ({
            flowLogId: fl.FlowLogId as FlowLogId,
            flowLogArn:
              `arn:aws:ec2:${env.region}:${env.accountId}:vpc-flow-log/${fl.FlowLogId}` as FlowLogArn,
            resourceId: fl.ResourceId!,
            trafficType: (fl.TrafficType ?? "ALL") as "ACCEPT" | "REJECT" | "ALL",
            logDestinationType: (fl.LogDestinationType ?? "cloud-watch-logs") as
              | "cloud-watch-logs"
              | "s3"
              | "kinesis-data-firehose",
          })),
        );

      return {
        stables: ["flowLogId", "flowLogArn"],

        list: () =>
          Effect.gen(function* () {
            const env = yield* AWSEnvironment.current;
            const items = yield* ec2.describeFlowLogs.pages({}).pipe(
              Stream.runCollect,
              Effect.map((chunk) =>
                Array.from(chunk).flatMap((page) =>
                  (page.FlowLogs ?? [])
                    .filter((fl): fl is ec2.FlowLog & { FlowLogId: string } => fl.FlowLogId != null)
                    .map((fl) => ({
                      flowLogId: fl.FlowLogId as FlowLogId,
                      flowLogArn:
                        `arn:aws:ec2:${env.region}:${env.accountId}:vpc-flow-log/${fl.FlowLogId}` as FlowLogArn,
                      resourceId: fl.ResourceId!,
                      trafficType: (fl.TrafficType ?? "ALL") as "ACCEPT" | "REJECT" | "ALL",
                      logDestinationType: (fl.LogDestinationType ?? "cloud-watch-logs") as
                        | "cloud-watch-logs"
                        | "s3"
                        | "kinesis-data-firehose",
                    })),
                ),
              ),
            );
            return items satisfies FlowLog["Attributes"][];
          }),

        read: Effect.fn(function* ({ output }) {
          if (!output) return undefined;
          const fl = yield* describeFlowLog(output.flowLogId);
          if (!fl) return undefined;
          return yield* toAttrs(fl);
        }),

        diff: Effect.fn(function* ({ news, olds }) {
          if (!isResolved(news)) return;
          // Flow logs are immutable except for tags — any structural change
          // replaces the resource.
          if (
            news.resourceType !== olds.resourceType ||
            news.resourceId !== olds.resourceId ||
            (news.trafficType ?? "ALL") !== (olds.trafficType ?? "ALL") ||
            (news.logDestinationType ?? "cloud-watch-logs") !==
              (olds.logDestinationType ?? "cloud-watch-logs") ||
            news.logGroupName !== olds.logGroupName ||
            news.logDestination !== olds.logDestination ||
            news.deliverLogsPermissionArn !== olds.deliverLogsPermissionArn ||
            (news.maxAggregationInterval ?? 600) !== (olds.maxAggregationInterval ?? 600) ||
            news.logFormat !== olds.logFormat
          ) {
            return { action: "replace" };
          }
          // Only tags are mutable in place.
        }),

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

          // Observe — find the flow log via the cached id, else create.
          let fl: ec2.FlowLog | undefined;
          if (output?.flowLogId) {
            fl = yield* describeFlowLog(output.flowLogId);
          }

          // Ensure — create if missing. createFlowLogs reports per-resource
          // failures in the Unsuccessful array rather than throwing.
          if (fl === undefined) {
            yield* session.note("Creating flow log...");
            // A freshly-created delivery role may not yet be assumable by the
            // flow-logs service (IAM eventual consistency) — createFlowLogs
            // reports that in Unsuccessful. Retry that (but not a genuine
            // "already exists") on a bounded schedule.
            const result = yield* ec2
              .createFlowLogs({
                ResourceType: news.resourceType,
                ResourceIds: [news.resourceId],
                TrafficType: news.trafficType ?? "ALL",
                LogDestinationType: news.logDestinationType ?? "cloud-watch-logs",
                LogGroupName: news.logGroupName,
                DeliverLogsPermissionArn: news.deliverLogsPermissionArn,
                LogDestination: news.logDestination,
                MaxAggregationInterval: news.maxAggregationInterval,
                LogFormat: news.logFormat,
                TagSpecifications: [
                  {
                    ResourceType: "vpc-flow-log",
                    Tags: createTagsList(desiredTags),
                  },
                ],
              })
              .pipe(
                Effect.flatMap((r) => {
                  const failure = r.Unsuccessful?.[0];
                  return failure
                    ? Effect.fail(
                        new FlowLogOperationFailed({
                          code: failure.Error?.Code ?? "Unknown",
                          message: failure.Error?.Message ?? "createFlowLogs failed",
                        }),
                      )
                    : Effect.succeed(r);
                }),
                Effect.retry({
                  while: (e) =>
                    e._tag === "FlowLogOperationFailed" && e.code !== "FlowLogAlreadyExists",
                  schedule: Schedule.max([Schedule.fixed(3000), Schedule.recurs(15)]),
                }),
              );
            const flowLogId = result.FlowLogIds![0]!;
            yield* session.note(`Flow log created: ${flowLogId}`);
            fl = yield* describeFlowLog(flowLogId);
            if (!fl) {
              // Freshly-created flow log not yet visible — synthesize attrs.
              return yield* toAttrs({
                FlowLogId: flowLogId,
                ResourceId: news.resourceId,
                TrafficType: news.trafficType ?? "ALL",
                LogDestinationType: news.logDestinationType ?? "cloud-watch-logs",
              } as ec2.FlowLog);
            }
          }

          const flowLogId = fl.FlowLogId!;

          // Sync tags — observed cloud tags vs desired.
          const currentTags =
            (yield* ec2
              .describeTags({
                Filters: [
                  { Name: "resource-id", Values: [flowLogId] },
                  { Name: "resource-type", Values: ["vpc-flow-log"] },
                ],
              })
              .pipe(
                Effect.map(
                  (r) =>
                    Object.fromEntries(r.Tags?.map((t) => [t.Key!, t.Value!]) ?? []) as Record<
                      string,
                      string
                    >,
                ),
              )) ?? {};
          const { removed, upsert } = diffTags(currentTags, desiredTags);
          if (removed.length > 0) {
            yield* ec2.deleteTags({
              Resources: [flowLogId],
              Tags: removed.map((key) => ({ Key: key })),
            });
          }
          if (upsert.length > 0) {
            yield* ec2.createTags({ Resources: [flowLogId], Tags: upsert });
          }

          const final = yield* describeFlowLog(flowLogId);
          return yield* toAttrs(final ?? fl);
        }),

        delete: Effect.fn(function* ({ output, session }) {
          const flowLogId = output.flowLogId;
          yield* session.note(`Deleting flow log: ${flowLogId}`);
          // deleteFlowLogs is idempotent — a missing flow log is reported in
          // Unsuccessful, which we ignore.
          yield* ec2.deleteFlowLogs({ FlowLogIds: [flowLogId] });
        }),
      };
    }),
  );