chore(util-endpoints): add dynamic endpoint resolver (#3884)

* chore(util-endpoints): add endpoint resolver from experiments

* fix: imports in lib

* test: evaluateTemplate.spec.ts

* test: evaluateCondition.spec.ts

* test: evaluateConditions.spec.ts

* test: evaluateEndpointRule.spec.ts

* test: evaluateEndpointUrl.spec.ts

* test: evaluateErrorRule.spec.ts

* test: evaluateExpression.spec.ts

* test: evaluateRef.spec.ts

* test: evaluateTreeRule.spec.ts

* test: evaluateFn.spec.ts

* test: evaluateRules.spec.ts

* chore: rename evaluateEndpointUrl to getEndpointUrl

* chore: rename evaluateFn to callFunction

* chore: rename evaluteRef to getReferenceValue

* test: getEndpointHeaders.spec.ts

* test: getEndpointProperties.spec.ts

* test: getEndpointProperty.spec.ts

* test: resolveEndpoint.spec.ts

* chore: move EndpointV2 interface to types

Author: trivikr

packages/types/src/endpoint.ts

@@ -25,3 +25,15 @@ export interface EndpointURL {
    */
   isIp: boolean;
 }
+
+export type EndpointObjectProperty =
+  | string
+  | boolean
+  | { [key: string]: EndpointObjectProperty }
+  | EndpointObjectProperty[];
+
+export interface EndpointV2 {
+  url: URL;
+  properties?: Record<string, EndpointObjectProperty>;
+  headers?: Record<string, string[]>;
+}

packages/util-endpoints/src/index.ts

@@ -1 +1,2 @@
-export * from "./EndpointError";
+export * from "./resolveEndpoint";
+export * from "./types";

packages/util-endpoints/src/lib/getAttr.spec.ts

@@ -1,4 +1,4 @@
-import { EndpointError } from "../EndpointError";
+import { EndpointError } from "../types";
 import { getAttr } from "./getAttr";
 import { getAttrPathList } from "./getAttrPathList";
 

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

@@ -1,4 +1,4 @@
-import { EndpointError } from "../EndpointError";
+import { EndpointError } from "../types";
 import { getAttrPathList } from "./getAttrPathList";
 
 export type GetAttrValue = string | boolean | { [key: string]: GetAttrValue } | Array<GetAttrValue>;

packages/util-endpoints/src/lib/getAttrPathList.spec.ts

@@ -1,4 +1,4 @@
-import { EndpointError } from "..";
+import { EndpointError } from "../types";
 import { getAttrPathList } from "./getAttrPathList";
 
 describe(getAttrPathList.name, () => {

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

@@ -1,4 +1,4 @@
-import { EndpointError } from "../";
+import { EndpointError } from "../types";
 
 /**
  * Parses path as a getAttr expression, returning a list of strings.

packages/util-endpoints/src/resolveEndpoint.spec.ts

@@ -0,0 +1,86 @@
+import { resolveEndpoint } from "./resolveEndpoint";
+import { EndpointError, EndpointParams, ParameterObject, RuleSetObject } from "./types";
+import { evaluateRules } from "./utils";
+
+jest.mock("./utils");
+
+describe(resolveEndpoint.name, () => {
+  const boolParamKey = "boolParamKey";
+  const stringParamKey = "stringParamKey";
+  const requiredParamKey = "requiredParamKey";
+  const paramWithDefaultKey = "paramWithDefaultKey";
+
+  const mockEndpointParams: EndpointParams = {
+    [boolParamKey]: true,
+    [stringParamKey]: "stringParamValue",
+    [requiredParamKey]: "requiredParamValue",
+    [paramWithDefaultKey]: "defaultParamValue",
+  };
+
+  const mockRules = [];
+  const mockRuleSetParameters: Record<string, ParameterObject> = {
+    [boolParamKey]: {
+      type: "boolean",
+    },
+    [stringParamKey]: {
+      type: "string",
+    },
+    [requiredParamKey]: {
+      type: "string",
+      required: true,
+    },
+    [paramWithDefaultKey]: {
+      type: "string",
+      default: "paramWithDefaultValue",
+    },
+  };
+
+  const mockRuleSetObject: RuleSetObject = {
+    version: "1.0",
+    serviceId: "serviceId",
+    parameters: mockRuleSetParameters,
+    rules: mockRules,
+  };
+
+  const mockResolvedEndpoint = { url: new URL("http://example.com") };
+
+  beforeEach(() => {
+    (evaluateRules as jest.Mock).mockReturnValue(mockResolvedEndpoint);
+  });
+
+  afterEach(() => {
+    jest.resetAllMocks();
+  });
+
+  it("should throw an error if a required parameter is missing", () => {
+    const { requiredParamKey: ignored, ...endpointParamsWithoutRequired } = mockEndpointParams;
+    expect(() => resolveEndpoint(mockRuleSetObject, { endpointParams: endpointParamsWithoutRequired })).toThrow(
+      new EndpointError(`Missing required parameter: '${requiredParamKey}'`)
+    );
+    expect(evaluateRules).not.toHaveBeenCalled();
+  });
+
+  it("should use the default value if a parameter is not set", () => {
+    const { paramWithDefaultKey: ignored, ...endpointParamsWithoutDefault } = mockEndpointParams;
+
+    const resolvedEndpoint = resolveEndpoint(mockRuleSetObject, { endpointParams: endpointParamsWithoutDefault });
+    expect(resolvedEndpoint).toEqual(mockResolvedEndpoint);
+
+    expect(evaluateRules).toHaveBeenCalledWith(mockRules, {
+      endpointParams: {
+        ...mockEndpointParams,
+        [paramWithDefaultKey]: mockRuleSetParameters[paramWithDefaultKey].default,
+      },
+      referenceRecord: {},
+    });
+  });
+
+  it("should call evaluateRules", () => {
+    const resolvedEndpoint = resolveEndpoint(mockRuleSetObject, { endpointParams: mockEndpointParams });
+    expect(resolvedEndpoint).toEqual(mockResolvedEndpoint);
+    expect(evaluateRules).toHaveBeenCalledWith(mockRules, {
+      endpointParams: mockEndpointParams,
+      referenceRecord: {},
+    });
+  });
+});

packages/util-endpoints/src/resolveEndpoint.ts

@@ -0,0 +1,33 @@
+import { EndpointError, EndpointResolverOptions, RuleSetObject } from "./types";
+import { evaluateRules } from "./utils";
+
+/**
+ * Resolves an endpoint URL by processing the endpoints ruleset and options.
+ */
+export const resolveEndpoint = (ruleSetObject: RuleSetObject, options: EndpointResolverOptions) => {
+  const { endpointParams, logger } = options;
+  const { parameters, rules } = ruleSetObject;
+
+  const requiredParams = Object.entries(parameters)
+    .filter(([, v]) => v.required)
+    .map(([k]) => k);
+
+  for (const requiredParam of requiredParams) {
+    if (endpointParams[requiredParam] == null) {
+      throw new EndpointError(`Missing required parameter: '${requiredParam}'`);
+    }
+  }
+
+  // @ts-ignore Type 'undefined' is not assignable to type 'string | boolean' (2322)
+  const paramsWithDefault: [string, string | boolean][] = Object.entries(parameters)
+    .filter(([, v]) => v.default != null)
+    .map(([k, v]) => [k, v.default]);
+
+  if (paramsWithDefault.length > 0) {
+    for (const [paramKey, paramDefaultValue] of paramsWithDefault) {
+      endpointParams[paramKey] = endpointParams[paramKey] ?? paramDefaultValue;
+    }
+  }
+
+  return evaluateRules(rules, { endpointParams, logger, referenceRecord: {} });
+};

packages/util-endpoints/src/EndpointError.ts renamed to packages/util-endpoints/src/types/EndpointError.ts

@@ -0,0 +1,18 @@
+import { EndpointObjectProperty } from "@aws-sdk/types";
+
+import { ConditionObject, Expression } from "./shared";
+
+export type EndpointObjectProperties = Record<string, EndpointObjectProperty>;
+export type EndpointObjectHeaders = Record<string, Expression[]>;
+export type EndpointObject = {
+  url: Expression;
+  properties?: EndpointObjectProperties;
+  headers?: EndpointObjectHeaders;
+};
+
+export type EndpointRuleObject = {
+  type: "endpoint";
+  conditions?: ConditionObject[];
+  endpoint: EndpointObject;
+  documentation?: string;
+};

packages/util-endpoints/src/types/EndpointRuleObject.ts

@@ -0,0 +1,8 @@
+import { ConditionObject, Expression } from "./shared";
+
+export type ErrorRuleObject = {
+  type: "error";
+  conditions?: ConditionObject[];
+  error: Expression;
+  documentation?: string;
+};

packages/util-endpoints/src/types/ErrorRuleObject.ts

@@ -0,0 +1,21 @@
+import { RuleSetRules } from "./TreeRuleObject";
+
+export type DeprecatedObject = {
+  message?: string;
+  since?: string;
+};
+
+export type ParameterObject = {
+  type: "string" | "boolean";
+  default?: string | boolean;
+  required?: boolean;
+  documentation?: string;
+  deprecated?: DeprecatedObject;
+};
+
+export type RuleSetObject = {
+  version: string;
+  serviceId: string;
+  parameters: Record<string, ParameterObject>;
+  rules: RuleSetRules;
+};

packages/util-endpoints/src/types/RuleSetObject.ts

@@ -0,0 +1,12 @@
+import { EndpointRuleObject } from "./EndpointRuleObject";
+import { ErrorRuleObject } from "./ErrorRuleObject";
+import { ConditionObject } from "./shared";
+
+export type RuleSetRules = Array<EndpointRuleObject | ErrorRuleObject | TreeRuleObject>;
+
+export type TreeRuleObject = {
+  type: "tree";
+  conditions?: ConditionObject[];
+  rules: RuleSetRules;
+  documentation?: string;
+};

packages/util-endpoints/src/types/TreeRuleObject.ts

@@ -0,0 +1,6 @@
+export * from "./EndpointError";
+export * from "./EndpointRuleObject";
+export * from "./ErrorRuleObject";
+export * from "./RuleSetObject";
+export * from "./TreeRuleObject";
+export * from "./shared";

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

@@ -0,0 +1,22 @@
+import { Logger } from "@aws-sdk/types";
+
+export type ReferenceObject = { ref: string };
+
+export type FunctionObject = { fn: string; argv: FunctionArgv };
+export type FunctionArgv = Array<string | boolean | ReferenceObject | FunctionObject>;
+export type FunctionReturn = string | boolean | number | { [key: string]: FunctionReturn };
+
+export type ConditionObject = FunctionObject & { assign?: string };
+
+export type Expression = string | ReferenceObject | FunctionObject;
+
+export type EndpointParams = Record<string, string | boolean>;
+export type EndpointResolverOptions = {
+  endpointParams: EndpointParams;
+  logger?: Logger;
+};
+
+export type ReferenceRecord = Record<string, FunctionReturn>;
+export type EvaluateOptions = EndpointResolverOptions & {
+  referenceRecord: ReferenceRecord;
+};

packages/util-endpoints/src/types/shared.ts

@@ -0,0 +1,46 @@
+import * as lib from "../lib";
+import { callFunction } from "./callFunction";
+import { evaluateExpression } from "./evaluateExpression";
+
+jest.mock("./evaluateExpression");
+
+describe(callFunction.name, () => {
+  const mockOptions = {
+    endpointParams: {},
+    referenceRecord: {},
+  };
+  const mockFunctionName = "mockFunctionName";
+  const mockReturn = "mockReturn";
+
+  beforeEach(() => {
+    lib[mockFunctionName] = jest.fn().mockReturnValue(mockReturn);
+  });
+
+  afterEach(() => {
+    jest.clearAllMocks();
+  });
+
+  it("skips evaluateExpression for boolean arg", () => {
+    const mockBooleanArg = true;
+    const mockFn = { fn: mockFunctionName, argv: [mockBooleanArg] };
+    const result = callFunction(mockFn, mockOptions);
+    expect(result).toBe(mockReturn);
+    expect(evaluateExpression).not.toHaveBeenCalled();
+    expect(lib[mockFunctionName]).toHaveBeenCalledWith(mockBooleanArg);
+  });
+
+  it.each(["string", { ref: "ref" }, { fn: "fn", argv: [] }])(
+    "calls evaluateExpression for non-boolean arg: %s",
+    (arg) => {
+      const mockArgReturn = "mockArgReturn";
+      const mockFn = { fn: mockFunctionName, argv: [arg] };
+
+      (evaluateExpression as jest.Mock).mockReturnValue(mockArgReturn);
+
+      const result = callFunction(mockFn, mockOptions);
+      expect(result).toBe(mockReturn);
+      expect(evaluateExpression).toHaveBeenCalledWith(arg, "arg", mockOptions);
+      expect(lib[mockFunctionName]).toHaveBeenCalledWith(mockArgReturn);
+    }
+  );
+});

packages/util-endpoints/src/utils/callFunction.spec.ts

@@ -0,0 +1,9 @@
+import * as lib from "../lib";
+import { EvaluateOptions, FunctionObject, FunctionReturn } from "../types";
+import { evaluateExpression } from "./evaluateExpression";
+
+export const callFunction = ({ fn, argv }: FunctionObject, options: EvaluateOptions): FunctionReturn => {
+  const argvArray = argv.map((arg) => (typeof arg === "boolean" ? arg : evaluateExpression(arg, "arg", options)));
+  // @ts-ignore Element implicitly has an 'any' type
+  return lib[fn](...argvArray);
+};

packages/util-endpoints/src/utils/callFunction.ts

@@ -0,0 +1,49 @@
+import { EndpointError, EvaluateOptions } from "../types";
+import { callFunction } from "./callFunction";
+import { evaluateCondition } from "./evaluateCondition";
+
+jest.mock("./callFunction");
+
+describe(evaluateCondition.name, () => {
+  const mockOptions: EvaluateOptions = {
+    endpointParams: {},
+    referenceRecord: {},
+  };
+  const mockAssign = "mockAssign";
+  const mockFnArgs = { fn: "fn", argv: ["arg"] };
+
+  it("throws error if assign is already defined in Reference Record", () => {
+    const mockOptionsWithAssign = {
+      ...mockOptions,
+      referenceRecord: {
+        [mockAssign]: true,
+      },
+    };
+    expect(() => evaluateCondition({ assign: mockAssign, ...mockFnArgs }, mockOptionsWithAssign)).toThrow(
+      new EndpointError(`'${mockAssign}' is already defined in Reference Record.`)
+    );
+    expect(callFunction).not.toHaveBeenCalled();
+  });
+
+  describe("evaluates function", () => {
+    describe.each([
+      [true, "truthy", [true, 1, -1, "true", "false"]],
+      [false, "falsy", [false, 0, -0, "", null, undefined, NaN]],
+    ])("returns %s for %s values", (result, boolStatus, testCases) => {
+      it.each(testCases)(`${boolStatus} value: '%s'`, (mockReturn) => {
+        (callFunction as jest.Mock).mockReturnValue(mockReturn);
+        const { result, toAssign } = evaluateCondition(mockFnArgs, mockOptions);
+        expect(result).toBe(result);
+        expect(toAssign).toBeUndefined();
+      });
+    });
+  });
+
+  it("returns assigned value if defined", () => {
+    const mockAssignedValue = "mockAssignedValue";
+    (callFunction as jest.Mock).mockReturnValue(mockAssignedValue);
+    const { result, toAssign } = evaluateCondition({ assign: mockAssign, ...mockFnArgs }, mockOptions);
+    expect(result).toBe(true);
+    expect(toAssign).toEqual({ name: mockAssign, value: mockAssignedValue });
+  });
+});

packages/util-endpoints/src/utils/evaluateCondition.spec.ts

@@ -0,0 +1,13 @@
+import { ConditionObject, EndpointError, EvaluateOptions } from "../types";
+import { callFunction } from "./callFunction";
+
+export const evaluateCondition = ({ assign, ...fnArgs }: ConditionObject, options: EvaluateOptions) => {
+  if (assign && options.referenceRecord[assign]) {
+    throw new EndpointError(`'${assign}' is already defined in Reference Record.`);
+  }
+  const value = callFunction(fnArgs, options);
+  return {
+    result: !!value,
+    ...(assign != null && { toAssign: { name: assign, value } }),
+  };
+};