or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

authentication.mderror-handling.mdhttp-client.mdindex.mdnetwork-transport.mdobservability.mdpipeline.mdrequest-processing.mdretry-policies.mdutilities.md
tile.json

index.mddocs/

Azure Core REST Pipeline

Azure Core REST Pipeline provides the core HTTP pipeline infrastructure for Azure SDK JavaScript libraries, enabling them to work consistently across both Node.js and browser environments. It implements a flexible middleware-style architecture using pipeline policies that can intercept, modify, and handle HTTP requests and responses in a predictable order.

Package Information

  • Package Name: @azure/core-rest-pipeline
  • Package Type: npm
  • Language: TypeScript
  • Installation: npm install @azure/core-rest-pipeline

Core Imports

import {
  createPipelineFromOptions,
  createDefaultHttpClient,
  createPipelineRequest,
  createHttpHeaders,
  type Pipeline,
  type PipelineRequest,
  type PipelineResponse,
  type HttpClient
} from "@azure/core-rest-pipeline";

For CommonJS:

const {
  createPipelineFromOptions,
  createDefaultHttpClient,
  createPipelineRequest,
  createHttpHeaders
} = require("@azure/core-rest-pipeline");

Basic Usage

import {
  createPipelineFromOptions,
  createDefaultHttpClient,
  createPipelineRequest,
  userAgentPolicy,
  logPolicy
} from "@azure/core-rest-pipeline";

// Create a pipeline with standard policies
const pipeline = createPipelineFromOptions({
  userAgentOptions: { userAgentPrefix: "MySDK/1.0.0" },
  retryOptions: { maxRetries: 3 }
});

// Add custom policies
pipeline.addPolicy(logPolicy({ logger: console }));

// Create HTTP client and make request
const client = createDefaultHttpClient();
const request = createPipelineRequest({
  url: "https://api.example.com/data",
  method: "GET"
});

// Send request through pipeline
const response = await pipeline.sendRequest(client, request);
console.log(response.status, response.bodyAsText);

Architecture

Azure Core REST Pipeline is built around several key components:

  • Pipeline System: Core pipeline that executes policies in phases (Serialize → Policies → Deserialize → Retry → Sign)
  • Policy Framework: Middleware-style policies for authentication, retry logic, logging, and request/response transformation
  • HTTP Abstraction: Isomorphic HTTP client that works consistently across Node.js and browser environments
  • Request/Response Objects: Standardized request and response interfaces with rich metadata support
  • Error Handling: Comprehensive error types with request/response context and retry information

Capabilities

Pipeline Management

Core pipeline creation, configuration, and policy management for building HTTP request processing pipelines.

function createPipelineFromOptions(options: InternalPipelineOptions): Pipeline;
function createEmptyPipeline(): Pipeline;

interface Pipeline {
  addPolicy(policy: PipelinePolicy, options?: AddPolicyOptions): void;
  removePolicy(options: { name?: string; phase?: PipelinePhase }): PipelinePolicy[];
  sendRequest(httpClient: HttpClient, request: PipelineRequest): Promise<PipelineResponse>;
  getOrderedPolicies(): PipelinePolicy[];
  clone(): Pipeline;
}

Pipeline Management

HTTP Client and Request/Response

HTTP client abstraction and request/response object creation for isomorphic HTTP operations.

function createDefaultHttpClient(): HttpClient;
function createPipelineRequest(options: PipelineRequestOptions): PipelineRequest; 
function createHttpHeaders(rawHeaders?: RawHttpHeadersInput): HttpHeaders;

interface HttpClient {
  sendRequest: SendRequest;
}

interface PipelineRequest {
  url: string;
  method: HttpMethods;
  headers: HttpHeaders;
  timeout: number;
  body?: RequestBodyType;
  // ... additional properties
}

HTTP Client and Requests

Authentication Policies

Bearer token authentication and auxiliary authentication header policies for Azure services.

function bearerTokenAuthenticationPolicy(
  options: BearerTokenAuthenticationPolicyOptions
): PipelinePolicy;

function auxiliaryAuthenticationHeaderPolicy(
  options: AuxiliaryAuthenticationHeaderPolicyOptions  
): PipelinePolicy;

interface BearerTokenAuthenticationPolicyOptions {
  credential: TokenCredential;
  scopes: string[];
  challengeCallbacks?: ChallengeCallbacks;
}

Authentication Policies

Retry Policies

