@typespec/ts-http-runtime 1.0.0-alpha.20231023.3

package/dist-esm/src/policies/systemErrorRetryPolicy.js

@@ -0,0 +1,27 @@
+// Copyright (c) Microsoft Corporation.
+// Licensed under the MIT license.
+import { exponentialRetryStrategy } from "../retryStrategies/exponentialRetryStrategy";
+import { retryPolicy } from "./retryPolicy";
+import { DEFAULT_RETRY_POLICY_COUNT } from "../constants";
+/**
+ * Name of the {@link systemErrorRetryPolicy}
+ */
+export const systemErrorRetryPolicyName = "systemErrorRetryPolicy";
+/**
+ * A retry policy that specifically seeks to handle errors in the
+ * underlying transport layer (e.g. DNS lookup failures) rather than
+ * retryable error codes from the server itself.
+ * @param options - Options that customize the policy.
+ */
+export function systemErrorRetryPolicy(options = {}) {
+    var _a;
+    return {
+        name: systemErrorRetryPolicyName,
+        sendRequest: retryPolicy([
+            exponentialRetryStrategy(Object.assign(Object.assign({}, options), { ignoreHttpStatusCodes: true })),
+        ], {
+            maxRetries: (_a = options.maxRetries) !== null && _a !== void 0 ? _a : DEFAULT_RETRY_POLICY_COUNT,
+        }).sendRequest,
+    };
+}
+//# sourceMappingURL=systemErrorRetryPolicy.js.map

package/dist-esm/src/policies/systemErrorRetryPolicy.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"systemErrorRetryPolicy.js","sourceRoot":"","sources":["../../../src/policies/systemErrorRetryPolicy.ts"],"names":[],"mappings":"AAAA,uCAAuC;AACvC,kCAAkC;AAGlC,OAAO,EAAE,wBAAwB,EAAE,MAAM,6CAA6C,CAAC;AACvF,OAAO,EAAE,WAAW,EAAE,MAAM,eAAe,CAAC;AAC5C,OAAO,EAAE,0BAA0B,EAAE,MAAM,cAAc,CAAC;AAE1D;;GAEG;AACH,MAAM,CAAC,MAAM,0BAA0B,GAAG,wBAAwB,CAAC;AAyBnE;;;;;GAKG;AACH,MAAM,UAAU,sBAAsB,CACpC,UAAyC,EAAE;;IAE3C,OAAO;QACL,IAAI,EAAE,0BAA0B;QAChC,WAAW,EAAE,WAAW,CACtB;YACE,wBAAwB,iCACnB,OAAO,KACV,qBAAqB,EAAE,IAAI,IAC3B;SACH,EACD;YACE,UAAU,EAAE,MAAA,OAAO,CAAC,UAAU,mCAAI,0BAA0B;SAC7D,CACF,CAAC,WAAW;KACd,CAAC;AACJ,CAAC","sourcesContent":["// Copyright (c) Microsoft Corporation.\n// Licensed under the MIT license.\n\nimport { PipelinePolicy } from \"../pipeline\";\nimport { exponentialRetryStrategy } from \"../retryStrategies/exponentialRetryStrategy\";\nimport { retryPolicy } from \"./retryPolicy\";\nimport { DEFAULT_RETRY_POLICY_COUNT } from \"../constants\";\n\n/**\n * Name of the {@link systemErrorRetryPolicy}\n */\nexport const systemErrorRetryPolicyName = \"systemErrorRetryPolicy\";\n\n/**\n * Options that control how to retry failed requests.\n */\nexport interface SystemErrorRetryPolicyOptions {\n  /**\n   * The maximum number of retry attempts. Defaults to 3.\n   */\n  maxRetries?: number;\n\n  /**\n   * The amount of delay in milliseconds between retry attempts. Defaults to 1000\n   * (1 second.) The delay increases exponentially with each retry up to a maximum\n   * specified by maxRetryDelayInMs.\n   */\n  retryDelayInMs?: number;\n\n  /**\n   * The maximum delay in milliseconds allowed before retrying an operation. Defaults\n   * to 64000 (64 seconds).\n   */\n  maxRetryDelayInMs?: number;\n}\n\n/**\n * A retry policy that specifically seeks to handle errors in the\n * underlying transport layer (e.g. DNS lookup failures) rather than\n * retryable error codes from the server itself.\n * @param options - Options that customize the policy.\n */\nexport function systemErrorRetryPolicy(\n  options: SystemErrorRetryPolicyOptions = {}\n): PipelinePolicy {\n  return {\n    name: systemErrorRetryPolicyName,\n    sendRequest: retryPolicy(\n      [\n        exponentialRetryStrategy({\n          ...options,\n          ignoreHttpStatusCodes: true,\n        }),\n      ],\n      {\n        maxRetries: options.maxRetries ?? DEFAULT_RETRY_POLICY_COUNT,\n      }\n    ).sendRequest,\n  };\n}\n"]}

package/dist-esm/src/policies/throttlingRetryPolicy.js

@@ -0,0 +1,29 @@
+// Copyright (c) Microsoft Corporation.
+// Licensed under the MIT license.
+import { throttlingRetryStrategy } from "../retryStrategies/throttlingRetryStrategy";
+import { retryPolicy } from "./retryPolicy";
+import { DEFAULT_RETRY_POLICY_COUNT } from "../constants";
+/**
+ * Name of the {@link throttlingRetryPolicy}
+ */
+export const throttlingRetryPolicyName = "throttlingRetryPolicy";
+/**
+ * A policy that retries when the server sends a 429 response with a Retry-After header.
+ *
+ * To learn more, please refer to
+ * https://docs.microsoft.com/en-us/azure/azure-resource-manager/resource-manager-request-limits,
+ * https://docs.microsoft.com/en-us/azure/azure-subscription-service-limits and
+ * https://docs.microsoft.com/en-us/azure/virtual-machines/troubleshooting/troubleshooting-throttling-errors
+ *
+ * @param options - Options that configure retry logic.
+ */
+export function throttlingRetryPolicy(options = {}) {
+    var _a;
+    return {
+        name: throttlingRetryPolicyName,
+        sendRequest: retryPolicy([throttlingRetryStrategy()], {
+            maxRetries: (_a = options.maxRetries) !== null && _a !== void 0 ? _a : DEFAULT_RETRY_POLICY_COUNT,
+        }).sendRequest,
+    };
+}
+//# sourceMappingURL=throttlingRetryPolicy.js.map

package/dist-esm/src/policies/throttlingRetryPolicy.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"throttlingRetryPolicy.js","sourceRoot":"","sources":["../../../src/policies/throttlingRetryPolicy.ts"],"names":[],"mappings":"AAAA,uCAAuC;AACvC,kCAAkC;AAGlC,OAAO,EAAE,uBAAuB,EAAE,MAAM,4CAA4C,CAAC;AACrF,OAAO,EAAE,WAAW,EAAE,MAAM,eAAe,CAAC;AAC5C,OAAO,EAAE,0BAA0B,EAAE,MAAM,cAAc,CAAC;AAE1D;;GAEG;AACH,MAAM,CAAC,MAAM,yBAAyB,GAAG,uBAAuB,CAAC;AAYjE;;;;;;;;;GASG;AACH,MAAM,UAAU,qBAAqB,CAAC,UAAwC,EAAE;;IAC9E,OAAO;QACL,IAAI,EAAE,yBAAyB;QAC/B,WAAW,EAAE,WAAW,CAAC,CAAC,uBAAuB,EAAE,CAAC,EAAE;YACpD,UAAU,EAAE,MAAA,OAAO,CAAC,UAAU,mCAAI,0BAA0B;SAC7D,CAAC,CAAC,WAAW;KACf,CAAC;AACJ,CAAC","sourcesContent":["// Copyright (c) Microsoft Corporation.\n// Licensed under the MIT license.\n\nimport { PipelinePolicy } from \"../pipeline\";\nimport { throttlingRetryStrategy } from \"../retryStrategies/throttlingRetryStrategy\";\nimport { retryPolicy } from \"./retryPolicy\";\nimport { DEFAULT_RETRY_POLICY_COUNT } from \"../constants\";\n\n/**\n * Name of the {@link throttlingRetryPolicy}\n */\nexport const throttlingRetryPolicyName = \"throttlingRetryPolicy\";\n\n/**\n * Options that control how to retry failed requests.\n */\nexport interface ThrottlingRetryPolicyOptions {\n  /**\n   * The maximum number of retry attempts. Defaults to 3.\n   */\n  maxRetries?: number;\n}\n\n/**\n * A policy that retries when the server sends a 429 response with a Retry-After header.\n *\n * To learn more, please refer to\n * https://docs.microsoft.com/en-us/azure/azure-resource-manager/resource-manager-request-limits,\n * https://docs.microsoft.com/en-us/azure/azure-subscription-service-limits and\n * https://docs.microsoft.com/en-us/azure/virtual-machines/troubleshooting/troubleshooting-throttling-errors\n *\n * @param options - Options that configure retry logic.\n */\nexport function throttlingRetryPolicy(options: ThrottlingRetryPolicyOptions = {}): PipelinePolicy {\n  return {\n    name: throttlingRetryPolicyName,\n    sendRequest: retryPolicy([throttlingRetryStrategy()], {\n      maxRetries: options.maxRetries ?? DEFAULT_RETRY_POLICY_COUNT,\n    }).sendRequest,\n  };\n}\n"]}

