chore(util-endpoints): add endpoint ruleset library specific to aws

packages/types/src/endpoint.ts

@@ -1,3 +1,19 @@
+export interface EndpointPartition {
+  name: string;
+  dnsSuffix: string;
+  dualStackDnsSuffix: string;
+  supportsFIPS: boolean;
+  supportsDualStack: boolean;
+}
+
+export interface EndpointARN {
+  partition: string;
+  service: string;
+  region: string;
+  accountId: string;
+  resourceId: Array<string>;
+}
+
 export enum EndpointURLScheme {
   HTTP = "http",
   HTTPS = "https",

packages/util-endpoints/src/lib/aws/index.ts

@@ -0,0 +1 @@
+export * from "./partition";

packages/util-endpoints/src/lib/aws/parseArn.spec.ts

@@ -0,0 +1,79 @@
+import { EndpointARN } from "@aws-sdk/types";
+
+import { parseArn } from "./parseArn";
+
+describe(parseArn.name, () => {
+  const VALID_TEST_CASES: Array<[string, EndpointARN]> = [
+    [
+      "arn:aws:s3:us-west-2:123456789012:accesspoint:myendpoint",
+      {
+        partition: "aws",
+        service: "s3",
+        region: "us-west-2",
+        accountId: "123456789012",
+        resourceId: ["accesspoint", "myendpoint"],
+      },
+    ],
+    [
+      "arn:aws:s3:us-west-2:123456789012:accesspoint/myendpoint",
+      {
+        partition: "aws",
+        service: "s3",
+        region: "us-west-2",
+        accountId: "123456789012",
+        resourceId: ["accesspoint", "myendpoint"],
+      },
+    ],
+    [
+      "arn:aws:s3:us-east-1:123456789012:accesspoint:myendpoint",
+      {
+        partition: "aws",
+        service: "s3",
+        region: "us-east-1",
+        accountId: "123456789012",
+        resourceId: ["accesspoint", "myendpoint"],
+      },
+    ],
+    [
+      "arn:aws-cn:s3:cn-north-1:123456789012:accesspoint:myendpoint",
+      {
+        partition: "aws-cn",
+        service: "s3",
+        region: "cn-north-1",
+        accountId: "123456789012",
+        resourceId: ["accesspoint", "myendpoint"],
+      },
+    ],
+    [
+      "arn:aws:sns:us-west-2:123456789012:myTopic",
+      {
+        partition: "aws",
+        service: "sns",
+        region: "us-west-2",
+        accountId: "123456789012",
+        resourceId: ["myTopic"],
+      },
+    ],
+    [
+      "arn:aws:sns:::myTopic",
+      {
+        partition: "aws",
+        service: "sns",
+        region: "",
+        accountId: "",
+        resourceId: ["myTopic"],
+      },
+    ],
+  ];
+
+  it.each(VALID_TEST_CASES)("returns for valid arn %s", (input: string, outout: EndpointARN) => {
+    expect(parseArn(input)).toEqual(outout);
+  });
+
+  it.each(["some:random:string:separated:by:colons", "arn:aws:too:short"])(
+    "returns null for invalid arn %s",
+    (input: string) => {
+      expect(parseArn(input)).toBeNull();
+    }
+  );
+});

packages/util-endpoints/src/lib/aws/parseArn.ts

@@ -0,0 +1,30 @@
+import { EndpointARN } from "@aws-sdk/types";
+
+/**
+ * Evaluates a single string argument value, and returns an object containing
+ * details about the parsed ARN.
+ * If the input was not a valid ARN, the function returns null.
+ */
+export const parseArn = (value: string): EndpointARN | null => {
+  const segments = value.split(":");
+
+  if (segments.length < 6 || segments[0] !== "arn") return null;
+
+  const [
+    ,
+    //Skip "arn" literal
+    partition,
+    service,
+    region,
+    accountId,
+    ...resourceId
+  ] = segments;
+
+  return {
+    partition,
+    service,
+    region,
+    accountId,
+    resourceId: resourceId[0].includes("/") ? resourceId[0].split("/") : resourceId,
+  };
+};

packages/util-endpoints/src/lib/aws/partition.spec.ts

@@ -0,0 +1,92 @@
+import { partitions } from "./partitions.json";
+
+const MOCK_DEFAULT_PARTITION = {
+  id: "aws",
+  regionRegex: "mockDefaultRegionRegex",
+  regions: {
+    "mock-region-1": {
+      dnsSuffix: "mockRegion1DnsSuffix",
+      dualStackDnsSuffix: "mockRegion1DualStackDnsSuffix",
+    },
+    "mock-region-2": {},
+  },
+  outputs: {
+    dnsSuffix: "mockDefaultDnsSuffix",
+    dualStackDnsSuffix: "mockDefaultDualStackDnsSuffix",
+    supportsFIPS: false,
+    supportsDualStack: false,
+  },
+};
+
+const MOCK_PARTITION = {
+  id: "partitionId",
+  regionRegex: "mockRegionRegex",
+  regions: {},
+  outputs: {
+    dnsSuffix: "mockPartitionDnsSuffix",
+    dualStackDnsSuffix: "mockPartitionDualStackDnsSuffix",
+    supportsFIPS: true,
+    supportsDualStack: true,
+  },
+};
+
+describe("partition", () => {
+  describe("should reuturn data when default partition exists", () => {
+    jest.isolateModules(() => {
+      jest.mock("./partitions.json", () => ({
+        partitions: [MOCK_DEFAULT_PARTITION, MOCK_PARTITION],
+      }));
+      const { partition } = require("./partition");
+
+      describe("should return the data when region is found", () => {
+        it("returns region data if it exists", () => {
+          const regionWithRegionData = "mock-region-1";
+          expect(partition(regionWithRegionData)).toEqual({
+            name: MOCK_DEFAULT_PARTITION.id,
+            ...MOCK_DEFAULT_PARTITION.outputs,
+            ...MOCK_DEFAULT_PARTITION.regions[regionWithRegionData],
+          });
+        });
+
+        it("returns partition data if region data does not exist", () => {
+          const regionWithoutRegionData = "mock-region-2";
+          expect(partition(regionWithoutRegionData)).toEqual({
+            name: MOCK_DEFAULT_PARTITION.id,
+            ...MOCK_DEFAULT_PARTITION.outputs,
+          });
+        });
+      });
+
+      it("should return the partition data when region is matched with regionRegex", () => {
+        expect(partition(MOCK_DEFAULT_PARTITION.regionRegex)).toEqual({
+          name: MOCK_DEFAULT_PARTITION.id,
+          ...MOCK_DEFAULT_PARTITION.outputs,
+        });
+        expect(partition(MOCK_PARTITION.regionRegex)).toEqual({
+          name: MOCK_PARTITION.id,
+          ...MOCK_PARTITION.outputs,
+        });
+      });
+
+      it("should return the default partition when the region is not found", () => {
+        expect(partition("non-existant-region")).toEqual({
+          name: MOCK_DEFAULT_PARTITION.id,
+          ...MOCK_DEFAULT_PARTITION.outputs,
+        });
+      });
+    });
+  });
+
+  it("should throw an error when the default partition is not found, and region doesn't match in partition array or regex", () => {
+    jest.isolateModules(() => {
+      jest.mock("./partitions.json", () => ({
+        partitions: [MOCK_PARTITION],
+      }));
+      const { partition } = require("./partition");
+      expect(() => partition("non-existant-region")).toThrow(
+        "Provided region was not found in the partition array or regex," +
+          " and default partition with id 'aws' doesn't exist."
+      );
+    });
+  });
+});

packages/util-endpoints/src/lib/aws/partition.ts

@@ -0,0 +1,51 @@
+import { EndpointPartition } from "@aws-sdk/types";
+
+import { partitions } from "./partitions.json";
+
+const DEFAULT_PARTITION = partitions.find((partition) => partition.id === "aws");
+
+/**
+ * Evaluates a single string argument value as a region, and matches the
+ * string value to an AWS partition.
+ * The matcher MUST always return a successful object describing the partition
+ * that the region has been determined to be a part of.
+ */
+export const partition = (value: string): EndpointPartition => {
+  // Check for explicit region listed in the regions array.
+  for (const partition of partitions) {
+    const { id, regions, outputs } = partition;
+    for (const [region, regionData] of Object.entries(regions)) {
+      if (region === value) {
+        return {
+          name: id,
+          ...outputs,
+          ...regionData,
+        };
+      }
+    }
+  }
+
+  // Check for region that matches a regionRegex pattern.
+  for (const partition of partitions) {
+    const { id, regionRegex, outputs } = partition;
+    if (new RegExp(regionRegex).test(value)) {
+      return {
+        name: id,
+        ...outputs,
+      };
+    }
+  }
+
+  if (!DEFAULT_PARTITION) {
+    throw new Error(
+      "Provided region was not found in the partition array or regex," +
+        " and default partition with id 'aws' doesn't exist."
+    );
+  }
+
+  // Return the default partition.
+  return {
+    name: DEFAULT_PARTITION.id,
+    ...DEFAULT_PARTITION.outputs,
+  };
+};

packages/util-endpoints/src/lib/aws/partitions.json

@@ -0,0 +1,92 @@
+{
+  "version": "1.1",
+  "partitions": [
+    {
+      "id": "aws",
+      "regionRegex": "^(us|eu|ap|sa|ca|me|af)-\\w+-\\d+$",
+      "regions": {
+        "af-south-1": {},
+        "af-east-1": {},
+        "ap-northeast-1": {},
+        "ap-northeast-2": {},
+        "ap-northeast-3": {},
+        "ap-south-1": {},
+        "ap-southeast-1": {},
+        "ap-southeast-2": {},
+        "ap-southeast-3": {},
+        "ca-central-1": {},
+        "eu-central-1": {},
+        "eu-north-1": {},
+        "eu-south-1": {},
+        "eu-west-1": {},
+        "eu-west-2": {},
+        "eu-west-3": {},
+        "me-south-1": {},
+        "sa-east-1": {},
+        "us-east-1": {},
+        "us-east-2": {},
+        "us-west-1": {},
+        "us-west-2": {},
+        "aws-global": {}
+      },
+      "outputs": {
+        "dnsSuffix": "amazonaws.com",
+        "dualStackDnsSuffix": "api.aws",
+        "supportsFIPS": true,
+        "supportsDualStack": true
+      }
+    },
+    {
+      "id": "aws-us-gov",
+      "regionRegex": "^us\\-gov\\-\\w+\\-\\d+$",
+      "regions": {
+        "us-gov-west-1": {},
+        "us-gov-east-1": {},
+        "aws-us-gov-global": {}
+      },
+      "outputs": {
+        "dnsSuffix": "amazonaws.com",
+        "dualStackDnsSuffix": "api.aws",
+        "supportsFIPS": true,
+        "supportsDualStack": true
+      }
+    },
+    {
+      "id": "aws-cn",
+      "regionRegex": "^cn\\-\\w+\\-\\d+$",
+      "regions": {
+        "cn-north-1": {},
+        "cn-northwest-1": {},
+        "aws-cn-global": {}
+      },
+      "outputs": {
+        "dnsSuffix": "amazonaws.com.cn",
+        "dualStackDnsSuffix": "api.amazonwebservices.com.cn",
+        "supportsFIPS": true,
+        "supportsDualStack": true
+      }
+    },
+    {
+      "id": "aws-iso",
+      "regionRegex": "^us\\-iso\\-\\w+\\-\\d+$",
+      "outputs": {
+        "dnsSuffix": "c2s.ic.gov",
+        "supportsFIPS": true,
+        "supportsDualStack": false,
+        "dualStackDnsSuffix": "c2s.ic.gov"
+      },
+      "regions": {}
+    },
+    {
+      "id": "aws-iso-b",
+      "regionRegex": "^us\\-isob\\-\\w+\\-\\d+$",
+      "outputs": {
+        "dnsSuffix": "sc2s.sgov.gov",
+        "supportsFIPS": true,
+        "supportsDualStack": false,
+        "dualStackDnsSuffix": "sc2s.sgov.gov"
+      },
+      "regions": {}
+    }
+  ]
+}

packages/util-endpoints/src/lib/index.ts

@@ -1,3 +1,4 @@
+export * as aws from "./aws";
 export * from "./booleanEquals";
 export * from "./getAttr";
 export * from "./isSet";