feat(endpoint): log endpoint decisions at debug level (#4106)

Author: kuhe

packages/util-endpoints/src/debug/debugId.ts

@@ -0,0 +1 @@
+export const debugId = "endpoints";

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

@@ -0,0 +1,2 @@
+export * from "./debugId";
+export * from "./toDebugString";

packages/util-endpoints/src/debug/toDebugString.ts

@@ -0,0 +1,26 @@
+import { EndpointParameters, EndpointV2 } from "@aws-sdk/types";
+
+import { GetAttrValue } from "../lib";
+import { EndpointObject, FunctionObject, FunctionReturn } from "../types";
+
+export function toDebugString(input: EndpointParameters): string;
+export function toDebugString(input: EndpointV2): string;
+export function toDebugString(input: GetAttrValue): string;
+export function toDebugString(input: FunctionObject): string;
+export function toDebugString(input: FunctionReturn): string;
+export function toDebugString(input: EndpointObject): string;
+export function toDebugString(input: any): string {
+  if (typeof input !== 'object' || input == null) {
+    return input;
+  }
+
+  if ('ref' in input) {
+    return `$${toDebugString(input.ref)}`
+  }
+
+  if ('fn' in input) {
+    return `${input.fn}(${(input.argv || []).map(toDebugString)})`;
+  }
+
+  return JSON.stringify(input, null, 2);
+}

packages/util-endpoints/src/resolveEndpoint.ts

@@ -1,5 +1,6 @@
 import { EndpointV2 } from "@aws-sdk/types";
 
+import { debugId, toDebugString } from "./debug";
 import { EndpointError, EndpointResolverOptions, RuleSetObject } from "./types";
 import { evaluateRules } from "./utils";
 
@@ -10,6 +11,8 @@ export const resolveEndpoint = (ruleSetObject: RuleSetObject, options: EndpointR
   const { endpointParams, logger } = options;
   const { parameters, rules } = ruleSetObject;
 
+  options.logger?.debug(debugId, `Initial EndpointParams: ${toDebugString(endpointParams)}`);
+
   // @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)
@@ -45,5 +48,7 @@ export const resolveEndpoint = (ruleSetObject: RuleSetObject, options: EndpointR
     }
   }
 
+  options.logger?.debug(debugId, `Resolved endpoint: ${toDebugString(endpoint)}`);
+
   return endpoint;
 };

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

@@ -1,3 +1,4 @@
+import { debugId, toDebugString } from "../debug";
 import { ConditionObject, EndpointError, EvaluateOptions } from "../types";
 import { callFunction } from "./callFunction";
 
@@ -6,6 +7,9 @@ export const evaluateCondition = ({ assign, ...fnArgs }: ConditionObject, option
     throw new EndpointError(`'${assign}' is already defined in Reference Record.`);
   }
   const value = callFunction(fnArgs, options);
+
+  options.logger?.debug(debugId, `evaluateCondition: ${toDebugString(fnArgs)} = ${toDebugString(value)}`);
+
   return {
     result: value === "" ? true : !!value,
     ...(assign != null && { toAssign: { name: assign, value } }),

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

@@ -1,3 +1,4 @@
+import { debugId, toDebugString } from "../debug";
 import { ConditionObject, EvaluateOptions, FunctionReturn } from "../types";
 import { evaluateCondition } from "./evaluateCondition";
 
@@ -19,6 +20,7 @@ export const evaluateConditions = (conditions: ConditionObject[] = [], options:
 
     if (toAssign) {
       conditionsReferenceRecord[toAssign.name] = toAssign.value;
+      options.logger?.debug(debugId, `assign: ${toAssign.name} := ${toDebugString(toAssign.value)}`);
     }
   }
 

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

@@ -1,5 +1,6 @@
 import { EndpointV2 } from "@aws-sdk/types";
 
+import { debugId, toDebugString } from "../debug";
 import { EndpointRuleObject, EvaluateOptions } from "../types";
 import { evaluateConditions } from "./evaluateConditions";
 import { getEndpointHeaders } from "./getEndpointHeaders";
@@ -23,6 +24,9 @@ export const evaluateEndpointRule = (
   };
 
   const { url, properties, headers } = endpoint;
+
+  options.logger?.debug(debugId, `Resolving endpoint from template: ${toDebugString(endpoint)}`);
+
   return {
     ...(headers != undefined && {
       headers: getEndpointHeaders(headers, endpointRuleOptions),