Comprehensive retry mechanisms including exponential backoff, system error retry, and throttling retry policies.

function exponentialRetryPolicy(options?: ExponentialRetryPolicyOptions): PipelinePolicy;
function defaultRetryPolicy(options?: DefaultRetryPolicyOptions): PipelinePolicy;
function systemErrorRetryPolicy(options?: SystemErrorRetryPolicyOptions): PipelinePolicy;
function throttlingRetryPolicy(options?: ThrottlingRetryPolicyOptions): PipelinePolicy;

interface PipelineRetryOptions {
  maxRetries?: number;
  retryDelayInMs?: number;
  maxRetryDelayInMs?: number;
}

Retry Policies

Request Processing Policies

Policies for processing different request body types including multipart, form data, and newline-delimited JSON.

function multipartPolicy(): PipelinePolicy;
function formDataPolicy(): PipelinePolicy;
function ndJsonPolicy(): PipelinePolicy;
function decompressResponsePolicy(): PipelinePolicy;

interface MultipartRequestBody {
  parts: BodyPart[];
  boundary?: string;
}

Request Processing

Network and Transport

Network-level policies for proxy configuration, TLS settings, and HTTP agent management (Node.js specific).

function proxyPolicy(proxySettings?: ProxySettings): PipelinePolicy;
function agentPolicy(agent: Agent): PipelinePolicy;
function tlsPolicy(tlsSettings: TlsSettings): PipelinePolicy;
function redirectPolicy(options?: RedirectPolicyOptions): PipelinePolicy;

interface ProxySettings {
  host: string;
  port: number;
  username?: string;
  password?: string;
}

Network and Transport

Observability

Logging, tracing, and user agent policies for monitoring and debugging HTTP requests.

function logPolicy(options?: LogPolicyOptions): PipelinePolicy;
function tracingPolicy(options?: TracingPolicyOptions): PipelinePolicy;
function userAgentPolicy(options?: UserAgentPolicyOptions): PipelinePolicy;
function setClientRequestIdPolicy(): PipelinePolicy;

interface LogPolicyOptions {
  logger?: AzureLogger;
  allowedHeaders?: string[];
  allowedQueryParameters?: string[];
}

Observability

Error Handling

Comprehensive error handling with REST-specific error types and context information.

class RestError extends Error {
  code?: string;
  statusCode?: number;
  request?: PipelineRequest;
  response?: PipelineResponse;
  
  static readonly REQUEST_SEND_ERROR: string;
  static readonly PARSE_ERROR: string;
}

function isRestError(error: unknown): error is RestError;

Error Handling

Utility Functions

Helper functions for file creation and other common operations.

function createFile(
  stream: ReadableStream<Uint8Array> | NodeJS.ReadableStream,
  name: string,
  options?: CreateFileOptions
): File;

function createFileFromStream(
  stream: ReadableStream<Uint8Array> | NodeJS.ReadableStream,
  name: string,
  options?: CreateFileFromStreamOptions
): Promise<File>;

Utilities

Core Types

type HttpMethods = "GET" | "PUT" | "POST" | "DELETE" | "PATCH" | "HEAD" | "OPTIONS" | "TRACE";

type SendRequest = (request: PipelineRequest) => Promise<PipelineResponse>;

type PipelinePhase = "Deserialize" | "Serialize" | "Retry" | "Sign";

interface PipelinePolicy {
  name: string;
  sendRequest(request: PipelineRequest, next: SendRequest): Promise<PipelineResponse>;
}

interface AddPolicyOptions {
  beforePolicies?: string[];
  afterPolicies?: string[];
  afterPhase?: PipelinePhase;
  phase?: PipelinePhase;
}

type RequestBodyType =
  | NodeJS.ReadableStream
  | (() => NodeJS.ReadableStream)
  | ReadableStream<Uint8Array>
  | (() => ReadableStream<Uint8Array>)
  | Blob
  | ArrayBuffer
  | ArrayBufferView
  | FormData
  | string
  | null;

interface HttpHeaders extends Iterable<[string, string]> {
  get(name: string): string | undefined;
  has(name: string): boolean;
  set(name: string, value: string | number | boolean): void;
  delete(name: string): void;
  toJSON(options?: { preserveCase?: boolean }): RawHttpHeaders;
}

type RawHttpHeaders = { [headerName: string]: string };
type RawHttpHeadersInput = Record<string, string | number | boolean>;

interface TransferProgressEvent {
  loadedBytes: number;
}