package/dist-esm/src/policies/tlsPolicy.js

@@ -0,0 +1,22 @@
+// Copyright (c) Microsoft Corporation.
+// Licensed under the MIT license.
+/**
+ * Name of the TLS Policy
+ */
+export const tlsPolicyName = "tlsPolicy";
+/**
+ * Gets a pipeline policy that adds the client certificate to the HttpClient agent for authentication.
+ */
+export function tlsPolicy(tlsSettings) {
+    return {
+        name: tlsPolicyName,
+        sendRequest: async (req, next) => {
+            // Users may define a request tlsSettings, honor those over the client level one
+            if (!req.tlsSettings) {
+                req.tlsSettings = tlsSettings;
+            }
+            return next(req);
+        },
+    };
+}
+//# sourceMappingURL=tlsPolicy.js.map

package/dist-esm/src/policies/tlsPolicy.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"tlsPolicy.js","sourceRoot":"","sources":["../../../src/policies/tlsPolicy.ts"],"names":[],"mappings":"AAAA,uCAAuC;AACvC,kCAAkC;AAKlC;;GAEG;AACH,MAAM,CAAC,MAAM,aAAa,GAAG,WAAW,CAAC;AAEzC;;GAEG;AACH,MAAM,UAAU,SAAS,CAAC,WAAyB;IACjD,OAAO;QACL,IAAI,EAAE,aAAa;QACnB,WAAW,EAAE,KAAK,EAAE,GAAG,EAAE,IAAI,EAAE,EAAE;YAC/B,gFAAgF;YAChF,IAAI,CAAC,GAAG,CAAC,WAAW,EAAE;gBACpB,GAAG,CAAC,WAAW,GAAG,WAAW,CAAC;aAC/B;YACD,OAAO,IAAI,CAAC,GAAG,CAAC,CAAC;QACnB,CAAC;KACF,CAAC;AACJ,CAAC","sourcesContent":["// Copyright (c) Microsoft Corporation.\n// Licensed under the MIT license.\n\nimport { PipelinePolicy } from \"../pipeline\";\nimport { TlsSettings } from \"../interfaces\";\n\n/**\n * Name of the TLS Policy\n */\nexport const tlsPolicyName = \"tlsPolicy\";\n\n/**\n * Gets a pipeline policy that adds the client certificate to the HttpClient agent for authentication.\n */\nexport function tlsPolicy(tlsSettings?: TlsSettings): PipelinePolicy {\n  return {\n    name: tlsPolicyName,\n    sendRequest: async (req, next) => {\n      // Users may define a request tlsSettings, honor those over the client level one\n      if (!req.tlsSettings) {\n        req.tlsSettings = tlsSettings;\n      }\n      return next(req);\n    },\n  };\n}\n"]}

package/dist-esm/src/policies/tracingPolicy.js

@@ -0,0 +1,120 @@
+// Copyright (c) Microsoft Corporation.
+// Licensed under the MIT license.
+import { createTracingClient } from "../tracing/tracingClient";
+import { SDK_VERSION } from "../constants";
+import { getUserAgentValue } from "../util/userAgent";
+import { logger } from "../log";
+import { getErrorMessage, isError } from "../util/error";
+import { isRestError } from "../restError";
+/**
+ * The programmatic identifier of the tracingPolicy.
+ */
+export const tracingPolicyName = "tracingPolicy";
+/**
+ * A simple policy to create OpenTelemetry Spans for each request made by the pipeline
+ * that has SpanOptions with a parent.
+ * Requests made without a parent Span will not be recorded.
+ * @param options - Options to configure the telemetry logged by the tracing policy.
+ */
+export function tracingPolicy(options = {}) {
+    const userAgent = getUserAgentValue(options.userAgentPrefix);
+    const tracingClient = tryCreateTracingClient();
+    return {
+        name: tracingPolicyName,
+        async sendRequest(request, next) {
+            var _a, _b;
+            if (!tracingClient || !((_a = request.tracingOptions) === null || _a === void 0 ? void 0 : _a.tracingContext)) {
+                return next(request);
+            }
+            const { span, tracingContext } = (_b = tryCreateSpan(tracingClient, request, userAgent)) !== null && _b !== void 0 ? _b : {};
+            if (!span || !tracingContext) {
+                return next(request);
+            }
+            try {
+                const response = await tracingClient.withContext(tracingContext, next, request);
+                tryProcessResponse(span, response);
+                return response;
+            }
+            catch (err) {
+                tryProcessError(span, err);
+                throw err;
+            }
+        },
+    };
+}
+function tryCreateTracingClient() {
+    try {
+        return createTracingClient({
+            namespace: "",
+            packageName: "@typespec/ts-http-runtime",
+            packageVersion: SDK_VERSION,
+        });
+    }
+    catch (e) {
+        logger.warning(`Error when creating the TracingClient: ${getErrorMessage(e)}`);
+        return undefined;
+    }
+}
+function tryCreateSpan(tracingClient, request, userAgent) {
+    try {
+        // As per spec, we do not need to differentiate between HTTP and HTTPS in span name.
+        const { span, updatedOptions } = tracingClient.startSpan(`HTTP ${request.method}`, { tracingOptions: request.tracingOptions }, {
+            spanKind: "client",
+            spanAttributes: {
+                "http.method": request.method,
+                "http.url": request.url,
+                requestId: request.requestId,
+            },
+        });
+        // If the span is not recording, don't do any more work.
+        if (!span.isRecording()) {
+            span.end();
+            return undefined;
+        }
+        if (userAgent) {
+            span.setAttribute("http.user_agent", userAgent);
+        }
+        // set headers
+        const headers = tracingClient.createRequestHeaders(updatedOptions.tracingOptions.tracingContext);
+        for (const [key, value] of Object.entries(headers)) {
+            request.headers.set(key, value);
+        }
+        return { span, tracingContext: updatedOptions.tracingOptions.tracingContext };
+    }
+    catch (e) {
+        logger.warning(`Skipping creating a tracing span due to an error: ${getErrorMessage(e)}`);
+        return undefined;
+    }
+}
+function tryProcessError(span, error) {
+    try {
+        span.setStatus({
+            status: "error",
+            error: isError(error) ? error : undefined,
+        });
+        if (isRestError(error) && error.statusCode) {
+            span.setAttribute("http.status_code", error.statusCode);
+        }
+        span.end();
+    }
+    catch (e) {
+        logger.warning(`Skipping tracing span processing due to an error: ${getErrorMessage(e)}`);
+    }
+}
+function tryProcessResponse(span, response) {
+    try {
+        span.setAttribute("http.status_code", response.status);
+        const serviceRequestId = response.headers.get("x-ms-request-id");
+        if (serviceRequestId) {
+            span.setAttribute("serviceRequestId", serviceRequestId);
+        }
+        span.setStatus({
+            status: "success",
+        });
+        span.end();
+    }
+    catch (e) {
+        logger.warning(`Skipping tracing span processing due to an error: ${getErrorMessage(e)}`);
+    }
+}
+//# sourceMappingURL=tracingPolicy.js.map

