[core] Add optional agent option to WebResourceLike (#32590)

and add plubming to pass it to core-rest-pipeline.

Also add agent and tlsSettings to PipelineRequestOptions.

sdk/core/core-http-compat/review/core-http-compat.api.md

@@ -17,6 +17,15 @@ import type { ProxySettings } from '@azure/core-rest-pipeline';
 import { ServiceClient } from '@azure/core-client';
 import type { ServiceClientOptions } from '@azure/core-client';
 
+// @public
+export interface Agent {
+    destroy(): void;
+    maxFreeSockets: number;
+    maxSockets: number;
+    requests: unknown;
+    sockets: unknown;
+}
+
 // @public
 export interface CompatResponse extends Omit<FullOperationResponse, "request" | "headers"> {
     headers: HttpHeadersLike;
@@ -134,6 +143,7 @@ export type TransferProgressEvent = {
 // @public
 export interface WebResourceLike {
     abortSignal?: AbortSignalLike;
+    agent?: Agent;
     body?: any;
     clone(): WebResourceLike;
     decompressResponse?: boolean;

sdk/core/core-http-compat/src/index.ts

@@ -26,6 +26,7 @@ export { RedirectOptions } from "./policies/redirectOptions.js";
 export { disableKeepAlivePolicyName } from "./policies/disableKeepAlivePolicy.js";
 export { convertHttpClient } from "./httpClientAdapter.js";
 export {
+  Agent,
   WebResourceLike,
   HttpHeadersLike,
   RawHttpHeaders,

sdk/core/core-http-compat/src/util.ts

@@ -47,6 +47,7 @@ export function toPipelineRequest(
       onUploadProgress: webResource.onUploadProgress,
       proxySettings: webResource.proxySettings,
       streamResponseStatusCodes: webResource.streamResponseStatusCodes,
+      agent: webResource.agent,
     });
     if (options.originalRequest) {
       (newRequest as PipelineRequestWithOriginal)[originalClientRequestSymbol] =
@@ -76,6 +77,7 @@ export function toWebResourceLike(
     onUploadProgress: request.onUploadProgress,
     proxySettings: request.proxySettings,
     streamResponseStatusCodes: request.streamResponseStatusCodes,
+    agent: request.agent,
     clone(): WebResourceLike {
       throw new Error("Cannot clone a non-proxied WebResourceLike");
     },
@@ -119,6 +121,7 @@ export function toWebResourceLike(
           "onUploadProgress",
           "proxySettings",
           "streamResponseStatusCodes",
+          "agent",
         ];
 
         if (typeof prop === "string" && passThroughProps.includes(prop)) {
@@ -361,6 +364,34 @@ export class HttpHeaders implements HttpHeadersLike {
   }
 }
 
+/**
+ * An interface compatible with NodeJS's `http.Agent`.
+ * We want to avoid publicly re-exporting the actual interface,
+ * since it might vary across runtime versions.
+ */
+export interface Agent {
+  /**
+   * Destroy any sockets that are currently in use by the agent.
+   */
+  destroy(): void;
+  /**
+   * For agents with keepAlive enabled, this sets the maximum number of sockets that will be left open in the free state.
+   */
+  maxFreeSockets: number;
+  /**
+   * Determines how many concurrent sockets the agent can have open per origin.
+   */
+  maxSockets: number;
+  /**
+   * An object which contains queues of requests that have not yet been assigned to sockets.
+   */
+  requests: unknown;
+  /**
+   * An object which contains arrays of sockets currently in use by the agent.
+   */
+  sockets: unknown;
+}
+
 /**
  * A description of a HTTP request to be made to a remote server.
  */
@@ -437,6 +468,16 @@ export interface WebResourceLike {
   /** Callback which fires upon download progress. */
   onDownloadProgress?: (progress: TransferProgressEvent) => void;
 
+  /**
+   * NODEJS ONLY
+   *
+   * A Node-only option to provide a custom `http.Agent`/`https.Agent`.
+   * NOTE: usually this should be one instance shared by multiple requests so that the underlying
+   *       connection to the service can be reused.
+   * Does nothing when running in the browser.
+   */
+  agent?: Agent;
+
   /**
    * Clone this request object.
    */

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

@@ -283,6 +283,7 @@ export interface PipelineRequest {
 // @public
 export interface PipelineRequestOptions {
     abortSignal?: AbortSignalLike;
+    agent?: Agent;
     allowInsecureConnection?: boolean;
     body?: RequestBodyType;
     disableKeepAlive?: boolean;
@@ -297,6 +298,7 @@ export interface PipelineRequestOptions {
     requestId?: string;
     streamResponseStatusCodes?: Set<number>;
     timeout?: number;
+    tlsSettings?: TlsSettings;
     tracingOptions?: OperationTracingOptions;
     url: string;
     withCredentials?: boolean;

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

@@ -2,12 +2,14 @@
 // Licensed under the MIT License.
 
 import type {
+  Agent,
   FormDataMap,
   HttpHeaders,
   MultipartRequestBody,
   PipelineRequest,
   ProxySettings,
   RequestBodyType,
+  TlsSettings,
   TransferProgressEvent,
 } from "./interfaces.js";
 import { createHttpHeaders } from "./httpHeaders.js";
@@ -74,6 +76,16 @@ export interface PipelineRequestOptions {
    */
   streamResponseStatusCodes?: Set<number>;
 
+  /**
+   * NODEJS ONLY
+   *
+   * A Node-only option to provide a custom `http.Agent`/`https.Agent`.
+   * NOTE: usually this should be one instance shared by multiple requests so that the underlying
+   *       connection to the service can be reused.
+   * Does nothing when running in the browser.
+   */
+  agent?: Agent;
+
   /**
    * BROWSER ONLY
    *
@@ -85,6 +97,9 @@ export interface PipelineRequestOptions {
    */
   enableBrowserStreams?: boolean;
 
+  /** Settings for configuring TLS authentication */
+  tlsSettings?: TlsSettings;
+
   /**
    * Proxy configuration.
    */
@@ -128,7 +143,6 @@ class PipelineRequestImpl implements PipelineRequest {
   public formData?: FormDataMap;
   public streamResponseStatusCodes?: Set<number>;
   public enableBrowserStreams: boolean;
-
   public proxySettings?: ProxySettings;
   public disableKeepAlive: boolean;
   public abortSignal?: AbortSignalLike;
@@ -137,6 +151,8 @@ class PipelineRequestImpl implements PipelineRequest {
   public allowInsecureConnection?: boolean;
   public onUploadProgress?: (progress: TransferProgressEvent) => void;
   public onDownloadProgress?: (progress: TransferProgressEvent) => void;
+  public agent?: Agent;
+  public tlsSettings?: TlsSettings;
 
   constructor(options: PipelineRequestOptions) {
     this.url = options.url;
@@ -157,6 +173,8 @@ class PipelineRequestImpl implements PipelineRequest {
     this.requestId = options.requestId || randomUUID();
     this.allowInsecureConnection = options.allowInsecureConnection ?? false;
     this.enableBrowserStreams = options.enableBrowserStreams ?? false;
+    this.agent = options.agent;
+    this.tlsSettings = options.tlsSettings;
   }
 }
 

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

@@ -1350,18 +1350,22 @@ index 1ac007a..66abe50 100644
    HttpClient,
    HttpHeaders,
 diff --git a/src/pipelineRequest.ts b/src/pipelineRequest.ts
-index 8d1648d..5f67f7d 100644
+index 5947165..5f67f7d 100644
 --- a/src/pipelineRequest.ts
 +++ b/src/pipelineRequest.ts
-@@ -4,6 +4,7 @@
+@@ -2,21 +2,18 @@
+ // Licensed under the MIT License.
+
  import type {
+-  Agent,
    FormDataMap,
    HttpHeaders,
 +  HttpMethods,
    MultipartRequestBody,
    PipelineRequest,
    ProxySettings,
-@@ -11,10 +12,8 @@ import type {
+   RequestBodyType,
+-  TlsSettings,
    TransferProgressEvent,
  } from "./interfaces.js";
  import { createHttpHeaders } from "./httpHeaders.js";
@@ -1374,7 +1378,34 @@ index 8d1648d..5f67f7d 100644
 
  /**
   * Settings to initialize a request.
-@@ -100,11 +99,6 @@ export interface PipelineRequestOptions {
+@@ -76,16 +73,6 @@ export interface PipelineRequestOptions {
+    */
+   streamResponseStatusCodes?: Set<number>;
+
+-  /**
+-   * NODEJS ONLY
+-   *
+-   * A Node-only option to provide a custom `http.Agent`/`https.Agent`.
+-   * NOTE: usually this should be one instance shared by multiple requests so that the underlying
+-   *       connection to the service can be reused.
+-   * Does nothing when running in the browser.
+-   */
+-  agent?: Agent;
+-
+   /**
+    * BROWSER ONLY
+    *
+@@ -97,9 +84,6 @@ export interface PipelineRequestOptions {
+    */
+   enableBrowserStreams?: boolean;
+
+-  /** Settings for configuring TLS authentication */
+-  tlsSettings?: TlsSettings;
+-
+   /**
+    * Proxy configuration.
+    */
+@@ -115,11 +99,6 @@ export interface PipelineRequestOptions {
     */
    abortSignal?: AbortSignalLike;
 
@@ -1386,22 +1417,39 @@ index 8d1648d..5f67f7d 100644
    /**
     * Callback which fires upon upload progress.
     */
-@@ -133,7 +127,6 @@ class PipelineRequestImpl implements PipelineRequest {
+@@ -143,16 +122,14 @@ class PipelineRequestImpl implements PipelineRequest {
+   public formData?: FormDataMap;
+   public streamResponseStatusCodes?: Set<number>;
+   public enableBrowserStreams: boolean;
++
+   public proxySettings?: ProxySettings;
    public disableKeepAlive: boolean;
    public abortSignal?: AbortSignalLike;
    public requestId: string;
 -  public tracingOptions?: OperationTracingOptions;
    public allowInsecureConnection?: boolean;
    public onUploadProgress?: (progress: TransferProgressEvent) => void;
    public onDownloadProgress?: (progress: TransferProgressEvent) => void;
-@@ -151,7 +144,6 @@ class PipelineRequestImpl implements PipelineRequest {
+-  public agent?: Agent;
+-  public tlsSettings?: TlsSettings;
+
+   constructor(options: PipelineRequestOptions) {
+     this.url = options.url;
+@@ -167,14 +144,11 @@ class PipelineRequestImpl implements PipelineRequest {
      this.streamResponseStatusCodes = options.streamResponseStatusCodes;
      this.withCredentials = options.withCredentials ?? false;
      this.abortSignal = options.abortSignal;
 -    this.tracingOptions = options.tracingOptions;
      this.onUploadProgress = options.onUploadProgress;
      this.onDownloadProgress = options.onDownloadProgress;
      this.requestId = options.requestId || randomUUID();
+     this.allowInsecureConnection = options.allowInsecureConnection ?? false;
+     this.enableBrowserStreams = options.enableBrowserStreams ?? false;
+-    this.agent = options.agent;
+-    this.tlsSettings = options.tlsSettings;
+   }
+ }
+
 diff --git a/src/policies/auxiliaryAuthenticationHeaderPolicy.ts b/src/policies/auxiliaryAuthenticationHeaderPolicy.ts
 deleted file mode 100644
 index 55110a0..0000000