sailfork / t3code-github / .repos/ alchemy-effect/ packages/ aws/ src/ SES/ ReceiptRule.ts

import * as ses from "@distilled.cloud/aws/ses";
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 Schedule from "effect/Schedule";
import type { Providers } from "../Providers.ts";

/**
 * Whether SES requires (`Require`) or merely prefers (`Optional`) a TLS
 * connection from the sending mail server before accepting a message that
 * matches this rule.
 */
export type ReceiptRuleTlsPolicy = ses.TlsPolicy;

/**
 * A single receipt-rule action. Pass the distilled action shape directly — one
 * of `S3Action`, `SNSAction`, `LambdaAction`, `BounceAction`, `AddHeaderAction`,
 * `StopAction`, `WorkmailAction`, or `ConnectAction`. Actions run in array
 * order; resource ARNs (bucket, topic, function) are supplied by the caller.
 */
export type ReceiptRuleAction = ses.ReceiptAction;

export interface ReceiptRuleProps {
  /**
   * Name of the receipt rule set this rule belongs to. Typically the
   * `ruleSetName` output of a `SES.ReceiptRuleSet`. Changing it replaces the
   * rule.
   */
  ruleSetName: string;
  /**
   * Name of the receipt rule. May contain letters, numbers, dashes,
   * underscores and periods, up to 64 characters. If omitted, a deterministic
   * physical name is generated from the app, stage, and logical ID. Changing
   * the name replaces the rule.
   */
  ruleName?: string;
  /**
   * Whether the rule is enabled. Disabled rules are skipped during receipt
   * processing.
   * @default true
   */
  enabled?: boolean;
  /**
   * Whether SES scans incoming messages that match this rule for spam and
   * viruses.
   * @default true
   */
  scanEnabled?: boolean;
  /**
   * Whether SES accepts email over a clear text connection (`Optional`) or
   * requires TLS (`Require`) before applying this rule.
   * @default "Optional"
   */
  tlsPolicy?: ReceiptRuleTlsPolicy;
  /**
   * Recipient email addresses or domains this rule applies to. An empty or
   * omitted list matches all recipients.
   */
  recipients?: string[];
  /**
   * Name of an existing rule in the same rule set after which this rule should
   * be placed. Omit to place the rule at the top of the rule set. Rules are
   * evaluated in order.
   */
  after?: string;
  /**
   * Ordered list of actions SES performs when a message matches this rule
   * (deliver to S3, publish to SNS, invoke Lambda, bounce, add a header, stop
   * processing, etc.).
   */
  actions?: ReceiptRuleAction[];
}

export interface ReceiptRule extends Resource<
  "AWS.SES.ReceiptRule",
  ReceiptRuleProps,
  {
    /** Name of the rule set this rule belongs to. */
    ruleSetName: string;
    /** Name of the receipt rule. */
    ruleName: string;
  },
  never,
  Providers
> {}

/**
 * An Amazon SES receipt rule — a matcher plus an ordered list of actions that
 * SES applies to inbound email received through the parent
 * `SES.ReceiptRuleSet`.
 *
 * Actions are passed as the raw distilled action shapes (no marshalling): the
 * caller supplies bucket names, topic ARNs, and function ARNs directly.
 * ### Creating Rules
 * **Example:** Deliver Matching Mail to S3
 * ```typescript
 * import * as SES from "@alchemy.run/aws/SES";
 *
 * const ruleSet = yield* SES.ReceiptRuleSet("Inbound", {});
 * const rule = yield* SES.ReceiptRule("ToBucket", {
 *   ruleSetName: ruleSet.ruleSetName,
 *   recipients: ["support@example.com"],
 *   actions: [
 *     { S3Action: { BucketName: "my-inbound-mail" } },
 *   ],
 * });
 * ```
 *
 * **Example:** Invoke a Lambda and Add a Header
 * ```typescript
 * const rule = yield* SES.ReceiptRule("Process", {
 *   ruleSetName: ruleSet.ruleSetName,
 *   tlsPolicy: "Require",
 *   scanEnabled: true,
 *   actions: [
 *     { AddHeaderAction: { HeaderName: "X-Inbound", HeaderValue: "ses" } },
 *     { LambdaAction: { FunctionArn: fn.functionArn, InvocationType: "Event" } },
 *   ],
 * });
 * ```
 *
 * ### Ordering Rules
 * **Example:** Place a Rule After Another
 * ```typescript
 * // A BounceAction's Sender must be a verified SES identity — SES rejects the
 * // rule with IdentityNotVerified at create/update time otherwise.
 * const first = yield* SES.ReceiptRule("First", {
 *   ruleSetName: ruleSet.ruleSetName,
 *   actions: [{ StopAction: { Scope: "RuleSet" } }],
 * });
 * const second = yield* SES.ReceiptRule("Second", {
 *   ruleSetName: ruleSet.ruleSetName,
 *   after: first.ruleName,
 *   actions: [{ BounceAction: {
 *     SmtpReplyCode: "550",
 *     Message: "Mailbox does not exist",
 *     Sender: "mailer-daemon@example.com",
 *   } }],
 * });
 * ```
 *
 * @resource
 */
export const ReceiptRule = Resource<ReceiptRule>("AWS.SES.ReceiptRule");

/**
 * The name of the rule immediately preceding `ruleName` in the rule set's
 * ordered rule list, or `undefined` when the rule is first (or absent). This is
 * the observed value of the `after` position.
 */