package/dist-esm/src/policies/tracingPolicy.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"tracingPolicy.js","sourceRoot":"","sources":["../../../src/policies/tracingPolicy.ts"],"names":[],"mappings":"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","sourcesContent":["// Copyright (c) Microsoft Corporation.\n// Licensed under the MIT license.\n\nimport { TracingClient, TracingContext, TracingSpan } from \"../tracing/interfaces\";\nimport { createTracingClient } from \"../tracing/tracingClient\";\nimport { SDK_VERSION } from \"../constants\";\nimport { PipelineRequest, PipelineResponse, SendRequest } from \"../interfaces\";\nimport { PipelinePolicy } from \"../pipeline\";\nimport { getUserAgentValue } from \"../util/userAgent\";\nimport { logger } from \"../log\";\nimport { getErrorMessage, isError } from \"../util/error\";\nimport { isRestError } from \"../restError\";\n\n/**\n * The programmatic identifier of the tracingPolicy.\n */\nexport const tracingPolicyName = \"tracingPolicy\";\n\n/**\n * Options to configure the tracing policy.\n */\nexport interface TracingPolicyOptions {\n  /**\n   * String prefix to add to the user agent logged as metadata\n   * on the generated Span.\n   * Defaults to an empty string.\n   */\n  userAgentPrefix?: string;\n}\n\n/**\n * A simple policy to create OpenTelemetry Spans for each request made by the pipeline\n * that has SpanOptions with a parent.\n * Requests made without a parent Span will not be recorded.\n * @param options - Options to configure the telemetry logged by the tracing policy.\n */\nexport function tracingPolicy(options: TracingPolicyOptions = {}): PipelinePolicy {\n  const userAgent = getUserAgentValue(options.userAgentPrefix);\n  const tracingClient = tryCreateTracingClient();\n\n  return {\n    name: tracingPolicyName,\n    async sendRequest(request: PipelineRequest, next: SendRequest): Promise<PipelineResponse> {\n      if (!tracingClient || !request.tracingOptions?.tracingContext) {\n        return next(request);\n      }\n\n      const { span, tracingContext } = tryCreateSpan(tracingClient, request, userAgent) ?? {};\n\n      if (!span || !tracingContext) {\n        return next(request);\n      }\n\n      try {\n        const response = await tracingClient.withContext(tracingContext, next, request);\n        tryProcessResponse(span, response);\n        return response;\n      } catch (err: any) {\n        tryProcessError(span, err);\n        throw err;\n      }\n    },\n  };\n}\n\nfunction tryCreateTracingClient(): TracingClient | undefined {\n  try {\n    return createTracingClient({\n      namespace: \"\",\n      packageName: \"@typespec/ts-http-runtime\",\n      packageVersion: SDK_VERSION,\n    });\n  } catch (e: unknown) {\n    logger.warning(`Error when creating the TracingClient: ${getErrorMessage(e)}`);\n    return undefined;\n  }\n}\n\nfunction tryCreateSpan(\n  tracingClient: TracingClient,\n  request: PipelineRequest,\n  userAgent?: string\n): { span: TracingSpan; tracingContext: TracingContext } | undefined {\n  try {\n    // As per spec, we do not need to differentiate between HTTP and HTTPS in span name.\n    const { span, updatedOptions } = tracingClient.startSpan(\n      `HTTP ${request.method}`,\n      { tracingOptions: request.tracingOptions },\n      {\n        spanKind: \"client\",\n        spanAttributes: {\n          \"http.method\": request.method,\n          \"http.url\": request.url,\n          requestId: request.requestId,\n        },\n      }\n    );\n\n    // If the span is not recording, don't do any more work.\n    if (!span.isRecording()) {\n      span.end();\n      return undefined;\n    }\n\n    if (userAgent) {\n      span.setAttribute(\"http.user_agent\", userAgent);\n    }\n\n    // set headers\n    const headers = tracingClient.createRequestHeaders(\n      updatedOptions.tracingOptions.tracingContext\n    );\n    for (const [key, value] of Object.entries(headers)) {\n      request.headers.set(key, value);\n    }\n    return { span, tracingContext: updatedOptions.tracingOptions.tracingContext };\n  } catch (e: any) {\n    logger.warning(`Skipping creating a tracing span due to an error: ${getErrorMessage(e)}`);\n    return undefined;\n  }\n}\n\nfunction tryProcessError(span: TracingSpan, error: unknown): void {\n  try {\n    span.setStatus({\n      status: \"error\",\n      error: isError(error) ? error : undefined,\n    });\n    if (isRestError(error) && error.statusCode) {\n      span.setAttribute(\"http.status_code\", error.statusCode);\n    }\n    span.end();\n  } catch (e: any) {\n    logger.warning(`Skipping tracing span processing due to an error: ${getErrorMessage(e)}`);\n  }\n}\n\nfunction tryProcessResponse(span: TracingSpan, response: PipelineResponse): void {\n  try {\n    span.setAttribute(\"http.status_code\", response.status);\n    const serviceRequestId = response.headers.get(\"x-ms-request-id\");\n    if (serviceRequestId) {\n      span.setAttribute(\"serviceRequestId\", serviceRequestId);\n    }\n    span.setStatus({\n      status: \"success\",\n    });\n    span.end();\n  } catch (e: any) {\n    logger.warning(`Skipping tracing span processing due to an error: ${getErrorMessage(e)}`);\n  }\n}\n"]}

package/dist-esm/src/policies/userAgentPolicy.js

@@ -0,0 +1,26 @@
+// Copyright (c) Microsoft Corporation.
+// Licensed under the MIT license.
+import { getUserAgentHeaderName, getUserAgentValue } from "../util/userAgent";
+const UserAgentHeaderName = getUserAgentHeaderName();
+/**
+ * The programmatic identifier of the userAgentPolicy.
+ */
+export const userAgentPolicyName = "userAgentPolicy";
+/**
+ * A policy that sets the User-Agent header (or equivalent) to reflect
+ * the library version.
+ * @param options - Options to customize the user agent value.
+ */
+export function userAgentPolicy(options = {}) {
+    const userAgentValue = getUserAgentValue(options.userAgentPrefix);
+    return {
+        name: userAgentPolicyName,
+        async sendRequest(request, next) {
+            if (!request.headers.has(UserAgentHeaderName)) {
+                request.headers.set(UserAgentHeaderName, userAgentValue);
+            }
+            return next(request);
+        },
+    };
+}
+//# sourceMappingURL=userAgentPolicy.js.map

package/dist-esm/src/policies/userAgentPolicy.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"userAgentPolicy.js","sourceRoot":"","sources":["../../../src/policies/userAgentPolicy.ts"],"names":[],"mappings":"AAAA,uCAAuC;AACvC,kCAAkC;AAIlC,OAAO,EAAE,sBAAsB,EAAE,iBAAiB,EAAE,MAAM,mBAAmB,CAAC;AAE9E,MAAM,mBAAmB,GAAG,sBAAsB,EAAE,CAAC;AAErD;;GAEG;AACH,MAAM,CAAC,MAAM,mBAAmB,GAAG,iBAAiB,CAAC;AAarD;;;;GAIG;AACH,MAAM,UAAU,eAAe,CAAC,UAAkC,EAAE;IAClE,MAAM,cAAc,GAAG,iBAAiB,CAAC,OAAO,CAAC,eAAe,CAAC,CAAC;IAClE,OAAO;QACL,IAAI,EAAE,mBAAmB;QACzB,KAAK,CAAC,WAAW,CAAC,OAAwB,EAAE,IAAiB;YAC3D,IAAI,CAAC,OAAO,CAAC,OAAO,CAAC,GAAG,CAAC,mBAAmB,CAAC,EAAE;gBAC7C,OAAO,CAAC,OAAO,CAAC,GAAG,CAAC,mBAAmB,EAAE,cAAc,CAAC,CAAC;aAC1D;YACD,OAAO,IAAI,CAAC,OAAO,CAAC,CAAC;QACvB,CAAC;KACF,CAAC;AACJ,CAAC","sourcesContent":["// Copyright (c) Microsoft Corporation.\n// Licensed under the MIT license.\n\nimport { PipelineRequest, PipelineResponse, SendRequest } from \"../interfaces\";\nimport { PipelinePolicy } from \"../pipeline\";\nimport { getUserAgentHeaderName, getUserAgentValue } from \"../util/userAgent\";\n\nconst UserAgentHeaderName = getUserAgentHeaderName();\n\n/**\n * The programmatic identifier of the userAgentPolicy.\n */\nexport const userAgentPolicyName = \"userAgentPolicy\";\n\n/**\n * Options for adding user agent details to outgoing requests.\n */\nexport interface UserAgentPolicyOptions {\n  /**\n   * String prefix to add to the user agent for outgoing requests.\n   * Defaults to an empty string.\n   */\n  userAgentPrefix?: string;\n}\n\n/**\n * A policy that sets the User-Agent header (or equivalent) to reflect\n * the library version.\n * @param options - Options to customize the user agent value.\n */\nexport function userAgentPolicy(options: UserAgentPolicyOptions = {}): PipelinePolicy {\n  const userAgentValue = getUserAgentValue(options.userAgentPrefix);\n  return {\n    name: userAgentPolicyName,\n    async sendRequest(request: PipelineRequest, next: SendRequest): Promise<PipelineResponse> {\n      if (!request.headers.has(UserAgentHeaderName)) {\n        request.headers.set(UserAgentHeaderName, userAgentValue);\n      }\n      return next(request);\n    },\n  };\n}\n"]}

package/dist-esm/src/restError.js

@@ -0,0 +1,48 @@
+// Copyright (c) Microsoft Corporation.
+// Licensed under the MIT license.
+import { isError } from "./util/error";
+import { custom } from "./util/inspect";
+import { Sanitizer } from "./util/sanitizer";
+const errorSanitizer = new Sanitizer();
+/**
+ * A custom error type for failed pipeline requests.
+ */
+export class RestError extends Error {
+    constructor(message, options = {}) {
+        super(message);
+        this.name = "RestError";
+        this.code = options.code;
+        this.statusCode = options.statusCode;
+        this.request = options.request;
+        this.response = options.response;
+        Object.setPrototypeOf(this, RestError.prototype);
+    }
+    /**
+     * Logging method for util.inspect in Node
+     */
+    [custom]() {
+        return `RestError: ${this.message} \n ${errorSanitizer.sanitize(this)}`;
+    }
+}
+/**
+ * Something went wrong when making the request.
+ * This means the actual request failed for some reason,
+ * such as a DNS issue or the connection being lost.
+ */
+RestError.REQUEST_SEND_ERROR = "REQUEST_SEND_ERROR";
+/**
+ * This means that parsing the response from the server failed.
+ * It may have been malformed.
+ */
+RestError.PARSE_ERROR = "PARSE_ERROR";
+/**
+ * Typeguard for RestError
+ * @param e - Something caught by a catch clause.
+ */
+export function isRestError(e) {
+    if (e instanceof RestError) {
+        return true;
+    }
+    return isError(e) && e.name === "RestError";
+}
+//# sourceMappingURL=restError.js.map

