[core] add agent to PipelineOptions

sdk/core/core-http-compat/CHANGELOG.md

@@ -1,14 +1,10 @@
 # Release History
 
-## 2.1.3 (Unreleased)
+## 2.2.0 (2025-02-06)
 
 ### Features Added
 
-### Breaking Changes
-
-### Bugs Fixed
-
-### Other Changes
+- Add optional `agent` option to `WebResourceLike` [PR #32590](https://github.com/Azure/azure-sdk-for-js/pull/32590)
 
 ## 2.1.2 (2024-04-09)
 

sdk/core/core-http-compat/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@azure/core-http-compat",
-  "version": "2.1.3",
+  "version": "2.2.0",
   "description": "Core HTTP Compatibility Library to bridge the gap between Core V1 & V2 packages.",
   "sdk-type": "client",
   "type": "module",
@@ -77,7 +77,7 @@
   "dependencies": {
     "@azure/abort-controller": "^2.0.0",
     "@azure/core-client": "^1.3.0",
-    "@azure/core-rest-pipeline": "^1.3.0"
+    "@azure/core-rest-pipeline": "^1.19.0"
   },
   "devDependencies": {
     "@azure-tools/test-utils": "^1.0.1",

sdk/core/core-rest-pipeline/CHANGELOG.md

@@ -1,14 +1,11 @@
 # Release History
 
-## 1.18.3 (Unreleased)
+## 1.19.0 (2025-02-06)
 
 ### Features Added
 
-### Breaking Changes
-
-### Bugs Fixed
-
-### Other Changes
+- Add `agent` and `tlsSettings` to `PipelineRequestOptions` [PR #32590](https://github.com/Azure/azure-sdk-for-js/pull/32590)
+- Add `agent` option to `PipelineOptions` [PR #32809](https://github.com/Azure/azure-sdk-for-js/pull/32809)
 
 ## 1.18.2 (2025-01-10)
 

sdk/core/core-rest-pipeline/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@azure/core-rest-pipeline",
-  "version": "1.18.3",
+  "version": "1.19.0",
   "description": "Isomorphic client library for making HTTP requests in node.js and browser.",
   "sdk-type": "client",
   "type": "module",

sdk/core/core-rest-pipeline/review/core-rest-pipeline.api.md

@@ -30,6 +30,12 @@ export interface Agent {
     sockets: unknown;
 }
 
+// @public
+export function agentPolicy(agent?: Agent): PipelinePolicy;
+
+// @public
+export const agentPolicyName = "agentPolicy";
+
 // @public
 export interface AuthorizeRequestOnChallengeOptions {
     getAccessToken: (scopes: string[], options: GetTokenOptions) => Promise<AccessToken | null>;
@@ -239,6 +245,7 @@ export interface Pipeline {
 
 // @public
 export interface PipelineOptions {
+    agent?: Agent;
     proxyOptions?: ProxySettings;
     redirectOptions?: RedirectPolicyOptions;
     retryOptions?: PipelineRetryOptions;

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

@@ -1,6 +1,6 @@
 // Copyright (c) Microsoft Corporation.
 // Licensed under the MIT License.
 
-export const SDK_VERSION: string = "1.18.3";
+export const SDK_VERSION: string = "1.19.0";
 
 export const DEFAULT_RETRY_POLICY_COUNT = 3;

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

@@ -3,7 +3,7 @@
 
 import { type LogPolicyOptions, logPolicy } from "./policies/logPolicy.js";
 import { type Pipeline, createEmptyPipeline } from "./pipeline.js";
-import type { PipelineRetryOptions, TlsSettings, ProxySettings } from "./interfaces.js";
+import type { Agent, PipelineRetryOptions, ProxySettings, TlsSettings } from "./interfaces.js";
 import { type RedirectPolicyOptions, redirectPolicy } from "./policies/redirectPolicy.js";
 import { type UserAgentPolicyOptions, userAgentPolicy } from "./policies/userAgentPolicy.js";
 import { multipartPolicy, multipartPolicyName } from "./policies/multipartPolicy.js";
@@ -13,6 +13,7 @@ import { formDataPolicy } from "./policies/formDataPolicy.js";
 import { isNodeLike } from "@azure/core-util";
 import { proxyPolicy } from "./policies/proxyPolicy.js";
 import { setClientRequestIdPolicy } from "./policies/setClientRequestIdPolicy.js";
+import { agentPolicy } from "./policies/agentPolicy.js";
 import { tlsPolicy } from "./policies/tlsPolicy.js";
 import { tracingPolicy } from "./policies/tracingPolicy.js";
 
@@ -31,6 +32,9 @@ export interface PipelineOptions {
    */
   proxyOptions?: ProxySettings;
 
+  /** Options for configuring Agent instance for outgoing requests */
+  agent?: Agent;
+
   /** Options for configuring TLS authentication */
   tlsOptions?: TlsSettings;
 
@@ -79,6 +83,9 @@ export function createPipelineFromOptions(options: InternalPipelineOptions): Pip
   const pipeline = createEmptyPipeline();
 
   if (isNodeLike) {
+    if (options.agent) {
+      pipeline.addPolicy(agentPolicy(options.agent));
+    }
     if (options.tlsOptions) {
       pipeline.addPolicy(tlsPolicy(options.tlsOptions));
     }

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

@@ -115,6 +115,7 @@ export {
   type AuxiliaryAuthenticationHeaderPolicyOptions,
   auxiliaryAuthenticationHeaderPolicyName,
 } from "./policies/auxiliaryAuthenticationHeaderPolicy.js";
+export { agentPolicy, agentPolicyName } from "./policies/agentPolicy.js";
 export {
   createFile,
   createFileFromStream,

sdk/core/core-rest-pipeline/src/policies/agentPolicy.ts

@@ -0,0 +1,26 @@
+// Copyright (c) Microsoft Corporation.
+// Licensed under the MIT License.
+
+import type { PipelinePolicy } from "../pipeline.js";
+import type { Agent } from "../interfaces.js";
+
+/**
+ * Name of the Agent Policy
+ */
+export const agentPolicyName = "agentPolicy";
+
+/**
+ * Gets a pipeline policy that sets http.agent
+ */
+export function agentPolicy(agent?: Agent): PipelinePolicy {
+  return {
+    name: agentPolicyName,
+    sendRequest: async (req, next) => {
+      // Users may define an agent on the request, honor it over the client level one
+      if (!req.agent) {
+        req.agent = agent;
+      }
+      return next(req);
+    },
+  };
+}

sdk/core/core-rest-pipeline/test/agentPolicy.spec.ts

@@ -0,0 +1,93 @@
+// Copyright (c) Microsoft Corporation.
+// Licensed under the MIT License.
+
+import { describe, it, assert, vi } from "vitest";
+import {
+  type PipelineResponse,
+  type SendRequest,
+  createHttpHeaders,
+  createPipelineRequest,
+  agentPolicy,
+  Agent,
+} from "../src/index.js";
+
+describe("agentPolicy", function () {
+  it("should set custom agent", async () => {
+    const request = createPipelineRequest({
+      url: "https://bing.com",
+    });
+    const customAgent: Agent = {
+      destroy: () => {},
+      maxFreeSockets: 1,
+      maxSockets: 1,
+      requests: 1,
+      sockets: {},
+    };
+    const policy = agentPolicy(customAgent);
+    const successResponse: PipelineResponse = {
+      headers: createHttpHeaders(),
+      request,
+      status: 200,
+    };
+    const next = vi.fn<SendRequest>();
+    next.mockResolvedValueOnce(successResponse);
+    assert.isUndefined(request.agent);
+
+    await policy.sendRequest(request, next);
+
+    assert.equal(request.agent, customAgent);
+  });
+
+  it("should not set agent when it is not passed in", async () => {
+    const request = createPipelineRequest({
+      url: "https://bing.com",
+    });
+    const policy = agentPolicy();
+    const successResponse: PipelineResponse = {
+      headers: createHttpHeaders(),
+      request,
+      status: 200,
+    };
+    const next = vi.fn<SendRequest>();
+    next.mockResolvedValueOnce(successResponse);
+    assert.isUndefined(request.agent);
+
+    await policy.sendRequest(request, next);
+
+    assert.isUndefined(request.agent);
+  });
+
+  it("should prefer request.agent", async () => {
+    const customAgent1: Agent = {
+      destroy: () => {},
+      maxFreeSockets: 1,
+      maxSockets: 1,
+      requests: 1,
+      sockets: {},
+    };
+    const request = createPipelineRequest({
+      url: "https://bing.com",
+    });
+    request.agent = customAgent1;
+    const customAgent2: Agent = {
+      destroy: () => {},
+      maxFreeSockets: 2,
+      maxSockets: 2,
+      requests: 2,
+      sockets: {},
+    };
+    const policy = agentPolicy(customAgent2);
+    const successResponse: PipelineResponse = {
+      headers: createHttpHeaders(),
+      request,
+      status: 200,
+    };
+    const next = vi.fn<SendRequest>();
+    next.mockResolvedValueOnce(successResponse);
+    assert.equal(request.agent, customAgent1);
+
+    await policy.sendRequest(request, next);
+
+    assert.equal(request.agent, customAgent1);
+  });
+});

sdk/core/ts-http-runtime/review/azure-core-comparison.diff

@@ -849,27 +849,23 @@ index 4ee4778..dc3b0f5 100644
      onUploadProgress: options.onUploadProgress,
      onDownloadProgress: options.onDownloadProgress,
 diff --git a/src/constants.ts b/src/constants.ts
-index 61ee1c1..e81a30d 100644
+index fdbfe9f..e81a30d 100644
 --- a/src/constants.ts
 +++ b/src/constants.ts
 @@ -1,6 +1,6 @@
  // Copyright (c) Microsoft Corporation.
  // Licensed under the MIT License.
 
--export const SDK_VERSION: string = "1.18.3";
+-export const SDK_VERSION: string = "1.19.0";
 +export const SDK_VERSION: string = "0.1.0";
 
  export const DEFAULT_RETRY_POLICY_COUNT = 3;
 diff --git a/src/createPipelineFromOptions.ts b/src/createPipelineFromOptions.ts
-index 2a2bd41..6066e07 100644
+index fefe550..fb56a78 100644
 --- a/src/createPipelineFromOptions.ts
 +++ b/src/createPipelineFromOptions.ts
-@@ -3,18 +3,16 @@
-
- import { type LogPolicyOptions, logPolicy } from "./policies/logPolicy.js";
- import { type Pipeline, createEmptyPipeline } from "./pipeline.js";
--import type { PipelineRetryOptions, TlsSettings, ProxySettings } from "./interfaces.js";
-+import type { PipelineRetryOptions, ProxySettings, TlsSettings } from "./interfaces.js";
+@@ -6,16 +6,14 @@ import { type Pipeline, createEmptyPipeline } from "./pipeline.js";
+ import type { Agent, PipelineRetryOptions, ProxySettings, TlsSettings } from "./interfaces.js";
  import { type RedirectPolicyOptions, redirectPolicy } from "./policies/redirectPolicy.js";
  import { type UserAgentPolicyOptions, userAgentPolicy } from "./policies/userAgentPolicy.js";
 -import { multipartPolicy, multipartPolicyName } from "./policies/multipartPolicy.js";
@@ -880,13 +876,14 @@ index 2a2bd41..6066e07 100644
 +import { isNodeLike } from "./util/checkEnvironment.js";
  import { proxyPolicy } from "./policies/proxyPolicy.js";
 -import { setClientRequestIdPolicy } from "./policies/setClientRequestIdPolicy.js";
+ import { agentPolicy } from "./policies/agentPolicy.js";
  import { tlsPolicy } from "./policies/tlsPolicy.js";
 -import { tracingPolicy } from "./policies/tracingPolicy.js";
 +import { multipartPolicy, multipartPolicyName } from "./policies/multipartPolicy.js";
 
  /**
   * Defines options that are used to configure the HTTP pipeline for
-@@ -88,15 +86,11 @@ export function createPipelineFromOptions(options: InternalPipelineOptions): Pip
+@@ -95,15 +93,11 @@ export function createPipelineFromOptions(options: InternalPipelineOptions): Pip
 
    pipeline.addPolicy(formDataPolicy(), { beforePolicies: [multipartPolicyName] });
    pipeline.addPolicy(userAgentPolicy(options.userAgentOptions));
@@ -916,10 +913,10 @@ index e9751e2..e4f8769 100644
    HttpClient,
    HttpHeaders as PipelineHeaders,
 diff --git a/src/index.ts b/src/index.ts
-index aa95065..65e7734 100644
+index 92a7ee9..65e7734 100644
 --- a/src/index.ts
 +++ b/src/index.ts
-@@ -9,115 +9,71 @@ declare global {
+@@ -9,116 +9,71 @@ declare global {
    interface TransformStream<I = any, O = any> {}
  }
 
@@ -1062,6 +1059,7 @@ index aa95065..65e7734 100644
 -  type AuxiliaryAuthenticationHeaderPolicyOptions,
 -  auxiliaryAuthenticationHeaderPolicyName,
 -} from "./policies/auxiliaryAuthenticationHeaderPolicy.js";
+-export { agentPolicy, agentPolicyName } from "./policies/agentPolicy.js";
 -export {
 -  createFile,
 -  createFileFromStream,

sdk/core/ts-http-runtime/review/ts-http-runtime.api.md

@@ -258,6 +258,7 @@ export interface Pipeline {
 
 // @public
 export interface PipelineOptions {
+    agent?: Agent;
     proxyOptions?: ProxySettings;
     redirectOptions?: RedirectPolicyOptions;
     retryOptions?: PipelineRetryOptions;

sdk/core/ts-http-runtime/src/createPipelineFromOptions.ts

@@ -3,14 +3,15 @@
 
 import { type LogPolicyOptions, logPolicy } from "./policies/logPolicy.js";
 import { type Pipeline, createEmptyPipeline } from "./pipeline.js";
-import type { PipelineRetryOptions, ProxySettings, TlsSettings } from "./interfaces.js";
+import type { Agent, PipelineRetryOptions, ProxySettings, TlsSettings } from "./interfaces.js";
 import { type RedirectPolicyOptions, redirectPolicy } from "./policies/redirectPolicy.js";
 import { type UserAgentPolicyOptions, userAgentPolicy } from "./policies/userAgentPolicy.js";
 import { decompressResponsePolicy } from "./policies/decompressResponsePolicy.js";
 import { defaultRetryPolicy } from "./policies/defaultRetryPolicy.js";
 import { formDataPolicy } from "./policies/formDataPolicy.js";
 import { isNodeLike } from "./util/checkEnvironment.js";
 import { proxyPolicy } from "./policies/proxyPolicy.js";
+import { agentPolicy } from "./policies/agentPolicy.js";
 import { tlsPolicy } from "./policies/tlsPolicy.js";
 import { multipartPolicy, multipartPolicyName } from "./policies/multipartPolicy.js";
 
@@ -29,6 +30,9 @@ export interface PipelineOptions {
    */
   proxyOptions?: ProxySettings;
 
+  /** Options for configuring Agent instance for outgoing requests */
+  agent?: Agent;
+
   /** Options for configuring TLS authentication */
   tlsOptions?: TlsSettings;
 
@@ -77,6 +81,9 @@ export function createPipelineFromOptions(options: InternalPipelineOptions): Pip
   const pipeline = createEmptyPipeline();
 
   if (isNodeLike) {
+    if (options.agent) {
+      pipeline.addPolicy(agentPolicy(options.agent));
+    }
     if (options.tlsOptions) {
       pipeline.addPolicy(tlsPolicy(options.tlsOptions));
     }

sdk/core/ts-http-runtime/src/policies/agentPolicy.ts

@@ -0,0 +1,26 @@
+// Copyright (c) Microsoft Corporation.
+// Licensed under the MIT License.
+
+import type { PipelinePolicy } from "../pipeline.js";
+import type { Agent } from "../interfaces.js";
+
+/**
+ * Name of the Agent Policy
+ */
+export const agentPolicyName = "agentPolicy";
+
+/**
+ * Gets a pipeline policy that sets http.agent
+ */
+export function agentPolicy(agent?: Agent): PipelinePolicy {
+  return {
+    name: agentPolicyName,
+    sendRequest: async (req, next) => {
+      // Users may define an agent on the request, honor it over the client level one
+      if (!req.agent) {
+        req.agent = agent;
+      }
+      return next(req);
+    },
+  };
+}