const observedPredecessor = (
  rules: ReadonlyArray<ses.ReceiptRule>,
  ruleName: string,
): string | undefined => {
  const index = rules.findIndex((rule) => rule.Name === ruleName);
  if (index <= 0) return undefined;
  return rules[index - 1]?.Name;
};

/**
 * An IAM role can exist before SES is able to assume it, so create and
 * update retry that specific rejection while the role propagates.
 */
const retryRolePropagation = <A, R>(
  effect: Effect.Effect<A, ses.CreateReceiptRuleError | ses.UpdateReceiptRuleError, R>,
) =>
  effect.pipe(
    Effect.retry({
      while: (e) => e._tag === "ReceiptRuleRoleNotAssumable",
      schedule: Schedule.spaced("5 seconds"),
      times: 12,
    }),
  );

export const ReceiptRuleProvider = () =>
  Provider.effect(
    ReceiptRule,
    Effect.gen(function* () {
      const createName = Effect.fn(function* (
        id: string,
        props: Pick<ReceiptRuleProps, "ruleName">,
      ) {
        return props.ruleName ?? (yield* createPhysicalName({ id, maxLength: 64 }));
      });

      const describeRule = Effect.fn(function* (ruleSetName: string, ruleName: string) {
        return yield* ses
          .describeReceiptRule({ RuleSetName: ruleSetName, RuleName: ruleName })
          .pipe(
            Effect.catchTags({
              RuleDoesNotExistException: () => Effect.undefined,
              RuleSetDoesNotExistException: () => Effect.undefined,
            }),
          );
      });

      const buildRule = (ruleName: string, props: ReceiptRuleProps): ses.ReceiptRule => ({
        Name: ruleName,
        // The classic API defaults an omitted Enabled/ScanEnabled to FALSE —
        // apply the documented defaults explicitly so an undeclared rule is
        // enabled (a silently disabled rule bounces all inbound mail).
        Enabled: props.enabled ?? true,
        TlsPolicy: props.tlsPolicy,
        Recipients: props.recipients,
        Actions: props.actions,
        ScanEnabled: props.scanEnabled ?? true,
      });

      return ReceiptRule.Provider.of({
        stables: ["ruleSetName", "ruleName"],

        // Rules are sub-resources keyed entirely by their parent rule set;
        // there is no flat account-level enumeration, so nuke handles them via
        // the parent rule set's deletion.
        list: () => Effect.succeed([]),

        read: Effect.fn(function* ({ id, olds, output }) {
          const ruleSetName = output?.ruleSetName ?? olds.ruleSetName;
          if (!ruleSetName) return undefined;
          const ruleName = output?.ruleName ?? (yield* createName(id, olds));
          const found = yield* describeRule(ruleSetName, ruleName);
          return found?.Rule ? { ruleSetName, ruleName } : undefined;
        }),

        diff: Effect.fn(function* ({ id, news, olds }) {
          if (!isResolved(news)) return undefined;
          if (news.ruleSetName !== olds.ruleSetName) {
            return { action: "replace" } as const;
          }
          const oldName = yield* createName(id, olds);
          const newName = yield* createName(id, news);
          if (oldName !== newName) {
            return { action: "replace" } as const;
          }
        }),

        reconcile: Effect.fn(function* ({ id, news, output }) {
          const ruleSetName = news.ruleSetName;
          const ruleName = output?.ruleName ?? (yield* createName(id, news));
          const rule = buildRule(ruleName, news);

          // OBSERVE — cloud state is authoritative.
          const observed = yield* describeRule(ruleSetName, ruleName);

          // ENSURE / SYNC — a single full-replace call converges the rule's
          // matcher and actions whether it is missing or already present.
          if (observed?.Rule === undefined) {
            yield* ses
              .createReceiptRule({
                RuleSetName: ruleSetName,
                After: news.after,
                Rule: rule,
              })
              .pipe(
                retryRolePropagation,
                Effect.catchTag("AlreadyExistsException", () =>
                  ses
                    .updateReceiptRule({
                      RuleSetName: ruleSetName,
                      Rule: rule,
                    })
                    .pipe(retryRolePropagation),
                ),
              );
          } else {
            yield* ses
              .updateReceiptRule({
                RuleSetName: ruleSetName,
                Rule: rule,
              })
              .pipe(retryRolePropagation);
          }

          // SYNC POSITION — updateReceiptRule never moves the rule, so diff the
          // observed predecessor against the desired `after` and reposition
          // only on a mismatch.
          const ruleSet = yield* ses.describeReceiptRuleSet({
            RuleSetName: ruleSetName,
          });
          const predecessor = observedPredecessor(ruleSet.Rules ?? [], ruleName);
          if (predecessor !== news.after) {
            yield* ses.setReceiptRulePosition({
              RuleSetName: ruleSetName,
              RuleName: ruleName,
              After: news.after,
            });
          }

          return { ruleSetName, ruleName };
        }),

        delete: Effect.fn(function* ({ output }) {
          // deleteReceiptRule is idempotent for a missing rule; a missing rule
          // set means the rule is already gone.
          yield* ses
            .deleteReceiptRule({
              RuleSetName: output.ruleSetName,
              RuleName: output.ruleName,
            })
            .pipe(Effect.catchTag("RuleSetDoesNotExistException", () => Effect.void));
        }),
      });
    }),
  );