package/dist-esm/src/restError.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"restError.js","sourceRoot":"","sources":["../../src/restError.ts"],"names":[],"mappings":"AAAA,uCAAuC;AACvC,kCAAkC;AAElC,OAAO,EAAE,OAAO,EAAE,MAAM,cAAc,CAAC;AAEvC,OAAO,EAAE,MAAM,EAAE,MAAM,gBAAgB,CAAC;AACxC,OAAO,EAAE,SAAS,EAAE,MAAM,kBAAkB,CAAC;AAE7C,MAAM,cAAc,GAAG,IAAI,SAAS,EAAE,CAAC;AAwBvC;;GAEG;AACH,MAAM,OAAO,SAAU,SAAQ,KAAK;IAkClC,YAAY,OAAe,EAAE,UAA4B,EAAE;QACzD,KAAK,CAAC,OAAO,CAAC,CAAC;QACf,IAAI,CAAC,IAAI,GAAG,WAAW,CAAC;QACxB,IAAI,CAAC,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC;QACzB,IAAI,CAAC,UAAU,GAAG,OAAO,CAAC,UAAU,CAAC;QACrC,IAAI,CAAC,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC;QAC/B,IAAI,CAAC,QAAQ,GAAG,OAAO,CAAC,QAAQ,CAAC;QAEjC,MAAM,CAAC,cAAc,CAAC,IAAI,EAAE,SAAS,CAAC,SAAS,CAAC,CAAC;IACnD,CAAC;IAED;;OAEG;IACH,CAAC,MAAM,CAAC;QACN,OAAO,cAAc,IAAI,CAAC,OAAO,OAAO,cAAc,CAAC,QAAQ,CAAC,IAAI,CAAC,EAAE,CAAC;IAC1E,CAAC;;AAjDD;;;;GAIG;AACa,4BAAkB,GAAW,oBAAoB,CAAC;AAClE;;;GAGG;AACa,qBAAW,GAAW,aAAa,CAAC;AA0CtD;;;GAGG;AACH,MAAM,UAAU,WAAW,CAAC,CAAU;IACpC,IAAI,CAAC,YAAY,SAAS,EAAE;QAC1B,OAAO,IAAI,CAAC;KACb;IACD,OAAO,OAAO,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,IAAI,KAAK,WAAW,CAAC;AAC9C,CAAC","sourcesContent":["// Copyright (c) Microsoft Corporation.\n// Licensed under the MIT license.\n\nimport { isError } from \"./util/error\";\nimport { PipelineRequest, PipelineResponse } from \"./interfaces\";\nimport { custom } from \"./util/inspect\";\nimport { Sanitizer } from \"./util/sanitizer\";\n\nconst errorSanitizer = new Sanitizer();\n\n/**\n * The options supported by RestError.\n */\nexport interface RestErrorOptions {\n  /**\n   * The code of the error itself (use statics on RestError if possible.)\n   */\n  code?: string;\n  /**\n   * The HTTP status code of the request (if applicable.)\n   */\n  statusCode?: number;\n  /**\n   * The request that was made.\n   */\n  request?: PipelineRequest;\n  /**\n   * The response received (if any.)\n   */\n  response?: PipelineResponse;\n}\n\n/**\n * A custom error type for failed pipeline requests.\n */\nexport class RestError extends Error {\n  /**\n   * Something went wrong when making the request.\n   * This means the actual request failed for some reason,\n   * such as a DNS issue or the connection being lost.\n   */\n  static readonly REQUEST_SEND_ERROR: string = \"REQUEST_SEND_ERROR\";\n  /**\n   * This means that parsing the response from the server failed.\n   * It may have been malformed.\n   */\n  static readonly PARSE_ERROR: string = \"PARSE_ERROR\";\n\n  /**\n   * The code of the error itself (use statics on RestError if possible.)\n   */\n  public code?: string;\n  /**\n   * The HTTP status code of the request (if applicable.)\n   */\n  public statusCode?: number;\n  /**\n   * The request that was made.\n   */\n  public request?: PipelineRequest;\n  /**\n   * The response received (if any.)\n   */\n  public response?: PipelineResponse;\n  /**\n   * Bonus property set by the throw site.\n   */\n  public details?: unknown;\n\n  constructor(message: string, options: RestErrorOptions = {}) {\n    super(message);\n    this.name = \"RestError\";\n    this.code = options.code;\n    this.statusCode = options.statusCode;\n    this.request = options.request;\n    this.response = options.response;\n\n    Object.setPrototypeOf(this, RestError.prototype);\n  }\n\n  /**\n   * Logging method for util.inspect in Node\n   */\n  [custom](): string {\n    return `RestError: ${this.message} \\n ${errorSanitizer.sanitize(this)}`;\n  }\n}\n\n/**\n * Typeguard for RestError\n * @param e - Something caught by a catch clause.\n */\nexport function isRestError(e: unknown): e is RestError {\n  if (e instanceof RestError) {\n    return true;\n  }\n  return isError(e) && e.name === \"RestError\";\n}\n"]}

package/dist-esm/src/retryStrategies/exponentialRetryStrategy.js

@@ -0,0 +1,70 @@
+// Copyright (c) Microsoft Corporation.
+// Licensed under the MIT license.
+import { getRandomIntegerInclusive } from "../util/random";
+import { isThrottlingRetryResponse } from "./throttlingRetryStrategy";
+// intervals are in milliseconds
+const DEFAULT_CLIENT_RETRY_INTERVAL = 1000;
+const DEFAULT_CLIENT_MAX_RETRY_INTERVAL = 1000 * 64;
+/**
+ * A retry strategy that retries with an exponentially increasing delay in these two cases:
+ * - When there are errors in the underlying transport layer (e.g. DNS lookup failures).
+ * - Or otherwise if the outgoing request fails (408, greater or equal than 500, except for 501 and 505).
+ */
+export function exponentialRetryStrategy(options = {}) {
+    var _a, _b;
+    const retryInterval = (_a = options.retryDelayInMs) !== null && _a !== void 0 ? _a : DEFAULT_CLIENT_RETRY_INTERVAL;
+    const maxRetryInterval = (_b = options.maxRetryDelayInMs) !== null && _b !== void 0 ? _b : DEFAULT_CLIENT_MAX_RETRY_INTERVAL;
+    let retryAfterInMs = retryInterval;
+    return {
+        name: "exponentialRetryStrategy",
+        retry({ retryCount, response, responseError }) {
+            const matchedSystemError = isSystemError(responseError);
+            const ignoreSystemErrors = matchedSystemError && options.ignoreSystemErrors;
+            const isExponential = isExponentialRetryResponse(response);
+            const ignoreExponentialResponse = isExponential && options.ignoreHttpStatusCodes;
+            const unknownResponse = response && (isThrottlingRetryResponse(response) || !isExponential);
+            if (unknownResponse || ignoreExponentialResponse || ignoreSystemErrors) {
+                return { skipStrategy: true };
+            }
+            if (responseError && !matchedSystemError && !isExponential) {
+                return { errorToThrow: responseError };
+            }
+            // Exponentially increase the delay each time
+            const exponentialDelay = retryAfterInMs * Math.pow(2, retryCount);
+            // Don't let the delay exceed the maximum
+            const clampedExponentialDelay = Math.min(maxRetryInterval, exponentialDelay);
+            // Allow the final value to have some "jitter" (within 50% of the delay size) so
+            // that retries across multiple clients don't occur simultaneously.
+            retryAfterInMs =
+                clampedExponentialDelay / 2 + getRandomIntegerInclusive(0, clampedExponentialDelay / 2);
+            return { retryAfterInMs };
+        },
+    };
+}
+/**
+ * A response is a retry response if it has status codes:
+ * - 408, or
+ * - Greater or equal than 500, except for 501 and 505.
+ */
+export function isExponentialRetryResponse(response) {
+    return Boolean(response &&
+        response.status !== undefined &&
+        (response.status >= 500 || response.status === 408) &&
+        response.status !== 501 &&
+        response.status !== 505);
+}
+/**
+ * Determines whether an error from a pipeline response was triggered in the network layer.
+ */
+export function isSystemError(err) {
+    if (!err) {
+        return false;
+    }
+    return (err.code === "ETIMEDOUT" ||
+        err.code === "ESOCKETTIMEDOUT" ||
+        err.code === "ECONNREFUSED" ||
+        err.code === "ECONNRESET" ||
+        err.code === "ENOENT" ||
+        err.code === "ENOTFOUND");
+}
+//# sourceMappingURL=exponentialRetryStrategy.js.map

