feat: allow feature identification on the smithy context

.changeset/sharp-horses-fry.md

@@ -0,0 +1,6 @@
+---
+"@smithy/types": minor
+"@smithy/core": minor
+---
+
+add feature identification map to smithy context

packages/core/src/setFeature.spec.ts

@@ -0,0 +1,10 @@
+import { HandlerExecutionContext } from "@smithy/types";
+
+import { setFeature } from "./setFeature";
+
+describe(setFeature.name, () => {
+  it("creates the context object path if needed", () => {
+    const context: HandlerExecutionContext = {};
+    setFeature(context, "RETRY_MODE_STANDARD", "E");
+  });
+});

packages/core/src/setFeature.ts

@@ -0,0 +1,26 @@
+import type { HandlerExecutionContext, SmithyFeatures } from "@smithy/types";
+
+/**
+ * @internal
+ * Indicates to the request context that a given feature is active.
+ *
+ * @param context - handler execution context.
+ * @param feature - readable name of feature.
+ * @param value - encoding value of feature. This is required because the
+ * specification asks the library not to include a runtime lookup of all
+ * the feature identifiers.
+ */
+export function setFeature<F extends keyof SmithyFeatures>(
+  context: HandlerExecutionContext,
+  feature: F,
+  value: SmithyFeatures[F]
+) {
+  if (!context.__smithy_context) {
+    context.__smithy_context = {
+      features: {},
+    };
+  } else if (!context.__smithy_context.features) {
+    context.__smithy_context.features = {};
+  }
+  context.__smithy_context.features![feature] = value;
+}

packages/types/src/feature-ids.ts

@@ -0,0 +1,18 @@
+/**
+ * @internal
+ */
+export type SmithyFeatures = Partial<{
+  RESOURCE_MODEL: "A";
+  WAITER: "B";
+  PAGINATOR: "C";
+  RETRY_MODE_LEGACY: "D";
+  RETRY_MODE_STANDARD: "E";
+  RETRY_MODE_ADAPTIVE: "F";
+  GZIP_REQUEST_COMPRESSION: "L";
+  PROTOCOL_RPC_V2_CBOR: "M";
+  ENDPOINT_OVERRIDE: "N";
+  SIGV4A_SIGNING: "S";
+  CREDENTIALS_CODE: "e";
+  CREDENTIALS_HTTP: "z";
+  CREDENTIALS_IMDS: "0";
+}>;

packages/types/src/index.ts

@@ -11,6 +11,7 @@ export * from "./endpoint";
 export * from "./endpoints";
 export * from "./eventStream";
 export * from "./extensions";
+export * from "./feature-ids";
 export * from "./http";
 export * from "./http/httpHandlerInitialization";
 export * from "./identity";

packages/types/src/middleware.ts

@@ -1,7 +1,10 @@
-import { AuthScheme, HttpAuthDefinition } from "./auth/auth";
-import { EndpointV2 } from "./endpoint";
-import { Logger } from "./logger";
-import { UserAgent } from "./util";
+import type { AuthScheme, HttpAuthDefinition } from "./auth/auth";
+import type { SelectedHttpAuthScheme } from "./auth/HttpAuthScheme";
+import type { Command } from "./command";
+import type { EndpointV2 } from "./endpoint";
+import type { SmithyFeatures } from "./feature-ids";
+import type { Logger } from "./logger";
+import type { UserAgent } from "./util";
 
 /**
  * @public
@@ -554,6 +557,7 @@ export interface HandlerExecutionContext {
   currentAuthConfig?: HttpAuthDefinition;
 
   /**
+   * @deprecated do not extend this field, it is a carryover from AWS SDKs.
    * Used by DynamoDbDocumentClient.
    */
   dynamoDbDocumentClientOptions?: Partial<{
@@ -563,10 +567,30 @@ export interface HandlerExecutionContext {
 
   /**
    * @internal
-   * Context for Smithy properties
+   * Context for Smithy properties.
+   */
+  [SMITHY_CONTEXT_KEY]?: {
+    service?: string;
+    operation?: string;
+    commandInstance?: Command<any, any, any, any, any>;
+    selectedHttpAuthScheme?: SelectedHttpAuthScheme;
+    features?: SmithyFeatures;
+    /**
+     * @deprecated
+     * Do not assign arbitrary members to the Smithy Context,
+     * fields should be explicitly declared here to avoid collisions.
+     */
+    [key: string]: unknown;
+  };
+
+  /**
+   * @deprecated
+   * Do not assign arbitrary members to the context, since
+   * they can interfere with existing functionality.
+   *
+   * Additional members should instead be declared on the SMITHY_CONTEXT_KEY
+   * or other reserved keys.
    */
-  [SMITHY_CONTEXT_KEY]?: Record<string, unknown>;
-
   [key: string]: any;
 }