[core-client] New option for adding policies (Azure#19920)

Rather than needing to expose the Pipeline directly, clients can pass a static array of policies to be added.

After discussion with other architects, these additional policies are limited to specifying one of two positions to participate in the pipeline.

Author: xirzec

sdk/core/core-client/CHANGELOG.md

@@ -1,9 +1,11 @@
 # Release History
 
-## 1.4.1 (Unreleased)
+## 1.5.0 (Unreleased)
 
 ### Features Added
 
+- Added new `CommonClientOptions` member `additionalPolicies` to allow passing custom pipeline policies to client constructors. [PR #19920](https://github.com/Azure/azure-sdk-for-js/pull/19920)
+
 ### Breaking Changes
 
 ### Bugs Fixed

sdk/core/core-client/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@azure/core-client",
-  "version": "1.4.1",
+  "version": "1.5.0",
   "description": "Core library for interfacing with AutoRest generated code",
   "sdk-type": "client",
   "main": "dist/index.js",

sdk/core/core-client/review/core-client.api.md

@@ -18,6 +18,12 @@ import { PipelineResponse } from '@azure/core-rest-pipeline';
 import { TokenCredential } from '@azure/core-auth';
 import { TransferProgressEvent } from '@azure/core-rest-pipeline';
 
+// @public
+export interface AdditionalPolicyConfig {
+    policy: PipelinePolicy;
+    position: "perCall" | "perRetry";
+}
+
 // @public
 export function authorizeRequestOnClaimChallenge(onChallengeOptions: AuthorizeRequestOnChallengeOptions): Promise<boolean>;
 
@@ -41,6 +47,7 @@ export interface BaseMapper {
 
 // @public
 export interface CommonClientOptions extends PipelineOptions {
+    additionalPolicies?: AdditionalPolicyConfig[];
     allowInsecureConnection?: boolean;
     httpClient?: HttpClient;
 }

sdk/core/core-client/src/index.ts

@@ -40,6 +40,7 @@ export {
   SerializerOptions,
   RawResponseCallback,
   CommonClientOptions,
+  AdditionalPolicyConfig,
 } from "./interfaces";
 export {
   deserializationPolicy,

sdk/core/core-client/src/interfaces.ts

@@ -5,6 +5,7 @@ import {
   HttpClient,
   HttpMethods,
   PipelineOptions,
+  PipelinePolicy,
   PipelineRequest,
   PipelineResponse,
   TransferProgressEvent,
@@ -724,6 +725,23 @@ export interface SpanConfig {
   namespace: string;
 }
 
+/**
+ * Used to configure additional policies added to the pipeline at construction.
+ */
+export interface AdditionalPolicyConfig {
+  /**
+   * A policy to be added.
+   */
+  policy: PipelinePolicy;
+  /**
+   * Determines if this policy be applied before or after retry logic.
+   * Only use `perRetry` if you need to modify the request again
+   * each time the operation is retried due to retryable service
+   * issues.
+   */
+  position: "perCall" | "perRetry";
+}
+
 /**
  * The common set of options that high level clients are expected to expose.
  */
@@ -736,4 +754,8 @@ export interface CommonClientOptions extends PipelineOptions {
    * Set to true if the request is sent over HTTP instead of HTTPS
    */
   allowInsecureConnection?: boolean;
+  /**
+   * Additional policies to include in the HTTP pipeline.
+   */
+  additionalPolicies?: AdditionalPolicyConfig[];
 }

sdk/core/core-client/src/serviceClient.ts

@@ -93,6 +93,16 @@ export class ServiceClient {
     this._httpClient = options.httpClient || getCachedDefaultHttpClient();
 
     this.pipeline = options.pipeline || createDefaultPipeline(options);
+    if (options.additionalPolicies?.length) {
+      for (const { policy, position } of options.additionalPolicies) {
+        // Sign happens after Retry and is commonly needed to occur
+        // before policies that intercept post-retry.
+        const afterPhase = position === "perRetry" ? "Sign" : undefined;
+        this.pipeline.addPolicy(policy, {
+          afterPhase,
+        });
+      }
+    }
   }
 
   /**

sdk/core/core-client/test/serviceClient.spec.ts

@@ -19,8 +19,10 @@ import {
 } from "../src";
 import {
   HttpClient,
+  PipelinePolicy,
   PipelineRequest,
   RestError,
+  SendRequest,
   createEmptyPipeline,
   createHttpHeaders,
   createPipelineRequest,
@@ -1483,6 +1485,36 @@ describe("ServiceClient", function () {
     await client.sendOperationRequest<string>({ options: { top: 10 } as any }, operationSpec);
     assert.equal(request!.url, "https://example.com/path?$skip=10&$top=10");
   });
+
+  it("should insert policies in the correct pipeline position", async function () {
+    const pipeline = createEmptyPipeline();
+    const sendRequest = (request: PipelineRequest, next: SendRequest) => next(request);
+    const retryPolicy: PipelinePolicy = {
+      name: "retry",
+      sendRequest,
+    };
+    pipeline.addPolicy(retryPolicy, { phase: "Retry" });
+    const policy1: PipelinePolicy = {
+      name: "policy1",
+      sendRequest,
+    };
+    const policy2: PipelinePolicy = {
+      name: "policy2",
+      sendRequest,
+    };
+
+    const client = new ServiceClient({
+      pipeline,
+      additionalPolicies: [
+        { policy: policy1, position: "perRetry" },
+        { policy: policy2, position: "perCall" },
+      ],
+    });
+
+    assert(client);
+    const policies = pipeline.getOrderedPolicies();
+    assert.deepStrictEqual(policies, [policy2, retryPolicy, policy1]);
+  });
 });
 
 async function testSendOperationRequest(

sdk/core/core-rest-pipeline/src/constants.ts

@@ -1,4 +1,4 @@
 // Copyright (c) Microsoft Corporation.
 // Licensed under the MIT license.
 
-export const SDK_VERSION: string = "1.4.1";
+export const SDK_VERSION: string = "1.5.0";