package/dist-esm/src/retryStrategies/exponentialRetryStrategy.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"exponentialRetryStrategy.js","sourceRoot":"","sources":["../../../src/retryStrategies/exponentialRetryStrategy.ts"],"names":[],"mappings":"AAAA,uCAAuC;AACvC,kCAAkC;AAIlC,OAAO,EAAE,yBAAyB,EAAE,MAAM,gBAAgB,CAAC;AAE3D,OAAO,EAAE,yBAAyB,EAAE,MAAM,2BAA2B,CAAC;AAEtE,gCAAgC;AAChC,MAAM,6BAA6B,GAAG,IAAI,CAAC;AAC3C,MAAM,iCAAiC,GAAG,IAAI,GAAG,EAAE,CAAC;AAEpD;;;;GAIG;AACH,MAAM,UAAU,wBAAwB,CACtC,UAuBI,EAAE;;IAEN,MAAM,aAAa,GAAG,MAAA,OAAO,CAAC,cAAc,mCAAI,6BAA6B,CAAC;IAC9E,MAAM,gBAAgB,GAAG,MAAA,OAAO,CAAC,iBAAiB,mCAAI,iCAAiC,CAAC;IAExF,IAAI,cAAc,GAAG,aAAa,CAAC;IAEnC,OAAO;QACL,IAAI,EAAE,0BAA0B;QAChC,KAAK,CAAC,EAAE,UAAU,EAAE,QAAQ,EAAE,aAAa,EAAE;YAC3C,MAAM,kBAAkB,GAAG,aAAa,CAAC,aAAa,CAAC,CAAC;YACxD,MAAM,kBAAkB,GAAG,kBAAkB,IAAI,OAAO,CAAC,kBAAkB,CAAC;YAE5E,MAAM,aAAa,GAAG,0BAA0B,CAAC,QAAQ,CAAC,CAAC;YAC3D,MAAM,yBAAyB,GAAG,aAAa,IAAI,OAAO,CAAC,qBAAqB,CAAC;YACjF,MAAM,eAAe,GAAG,QAAQ,IAAI,CAAC,yBAAyB,CAAC,QAAQ,CAAC,IAAI,CAAC,aAAa,CAAC,CAAC;YAE5F,IAAI,eAAe,IAAI,yBAAyB,IAAI,kBAAkB,EAAE;gBACtE,OAAO,EAAE,YAAY,EAAE,IAAI,EAAE,CAAC;aAC/B;YAED,IAAI,aAAa,IAAI,CAAC,kBAAkB,IAAI,CAAC,aAAa,EAAE;gBAC1D,OAAO,EAAE,YAAY,EAAE,aAAa,EAAE,CAAC;aACxC;YAED,6CAA6C;YAC7C,MAAM,gBAAgB,GAAG,cAAc,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,UAAU,CAAC,CAAC;YAClE,yCAAyC;YACzC,MAAM,uBAAuB,GAAG,IAAI,CAAC,GAAG,CAAC,gBAAgB,EAAE,gBAAgB,CAAC,CAAC;YAC7E,gFAAgF;YAChF,mEAAmE;YACnE,cAAc;gBACZ,uBAAuB,GAAG,CAAC,GAAG,yBAAyB,CAAC,CAAC,EAAE,uBAAuB,GAAG,CAAC,CAAC,CAAC;YAC1F,OAAO,EAAE,cAAc,EAAE,CAAC;QAC5B,CAAC;KACF,CAAC;AACJ,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,0BAA0B,CAAC,QAA2B;IACpE,OAAO,OAAO,CACZ,QAAQ;QACN,QAAQ,CAAC,MAAM,KAAK,SAAS;QAC7B,CAAC,QAAQ,CAAC,MAAM,IAAI,GAAG,IAAI,QAAQ,CAAC,MAAM,KAAK,GAAG,CAAC;QACnD,QAAQ,CAAC,MAAM,KAAK,GAAG;QACvB,QAAQ,CAAC,MAAM,KAAK,GAAG,CAC1B,CAAC;AACJ,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,aAAa,CAAC,GAAe;IAC3C,IAAI,CAAC,GAAG,EAAE;QACR,OAAO,KAAK,CAAC;KACd;IACD,OAAO,CACL,GAAG,CAAC,IAAI,KAAK,WAAW;QACxB,GAAG,CAAC,IAAI,KAAK,iBAAiB;QAC9B,GAAG,CAAC,IAAI,KAAK,cAAc;QAC3B,GAAG,CAAC,IAAI,KAAK,YAAY;QACzB,GAAG,CAAC,IAAI,KAAK,QAAQ;QACrB,GAAG,CAAC,IAAI,KAAK,WAAW,CACzB,CAAC;AACJ,CAAC","sourcesContent":["// Copyright (c) Microsoft Corporation.\n// Licensed under the MIT license.\n\nimport { PipelineResponse } from \"../interfaces\";\nimport { RestError } from \"../restError\";\nimport { getRandomIntegerInclusive } from \"../util/random\";\nimport { RetryStrategy } from \"./retryStrategy\";\nimport { isThrottlingRetryResponse } from \"./throttlingRetryStrategy\";\n\n// intervals are in milliseconds\nconst DEFAULT_CLIENT_RETRY_INTERVAL = 1000;\nconst DEFAULT_CLIENT_MAX_RETRY_INTERVAL = 1000 * 64;\n\n/**\n * A retry strategy that retries with an exponentially increasing delay in these two cases:\n * - When there are errors in the underlying transport layer (e.g. DNS lookup failures).\n * - Or otherwise if the outgoing request fails (408, greater or equal than 500, except for 501 and 505).\n */\nexport function exponentialRetryStrategy(\n  options: {\n    /**\n     * The amount of delay in milliseconds between retry attempts. Defaults to 1000\n     * (1 second.) The delay increases exponentially with each retry up to a maximum\n     * specified by maxRetryDelayInMs.\n     */\n    retryDelayInMs?: number;\n\n    /**\n     * The maximum delay in milliseconds allowed before retrying an operation. Defaults\n     * to 64000 (64 seconds).\n     */\n    maxRetryDelayInMs?: number;\n\n    /**\n     * If true it won't retry if it received a system error.\n     */\n    ignoreSystemErrors?: boolean;\n\n    /**\n     * If true it won't retry if it received a non-fatal HTTP status code.\n     */\n    ignoreHttpStatusCodes?: boolean;\n  } = {}\n): RetryStrategy {\n  const retryInterval = options.retryDelayInMs ?? DEFAULT_CLIENT_RETRY_INTERVAL;\n  const maxRetryInterval = options.maxRetryDelayInMs ?? DEFAULT_CLIENT_MAX_RETRY_INTERVAL;\n\n  let retryAfterInMs = retryInterval;\n\n  return {\n    name: \"exponentialRetryStrategy\",\n    retry({ retryCount, response, responseError }) {\n      const matchedSystemError = isSystemError(responseError);\n      const ignoreSystemErrors = matchedSystemError && options.ignoreSystemErrors;\n\n      const isExponential = isExponentialRetryResponse(response);\n      const ignoreExponentialResponse = isExponential && options.ignoreHttpStatusCodes;\n      const unknownResponse = response && (isThrottlingRetryResponse(response) || !isExponential);\n\n      if (unknownResponse || ignoreExponentialResponse || ignoreSystemErrors) {\n        return { skipStrategy: true };\n      }\n\n      if (responseError && !matchedSystemError && !isExponential) {\n        return { errorToThrow: responseError };\n      }\n\n      // Exponentially increase the delay each time\n      const exponentialDelay = retryAfterInMs * Math.pow(2, retryCount);\n      // Don't let the delay exceed the maximum\n      const clampedExponentialDelay = Math.min(maxRetryInterval, exponentialDelay);\n      // Allow the final value to have some \"jitter\" (within 50% of the delay size) so\n      // that retries across multiple clients don't occur simultaneously.\n      retryAfterInMs =\n        clampedExponentialDelay / 2 + getRandomIntegerInclusive(0, clampedExponentialDelay / 2);\n      return { retryAfterInMs };\n    },\n  };\n}\n\n/**\n * A response is a retry response if it has status codes:\n * - 408, or\n * - Greater or equal than 500, except for 501 and 505.\n */\nexport function isExponentialRetryResponse(response?: PipelineResponse): boolean {\n  return Boolean(\n    response &&\n      response.status !== undefined &&\n      (response.status >= 500 || response.status === 408) &&\n      response.status !== 501 &&\n      response.status !== 505\n  );\n}\n\n/**\n * Determines whether an error from a pipeline response was triggered in the network layer.\n */\nexport function isSystemError(err?: RestError): boolean {\n  if (!err) {\n    return false;\n  }\n  return (\n    err.code === \"ETIMEDOUT\" ||\n    err.code === \"ESOCKETTIMEDOUT\" ||\n    err.code === \"ECONNREFUSED\" ||\n    err.code === \"ECONNRESET\" ||\n    err.code === \"ENOENT\" ||\n    err.code === \"ENOTFOUND\"\n  );\n}\n"]}

package/dist-esm/src/retryStrategies/retryStrategy.js

@@ -0,0 +1,4 @@
+// Copyright (c) Microsoft Corporation.
+// Licensed under the MIT license.
+export {};
+//# sourceMappingURL=retryStrategy.js.map

package/dist-esm/src/retryStrategies/retryStrategy.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"retryStrategy.js","sourceRoot":"","sources":["../../../src/retryStrategies/retryStrategy.ts"],"names":[],"mappings":"AAAA,uCAAuC;AACvC,kCAAkC","sourcesContent":["// Copyright (c) Microsoft Corporation.\n// Licensed under the MIT license.\n\nimport { TypeSpecRuntimeLogger } from \"../logger/logger\";\nimport { PipelineResponse } from \"../interfaces\";\nimport { RestError } from \"../restError\";\n\n/**\n * Information provided to the retry strategy about the current progress of the retry policy.\n */\nexport interface RetryInformation {\n  /**\n   * A {@link PipelineResponse}, if the last retry attempt succeeded.\n   */\n  response?: PipelineResponse;\n  /**\n   * A {@link RestError}, if the last retry attempt failed.\n   */\n  responseError?: RestError;\n  /**\n   * Total number of retries so far.\n   */\n  retryCount: number;\n}\n\n/**\n * Properties that can modify the behavior of the retry policy.\n */\nexport interface RetryModifiers {\n  /**\n   * If true, allows skipping the current strategy from running on the retry policy.\n   */\n  skipStrategy?: boolean;\n  /**\n   * Indicates to retry against this URL.\n   */\n  redirectTo?: string;\n  /**\n   * Controls whether to retry in a given number of milliseconds.\n   * If provided, a new retry will be attempted.\n   */\n  retryAfterInMs?: number;\n  /**\n   * Indicates to throw this error instead of retrying.\n   */\n  errorToThrow?: RestError;\n}\n\n/**\n * A retry strategy is intended to define whether to retry or not, and how to retry.\n */\nexport interface RetryStrategy {\n  /**\n   * Name of the retry strategy. Used for logging.\n   */\n  name: string;\n  /**\n   * Logger. If it's not provided, a default logger for all retry strategies is used.\n   */\n  logger?: TypeSpecRuntimeLogger;\n  /**\n   * Function that determines how to proceed with the subsequent requests.\n   * @param state - Retry state\n   */\n  retry(state: RetryInformation): RetryModifiers;\n}\n"]}

