[Pulumi Custom Resource] AWS SNS E-Mail Subscription

// index.ts
// ... pulumi imports
import {SnsEmailSubscription} from "./sns-email-subscription";

const billingTopic = new aws.sns.Topic("topic");
const emailSubscription = new SnsEmailSubscription("subscription", {
  topic: billingTopic.arn,
  endpoint: cfg.billingAlarmEmail,
  region: cfg.region,
  waitMs: 10000,
  validationMethod: "poll", // or "sleep" or undefined to not wait
});

// sns-email-subscription.ts
import * as pulumi from "@pulumi/pulumi";
import {SNS} from "aws-sdk";
import isEmail from "validator/lib/isEmail";
import {
  CheckFailure,
  CheckResult,
  CreateResult,
  DiffResult,
  ReadResult,
  Resource,
  ResourceProvider,
} from "@pulumi/pulumi/dynamic";

type ValidationMethod = "sleep" | "poll" | undefined;

export type SnsInputs = {
  topic: string | pulumi.Input<string>;
  endpoint: string | pulumi.Input<string>;
  region: string | pulumi.Input<string>;
  validationMethod?: ValidationMethod | pulumi.Input<ValidationMethod>;
  waitMs?: number | pulumi.Input<number>;
  maxRetry?: number | pulumi.Input<number>;
};

type ProviderInputs = {
  topic: string;
  endpoint: string;
  region: string;
  validationMethod?: ValidationMethod;
  waitMs?: number;
  maxRetry?: number;
};

// https://gist.github.com/joepie91/2664c85a744e6bd0629c
// sometimes I'm just to lazy to think about certain things so I just search 🤷‍♂️
const sleep = (duration: number) =>
  new Promise((resolve) => setTimeout(resolve, duration));

const subscriptionValidation = async (
  id: string,
  props: ProviderInputs,
): Promise<boolean> => {
  const maxRetry = props.maxRetry ?? 5;
  const sns = new SNS({apiVersion: "2010-03-31", region: props.region});
  let confirmed = false;
  let intents = 0;
  while (intents < maxRetry && !confirmed) {
    intents++;
    await sleep(props.waitMs ?? 10000);
    const request = sns.getSubscriptionAttributes({SubscriptionArn: id});
    const response = await request.promise();
    // note that AWS is returning strings here
    if (response?.Attributes?.PendingConfirmation === "false") {
      confirmed = true;
    }
  }
  return true;
};

const snsEmailSubscriptionProvider: ResourceProvider = {
  async check(
    olds: ProviderInputs,
    news: ProviderInputs,
  ): Promise<CheckResult> {
    const failures: CheckFailure[] = [];

    if (!news.topic) {
      failures.push({
        property: "topic",
        reason: "Please provide a valid SNS Topic ARN",
      });
    }

    // ensuring it's a string to provide our own error message
    if (!isEmail(news.endpoint || "")) {
      failures.push({
        property: "endpoint",
        reason: "Please provide a valid email address",
      });
    }

    if (!news.region) {
      failures.push({
        property: "region",
        reason: "Please provide the AWS region of the corresponding SNS Topic",
      });
    }

    if (news.maxRetry !== undefined && news.maxRetry < 5) {
      failures.push({
        property: "maxRetry",
        reason: "Please provide a number greater than 4",
      });
    }

    if (news.waitMs !== undefined && news.waitMs < 1000) {
      failures.push({
        property: "waitMs",
        reason: "Please provide a number >= 1000",
      });
    }

    if (!["sleep", "poll", undefined].includes(news.validationMethod)) {
      failures.push({
        property: "validationMethod",
        reason: `Has to be one of "sleep" | "poll" | undefined`,
      });
    }

    if (failures.length > 0) {
      return {failures: failures};
    }

    return {inputs: news};
  },

  async create(props: ProviderInputs): Promise<CreateResult> {
    const sns = new SNS({apiVersion: "2010-03-31", region: props.region});
    const {topic, endpoint} = props;

    const params: SNS.SubscribeInput = {
      Protocol: "email",
      TopicArn: topic,
      Endpoint: endpoint,
      // That's the reason why it shouldn't be necessary to wait
      // as AWS provides us already the ARN if it's needed at all
      // note that the resource returns the subscription ARN as `id`
      ReturnSubscriptionArn: true,
    };

    try {
      const subscription = sns.subscribe(params);
      const response = await subscription.promise();
      const subscriptionArn = response.SubscriptionArn;

      if (!subscriptionArn) {
        throw new Error("Missing subscriptionArn");
      }

      if (props.validationMethod === "sleep") {
        await sleep(props.waitMs ?? 60 * 1000);
      } else if (props.validationMethod === "poll") {
        await subscriptionValidation(subscriptionArn, props);
      }

      return {id: subscriptionArn, outs: props};
    } catch (error) {
      console.log(error.message);
      throw error;
    }
  },

  // diff will be used to determine if the resource needs to be changed
  // it allows to decide between an update or a full replacement
  // in this case, as SNS Subscriptions can't be replaced as far as I know
  // we force it to replace if any of the properties has changed
  async diff(
    id: string,
    olds: ProviderInputs,
    news: ProviderInputs,
  ): Promise<DiffResult> {
    const replaces: string[] = [];
    let changes = false;
    let deleteBeforeReplace = false;

    if (
      olds.topic !== news.topic ||
      olds.endpoint !== news.endpoint ||
      olds.region !== news.region
    ) {
      changes = true;
      // we could decide to delete the old subscription before creating the new one
      // from my testing it doesn't seem necessary
      // so I'll let Pulumi delete it after the new one has been created
      // deleteBeforeReplace = true;

      // For simplicity I just push all properties into the replaces array
      // The replaces array is what forces Pulumi to replace instead of update
      replaces.push(...Object.keys(news));
    }

    return {changes, replaces, deleteBeforeReplace};
  },

  async delete(id: string, outs: ProviderInputs) {
    const sns = new SNS({apiVersion: "2010-03-31", region: outs.region});
    const params: SNS.UnsubscribeInput = {SubscriptionArn: id};
    const subscription = sns.unsubscribe(params);
    await subscription.promise();
  },

  // I'm actually not sure when exactly this method will be called
  // or what it's used for 🤷‍♂️ 😅
  async read(id: string, props: ProviderInputs): Promise<ReadResult> {
    const sns = new SNS({apiVersion: "2010-03-31", region: props.region});
    const params: SNS.GetSubscriptionAttributesInput = {SubscriptionArn: id};
    const subscription = sns.getSubscriptionAttributes(params);
    const response = await subscription.promise();
    return {id, props: {...props, ...response}};
  },
};

export class SnsEmailSubscription extends Resource {
  /**
   * Creates a new SNS E-Mail Subscription
   *
   * @param topic - The SNS topic ARN
   * @param endpoint - The e-mail address
   * @param region - The AWS region of the SNS topic
   * @param [validationMethod] - The method used to "validate" the successfull email confirmation, one of "sleep" | "poll" | undefined
   * @param [waitMs] - Time in ms to wait for you to confirm the subscription defaults to 1 min in "sleep" and 10sec in "poll" mode. Has to be greater than 999ms
   * @param [maxRetry=5] - How often the "poll" "validationMethod should retry
   */
  constructor(
    name: string,
    props: SnsInputs,
    opts?: pulumi.CustomResourceOptions,
  ) {
    super(snsEmailSubscriptionProvider, name, props, opts);
  }
}