package/dist-esm/src/retryStrategies/throttlingRetryStrategy.js

@@ -0,0 +1,74 @@
+// Copyright (c) Microsoft Corporation.
+// Licensed under the MIT license.
+import { parseHeaderValueAsNumber } from "../util/helpers";
+/**
+ * The header that comes back from services representing
+ * the amount of time (minimum) to wait to retry (in seconds or timestamp after which we can retry).
+ */
+const RetryAfterHeader = "Retry-After";
+/**
+ * The headers that come back from services representing
+ * the amount of time (minimum) to wait to retry.
+ *
+ * "retry-after-ms", "x-ms-retry-after-ms" : milliseconds
+ * "Retry-After" : seconds or timestamp
+ */
+const AllRetryAfterHeaders = ["retry-after-ms", "x-ms-retry-after-ms", RetryAfterHeader];
+/**
+ * A response is a throttling retry response if it has a throttling status code (429 or 503),
+ * as long as one of the [ "Retry-After" or "retry-after-ms" or "x-ms-retry-after-ms" ] headers has a valid value.
+ *
+ * Returns the `retryAfterInMs` value if the response is a throttling retry response.
+ * If not throttling retry response, returns `undefined`.
+ *
+ * @internal
+ */
+function getRetryAfterInMs(response) {
+    if (!(response && [429, 503].includes(response.status)))
+        return undefined;
+    try {
+        // Headers: "retry-after-ms", "x-ms-retry-after-ms", "Retry-After"
+        for (const header of AllRetryAfterHeaders) {
+            const retryAfterValue = parseHeaderValueAsNumber(response, header);
+            if (retryAfterValue === 0 || retryAfterValue) {
+                // "Retry-After" header ==> seconds
+                // "retry-after-ms", "x-ms-retry-after-ms" headers ==> milli-seconds
+                const multiplyingFactor = header === RetryAfterHeader ? 1000 : 1;
+                return retryAfterValue * multiplyingFactor; // in milli-seconds
+            }
+        }
+        // RetryAfterHeader ("Retry-After") has a special case where it might be formatted as a date instead of a number of seconds
+        const retryAfterHeader = response.headers.get(RetryAfterHeader);
+        if (!retryAfterHeader)
+            return;
+        const date = Date.parse(retryAfterHeader);
+        const diff = date - Date.now();
+        // negative diff would mean a date in the past, so retry asap with 0 milliseconds
+        return Number.isFinite(diff) ? Math.max(0, diff) : undefined;
+    }
+    catch (e) {
+        return undefined;
+    }
+}
+/**
+ * A response is a retry response if it has a throttling status code (429 or 503),
+ * as long as one of the [ "Retry-After" or "retry-after-ms" or "x-ms-retry-after-ms" ] headers has a valid value.
+ */
+export function isThrottlingRetryResponse(response) {
+    return Number.isFinite(getRetryAfterInMs(response));
+}
+export function throttlingRetryStrategy() {
+    return {
+        name: "throttlingRetryStrategy",
+        retry({ response }) {
+            const retryAfterInMs = getRetryAfterInMs(response);
+            if (!Number.isFinite(retryAfterInMs)) {
+                return { skipStrategy: true };
+            }
+            return {
+                retryAfterInMs,
+            };
+        },
+    };
+}
+//# sourceMappingURL=throttlingRetryStrategy.js.map

package/dist-esm/src/retryStrategies/throttlingRetryStrategy.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"throttlingRetryStrategy.js","sourceRoot":"","sources":["../../../src/retryStrategies/throttlingRetryStrategy.ts"],"names":[],"mappings":"AAAA,uCAAuC;AACvC,kCAAkC;AAGlC,OAAO,EAAE,wBAAwB,EAAE,MAAM,iBAAiB,CAAC;AAG3D;;;GAGG;AACH,MAAM,gBAAgB,GAAG,aAAa,CAAC;AACvC;;;;;;GAMG;AACH,MAAM,oBAAoB,GAAa,CAAC,gBAAgB,EAAE,qBAAqB,EAAE,gBAAgB,CAAC,CAAC;AAEnG;;;;;;;;GAQG;AACH,SAAS,iBAAiB,CAAC,QAA2B;IACpD,IAAI,CAAC,CAAC,QAAQ,IAAI,CAAC,GAAG,EAAE,GAAG,CAAC,CAAC,QAAQ,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC;QAAE,OAAO,SAAS,CAAC;IAC1E,IAAI;QACF,kEAAkE;QAClE,KAAK,MAAM,MAAM,IAAI,oBAAoB,EAAE;YACzC,MAAM,eAAe,GAAG,wBAAwB,CAAC,QAAQ,EAAE,MAAM,CAAC,CAAC;YACnE,IAAI,eAAe,KAAK,CAAC,IAAI,eAAe,EAAE;gBAC5C,mCAAmC;gBACnC,oEAAoE;gBACpE,MAAM,iBAAiB,GAAG,MAAM,KAAK,gBAAgB,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC;gBACjE,OAAO,eAAe,GAAG,iBAAiB,CAAC,CAAC,mBAAmB;aAChE;SACF;QAED,2HAA2H;QAC3H,MAAM,gBAAgB,GAAG,QAAQ,CAAC,OAAO,CAAC,GAAG,CAAC,gBAAgB,CAAC,CAAC;QAChE,IAAI,CAAC,gBAAgB;YAAE,OAAO;QAE9B,MAAM,IAAI,GAAG,IAAI,CAAC,KAAK,CAAC,gBAAgB,CAAC,CAAC;QAC1C,MAAM,IAAI,GAAG,IAAI,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC;QAC/B,iFAAiF;QACjF,OAAO,MAAM,CAAC,QAAQ,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,IAAI,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC;KAC9D;IAAC,OAAO,CAAM,EAAE;QACf,OAAO,SAAS,CAAC;KAClB;AACH,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,yBAAyB,CAAC,QAA2B;IACnE,OAAO,MAAM,CAAC,QAAQ,CAAC,iBAAiB,CAAC,QAAQ,CAAC,CAAC,CAAC;AACtD,CAAC;AAED,MAAM,UAAU,uBAAuB;IACrC,OAAO;QACL,IAAI,EAAE,yBAAyB;QAC/B,KAAK,CAAC,EAAE,QAAQ,EAAE;YAChB,MAAM,cAAc,GAAG,iBAAiB,CAAC,QAAQ,CAAC,CAAC;YACnD,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,cAAc,CAAC,EAAE;gBACpC,OAAO,EAAE,YAAY,EAAE,IAAI,EAAE,CAAC;aAC/B;YACD,OAAO;gBACL,cAAc;aACf,CAAC;QACJ,CAAC;KACF,CAAC;AACJ,CAAC","sourcesContent":["// Copyright (c) Microsoft Corporation.\n// Licensed under the MIT license.\n\nimport { PipelineResponse } from \"..\";\nimport { parseHeaderValueAsNumber } from \"../util/helpers\";\nimport { RetryStrategy } from \"./retryStrategy\";\n\n/**\n * The header that comes back from services representing\n * the amount of time (minimum) to wait to retry (in seconds or timestamp after which we can retry).\n */\nconst RetryAfterHeader = \"Retry-After\";\n/**\n * The headers that come back from services representing\n * the amount of time (minimum) to wait to retry.\n *\n * \"retry-after-ms\", \"x-ms-retry-after-ms\" : milliseconds\n * \"Retry-After\" : seconds or timestamp\n */\nconst AllRetryAfterHeaders: string[] = [\"retry-after-ms\", \"x-ms-retry-after-ms\", RetryAfterHeader];\n\n/**\n * A response is a throttling retry response if it has a throttling status code (429 or 503),\n * as long as one of the [ \"Retry-After\" or \"retry-after-ms\" or \"x-ms-retry-after-ms\" ] headers has a valid value.\n *\n * Returns the `retryAfterInMs` value if the response is a throttling retry response.\n * If not throttling retry response, returns `undefined`.\n *\n * @internal\n */\nfunction getRetryAfterInMs(response?: PipelineResponse): number | undefined {\n  if (!(response && [429, 503].includes(response.status))) return undefined;\n  try {\n    // Headers: \"retry-after-ms\", \"x-ms-retry-after-ms\", \"Retry-After\"\n    for (const header of AllRetryAfterHeaders) {\n      const retryAfterValue = parseHeaderValueAsNumber(response, header);\n      if (retryAfterValue === 0 || retryAfterValue) {\n        // \"Retry-After\" header ==> seconds\n        // \"retry-after-ms\", \"x-ms-retry-after-ms\" headers ==> milli-seconds\n        const multiplyingFactor = header === RetryAfterHeader ? 1000 : 1;\n        return retryAfterValue * multiplyingFactor; // in milli-seconds\n      }\n    }\n\n    // RetryAfterHeader (\"Retry-After\") has a special case where it might be formatted as a date instead of a number of seconds\n    const retryAfterHeader = response.headers.get(RetryAfterHeader);\n    if (!retryAfterHeader) return;\n\n    const date = Date.parse(retryAfterHeader);\n    const diff = date - Date.now();\n    // negative diff would mean a date in the past, so retry asap with 0 milliseconds\n    return Number.isFinite(diff) ? Math.max(0, diff) : undefined;\n  } catch (e: any) {\n    return undefined;\n  }\n}\n\n/**\n * A response is a retry response if it has a throttling status code (429 or 503),\n * as long as one of the [ \"Retry-After\" or \"retry-after-ms\" or \"x-ms-retry-after-ms\" ] headers has a valid value.\n */\nexport function isThrottlingRetryResponse(response?: PipelineResponse): boolean {\n  return Number.isFinite(getRetryAfterInMs(response));\n}\n\nexport function throttlingRetryStrategy(): RetryStrategy {\n  return {\n    name: \"throttlingRetryStrategy\",\n    retry({ response }) {\n      const retryAfterInMs = getRetryAfterInMs(response);\n      if (!Number.isFinite(retryAfterInMs)) {\n        return { skipStrategy: true };\n      }\n      return {\n        retryAfterInMs,\n      };\n    },\n  };\n}\n"]}

package/dist-esm/src/tracing/instrumenter.js

@@ -0,0 +1,61 @@
+// Copyright (c) Microsoft Corporation.
+// Licensed under the MIT license.
+import { createTracingContext } from "./tracingContext";
+export function createDefaultTracingSpan() {
+    return {
+        end: () => {
+            // noop
+        },
+        isRecording: () => false,
+        recordException: () => {
+            // noop
+        },
+        setAttribute: () => {
+            // noop
+        },
+        setStatus: () => {
+            // noop
+        },
+    };
+}
+export function createDefaultInstrumenter() {
+    return {
+        createRequestHeaders: () => {
+            return {};
+        },
+        parseTraceparentHeader: () => {
+            return undefined;
+        },
+        startSpan: (_name, spanOptions) => {
+            return {
+                span: createDefaultTracingSpan(),
+                tracingContext: createTracingContext({ parentContext: spanOptions.tracingContext }),
+            };
+        },
+        withContext(_context, callback, ...callbackArgs) {
+            return callback(...callbackArgs);
+        },
+    };
+}
+/** @internal */
+let instrumenterImplementation;
+/**
+ * Extends the SDK with support for a given instrumenter implementation.
+ *
+ * @param instrumenter - The instrumenter implementation to use.
+ */
+export function useInstrumenter(instrumenter) {
+    instrumenterImplementation = instrumenter;
+}
+/**
+ * Gets the currently set instrumenter, a No-Op instrumenter by default.
+ *
+ * @returns The currently set instrumenter
+ */
+export function getInstrumenter() {
+    if (!instrumenterImplementation) {
+        instrumenterImplementation = createDefaultInstrumenter();
+    }
+    return instrumenterImplementation;
+}
+//# sourceMappingURL=instrumenter.js.map

package/dist-esm/src/tracing/instrumenter.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"instrumenter.js","sourceRoot":"","sources":["../../../src/tracing/instrumenter.ts"],"names":[],"mappings":"AAAA,uCAAuC;AACvC,kCAAkC;AAGlC,OAAO,EAAE,oBAAoB,EAAE,MAAM,kBAAkB,CAAC;AAExD,MAAM,UAAU,wBAAwB;IACtC,OAAO;QACL,GAAG,EAAE,GAAG,EAAE;YACR,OAAO;QACT,CAAC;QACD,WAAW,EAAE,GAAG,EAAE,CAAC,KAAK;QACxB,eAAe,EAAE,GAAG,EAAE;YACpB,OAAO;QACT,CAAC;QACD,YAAY,EAAE,GAAG,EAAE;YACjB,OAAO;QACT,CAAC;QACD,SAAS,EAAE,GAAG,EAAE;YACd,OAAO;QACT,CAAC;KACF,CAAC;AACJ,CAAC;AAED,MAAM,UAAU,yBAAyB;IACvC,OAAO;QACL,oBAAoB,EAAE,GAA2B,EAAE;YACjD,OAAO,EAAE,CAAC;QACZ,CAAC;QACD,sBAAsB,EAAE,GAA+B,EAAE;YACvD,OAAO,SAAS,CAAC;QACnB,CAAC;QACD,SAAS,EAAE,CACT,KAAa,EACb,WAAoC,EACmB,EAAE;YACzD,OAAO;gBACL,IAAI,EAAE,wBAAwB,EAAE;gBAChC,cAAc,EAAE,oBAAoB,CAAC,EAAE,aAAa,EAAE,WAAW,CAAC,cAAc,EAAE,CAAC;aACpF,CAAC;QACJ,CAAC;QACD,WAAW,CAIT,QAAwB,EACxB,QAAkB,EAClB,GAAG,YAA0B;YAE7B,OAAO,QAAQ,CAAC,GAAG,YAAY,CAAC,CAAC;QACnC,CAAC;KACF,CAAC;AACJ,CAAC;AAED,gBAAgB;AAChB,IAAI,0BAAoD,CAAC;AAEzD;;;;GAIG;AACH,MAAM,UAAU,eAAe,CAAC,YAA0B;IACxD,0BAA0B,GAAG,YAAY,CAAC;AAC5C,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,eAAe;IAC7B,IAAI,CAAC,0BAA0B,EAAE;QAC/B,0BAA0B,GAAG,yBAAyB,EAAE,CAAC;KAC1D;IACD,OAAO,0BAA0B,CAAC;AACpC,CAAC","sourcesContent":["// Copyright (c) Microsoft Corporation.\n// Licensed under the MIT license.\n\nimport { Instrumenter, InstrumenterSpanOptions, TracingContext, TracingSpan } from \"./interfaces\";\nimport { createTracingContext } from \"./tracingContext\";\n\nexport function createDefaultTracingSpan(): TracingSpan {\n  return {\n    end: () => {\n      // noop\n    },\n    isRecording: () => false,\n    recordException: () => {\n      // noop\n    },\n    setAttribute: () => {\n      // noop\n    },\n    setStatus: () => {\n      // noop\n    },\n  };\n}\n\nexport function createDefaultInstrumenter(): Instrumenter {\n  return {\n    createRequestHeaders: (): Record<string, string> => {\n      return {};\n    },\n    parseTraceparentHeader: (): TracingContext | undefined => {\n      return undefined;\n    },\n    startSpan: (\n      _name: string,\n      spanOptions: InstrumenterSpanOptions\n    ): { span: TracingSpan; tracingContext: TracingContext } => {\n      return {\n        span: createDefaultTracingSpan(),\n        tracingContext: createTracingContext({ parentContext: spanOptions.tracingContext }),\n      };\n    },\n    withContext<\n      CallbackArgs extends unknown[],\n      Callback extends (...args: CallbackArgs) => ReturnType<Callback>\n    >(\n      _context: TracingContext,\n      callback: Callback,\n      ...callbackArgs: CallbackArgs\n    ): ReturnType<Callback> {\n      return callback(...callbackArgs);\n    },\n  };\n}\n\n/** @internal */\nlet instrumenterImplementation: Instrumenter | undefined;\n\n/**\n * Extends the SDK with support for a given instrumenter implementation.\n *\n * @param instrumenter - The instrumenter implementation to use.\n */\nexport function useInstrumenter(instrumenter: Instrumenter): void {\n  instrumenterImplementation = instrumenter;\n}\n\n/**\n * Gets the currently set instrumenter, a No-Op instrumenter by default.\n *\n * @returns The currently set instrumenter\n */\nexport function getInstrumenter(): Instrumenter {\n  if (!instrumenterImplementation) {\n    instrumenterImplementation = createDefaultInstrumenter();\n  }\n  return instrumenterImplementation;\n}\n"]}

package/dist-esm/src/tracing/interfaces.js

@@ -0,0 +1,4 @@
+// Copyright (c) Microsoft Corporation.
+// Licensed under the MIT license.
+export {};
+//# sourceMappingURL=interfaces.js.map

package/dist-esm/src/tracing/interfaces.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"interfaces.js","sourceRoot":"","sources":["../../../src/tracing/interfaces.ts"],"names":[],"mappings":"AAAA,uCAAuC;AACvC,kCAAkC","sourcesContent":["// Copyright (c) Microsoft Corporation.\n// Licensed under the MIT license.\n\n/**\n * A narrower version of TypeScript 4.5's Awaited type which Recursively\n * unwraps the \"awaited type\", emulating the behavior of `await`.\n */\nexport type Resolved<T> = T extends { then(onfulfilled: infer F): any } // `await` only unwraps object types with a callable `then`. Non-object types are not unwrapped\n  ? F extends (value: infer V) => any // if the argument to `then` is callable, extracts the first argument\n    ? Resolved<V> // recursively unwrap the value\n    : never // the argument to `then` was not callable\n  : T; // non-object or non-thenable\n\n/**\n * Represents a client that can integrate with the currently configured {@link Instrumenter}.\n *\n * Create an instance using {@link createTracingClient}.\n */\nexport interface TracingClient {\n  /**\n   * Wraps a callback in a tracing span, calls the callback, and closes the span.\n   *\n   * This is the primary interface for using Tracing and will handle error recording as well as setting the status on the span.\n   *\n   * Both synchronous and asynchronous functions will be awaited in order to reflect the result of the callback on the span.\n   *\n   * Example:\n   *\n   * ```ts\n   * const myOperationResult = await tracingClient.withSpan(\"myClassName.myOperationName\", options, (updatedOptions) => myOperation(updatedOptions));\n   * ```\n   * @param name - The name of the span. By convention this should be `${className}.${methodName}`.\n   * @param operationOptions - The original options passed to the method. The callback will receive these options with the newly created {@link TracingContext}.\n   * @param callback - The callback to be invoked with the updated options and newly created {@link TracingSpan}.\n   */\n  withSpan<\n    Options extends { tracingOptions?: OperationTracingOptions },\n    Callback extends (\n      updatedOptions: Options,\n      span: Omit<TracingSpan, \"end\">\n    ) => ReturnType<Callback>\n  >(\n    name: string,\n    operationOptions: Options,\n    callback: Callback,\n    spanOptions?: TracingSpanOptions\n  ): Promise<Resolved<ReturnType<Callback>>>;\n  /**\n   * Starts a given span but does not set it as the active span.\n   *\n   * You must end the span using {@link TracingSpan.end}.\n   *\n   * Most of the time you will want to use {@link withSpan} instead.\n   *\n   * @param name - The name of the span. By convention this should be `${className}.${methodName}`.\n   * @param operationOptions - The original operation options.\n   * @param spanOptions - The options to use when creating the span.\n   *\n   * @returns A {@link TracingSpan} and the updated operation options.\n   */\n  startSpan<Options extends { tracingOptions?: OperationTracingOptions }>(\n    name: string,\n    operationOptions?: Options,\n    spanOptions?: TracingSpanOptions\n  ): {\n    span: TracingSpan;\n    updatedOptions: OptionsWithTracingContext<Options>;\n  };\n  /**\n   * Wraps a callback with an active context and calls the callback.\n   * Depending on the implementation, this may set the globally available active context.\n   *\n   * Useful when you want to leave the boundaries of the SDK (make a request or callback to user code) and are unable to use the {@link withSpan} API.\n   *\n   * @param context - The {@link TracingContext} to use as the active context in the scope of the callback.\n   * @param callback - The callback to be invoked with the given context set as the globally active context.\n   * @param callbackArgs - The callback arguments.\n   */\n  withContext<\n    CallbackArgs extends unknown[],\n    Callback extends (...args: CallbackArgs) => ReturnType<Callback>\n  >(\n    context: TracingContext,\n    callback: Callback,\n    ...callbackArgs: CallbackArgs\n  ): ReturnType<Callback>;\n\n  /**\n   * Parses a traceparent header value into a {@link TracingSpanContext}.\n   *\n   * @param traceparentHeader - The traceparent header to parse.\n   * @returns An implementation-specific identifier for the span.\n   */\n  parseTraceparentHeader(traceparentHeader: string): TracingContext | undefined;\n\n  /**\n   * Creates a set of request headers to propagate tracing information to a backend.\n   *\n   * @param tracingContext - The context containing the span to propagate.\n   * @returns The set of headers to add to a request.\n   */\n  createRequestHeaders(tracingContext?: TracingContext): Record<string, string>;\n}\n\n/**\n * Options that can be passed to {@link createTracingClient}\n */\nexport interface TracingClientOptions {\n  /** The value of the az.namespace tracing attribute on newly created spans. */\n  namespace: string;\n  /** The name of the package invoking this trace. */\n  packageName: string;\n  /** An optional version of the package invoking this trace. */\n  packageVersion?: string;\n}\n\n/** The kind of span. */\nexport type TracingSpanKind = \"client\" | \"server\" | \"producer\" | \"consumer\" | \"internal\";\n\n/** Options used to configure the newly created span. */\nexport interface TracingSpanOptions {\n  /** The kind of span. Implementations should default this to \"client\". */\n  spanKind?: TracingSpanKind;\n  /** A collection of {@link TracingSpanLink} to link to this span. */\n  spanLinks?: TracingSpanLink[];\n  /** Initial set of attributes to set on a span. */\n  spanAttributes?: { [key: string]: unknown };\n}\n\n/** A pointer from the current {@link TracingSpan} to another span in the same or a different trace. */\nexport interface TracingSpanLink {\n  /** The {@link TracingContext} containing the span context to link to. */\n  tracingContext: TracingContext;\n  /** A set of attributes on the link. */\n  attributes?: { [key: string]: unknown };\n}\n\n/**\n * Represents an implementation agnostic instrumenter.\n */\nexport interface Instrumenter {\n  /**\n   * Creates a new {@link TracingSpan} with the given name and options and sets it on a new context.\n   * @param name - The name of the span. By convention this should be `${className}.${methodName}`.\n   * @param spanOptions - The options to use when creating the span.\n   *\n   * @returns A {@link TracingSpan} that can be used to end the span, and the context this span has been set on.\n   */\n  startSpan(\n    name: string,\n    spanOptions: InstrumenterSpanOptions\n  ): { span: TracingSpan; tracingContext: TracingContext };\n  /**\n   * Wraps a callback with an active context and calls the callback.\n   * Depending on the implementation, this may set the globally available active context.\n   *\n   * @param context - The {@link TracingContext} to use as the active context in the scope of the callback.\n   * @param callback - The callback to be invoked with the given context set as the globally active context.\n   * @param callbackArgs - The callback arguments.\n   */\n  withContext<\n    CallbackArgs extends unknown[],\n    Callback extends (...args: CallbackArgs) => ReturnType<Callback>\n  >(\n    context: TracingContext,\n    callback: Callback,\n    ...callbackArgs: CallbackArgs\n  ): ReturnType<Callback>;\n\n  /**\n   * Provides an implementation-specific method to parse a {@link https://www.w3.org/TR/trace-context/#traceparent-header}\n   * into a {@link TracingSpanContext} which can be used to link non-parented spans together.\n   */\n  parseTraceparentHeader(traceparentHeader: string): TracingContext | undefined;\n  /**\n   * Provides an implementation-specific method to serialize a {@link TracingSpan} to a set of headers.\n   * @param tracingContext - The context containing the span to serialize.\n   */\n  createRequestHeaders(tracingContext?: TracingContext): Record<string, string>;\n}\n\n/**\n * Options passed to {@link Instrumenter.startSpan} as a superset of {@link TracingSpanOptions}.\n */\nexport interface InstrumenterSpanOptions extends TracingSpanOptions {\n  /** The name of the package invoking this trace. */\n  packageName: string;\n  /** The version of the package invoking this trace. */\n  packageVersion?: string;\n  /** The current tracing context. Defaults to an implementation-specific \"active\" context. */\n  tracingContext?: TracingContext;\n}\n\n/**\n * Status representing a successful operation that can be sent to {@link TracingSpan.setStatus}\n */\nexport type SpanStatusSuccess = { status: \"success\" };\n\n/**\n * Status representing an error that can be sent to {@link TracingSpan.setStatus}\n */\nexport type SpanStatusError = { status: \"error\"; error?: Error | string };\n\n/**\n * Represents the statuses that can be passed to {@link TracingSpan.setStatus}.\n *\n * By default, all spans will be created with status \"unset\".\n */\nexport type SpanStatus = SpanStatusSuccess | SpanStatusError;\n\n/**\n * Represents an implementation agnostic tracing span.\n */\nexport interface TracingSpan {\n  /**\n   * Sets the status of the span. When an error is provided, it will be recorded on the span as well.\n   *\n   * @param status - The {@link SpanStatus} to set on the span.\n   */\n  setStatus(status: SpanStatus): void;\n\n  /**\n   * Sets a given attribute on a span.\n   *\n   * @param name - The attribute's name.\n   * @param value - The attribute's value to set. May be any non-nullish value.\n   */\n  setAttribute(name: string, value: unknown): void;\n\n  /**\n   * Ends the span.\n   */\n  end(): void;\n\n  /**\n   * Records an exception on a {@link TracingSpan} without modifying its status.\n   *\n   * When recording an unhandled exception that should fail the span, please use {@link TracingSpan.setStatus} instead.\n   *\n   * @param exception - The exception to record on the span.\n   *\n   */\n  recordException(exception: Error | string): void;\n\n  /**\n   * Returns true if this {@link TracingSpan} is recording information.\n   *\n   * Depending on the span implementation, this may return false if the span is not being sampled.\n   */\n  isRecording(): boolean;\n}\n\n/** An immutable context bag of tracing values for the current operation. */\nexport interface TracingContext {\n  /**\n   * Sets a given object on a context.\n   * @param key - The key of the given context value.\n   * @param value - The value to set on the context.\n   *\n   * @returns - A new context with the given value set.\n   */\n  setValue(key: symbol, value: unknown): TracingContext;\n  /**\n   * Gets an object from the context if it exists.\n   * @param key - The key of the given context value.\n   *\n   * @returns - The value of the given context value if it exists, otherwise `undefined`.\n   */\n  getValue(key: symbol): unknown;\n  /**\n   * Deletes an object from the context if it exists.\n   * @param key - The key of the given context value to delete.\n   */\n  deleteValue(key: symbol): TracingContext;\n}\n\n/**\n * Tracing options to set on an operation.\n */\nexport interface OperationTracingOptions {\n  /** The context to use for created Tracing Spans. */\n  tracingContext?: TracingContext;\n}\n\n/**\n * A utility type for when we know a TracingContext has been set\n * as part of an operation's options.\n */\nexport type OptionsWithTracingContext<\n  Options extends { tracingOptions?: OperationTracingOptions }\n> = Options & {\n  tracingOptions: {\n    tracingContext: TracingContext;\n  };\n};\n"]}