HTTP Client and Requests

/**
 * Creates the default HttpClient implementation for the current environment
 * Uses fetch API in browsers and Node.js http/https modules in Node.js
 * @returns HttpClient instance
 */
function createDefaultHttpClient(): HttpClient;

/**
 * The required interface for a client that makes HTTP requests
 * on behalf of a pipeline
 */
interface HttpClient {
  /**
   * The method that makes the request and returns a response
   */
  sendRequest: SendRequest;
}

/**
 * A simple interface for making a pipeline request and receiving a response
 */
type SendRequest = (request: PipelineRequest) => Promise<PipelineResponse>;

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

// Create HTTP client
const client = createDefaultHttpClient();

// Create and send request
const request = createPipelineRequest({
  url: "https://api.example.com/users",
  method: "GET"
});

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

/**
 * Creates a new PipelineRequest with the given options
 * @param options - Options for configuring the request
 * @returns PipelineRequest instance
 */
function createPipelineRequest(options: PipelineRequestOptions): PipelineRequest;

interface PipelineRequestOptions {
  /**
   * The URL to make the request to
   */
  url: string;
  
  /**
   * The HTTP method to use. Defaults to "GET"
   */
  method?: HttpMethods;
  
  /**
   * The HTTP headers to use when making the request
   */
  headers?: RawHttpHeadersInput;
  
  /**
   * The request timeout in milliseconds. Defaults to 0 (no timeout)
   */
  timeout?: number;
  
  /**
   * Whether to send cookies with cross-origin requests. Defaults to false
   */
  withCredentials?: boolean;
  
  /**
   * The HTTP body content
   */
  body?: RequestBodyType;
  
  /**
   * Used to abort the request later
   */
  abortSignal?: AbortSignalLike;
  
  /**
   * Allow insecure HTTP connections. Defaults to false
   */
  allowInsecureConnection?: boolean;
  
  /**
   * Proxy configuration
   */
  proxySettings?: ProxySettings;
  
  /**
   * Disable connection reuse
   */
  disableKeepAlive?: boolean;
  
  /**
   * Status codes to treat as streams
   */
  streamResponseStatusCodes?: Set<number>;
  
  /**
   * Callback for upload progress
   */
  onUploadProgress?: (progress: TransferProgressEvent) => void;
  
  /**
   * Callback for download progress  
   */
  onDownloadProgress?: (progress: TransferProgressEvent) => void;
  
  /**
   * Tracing options
   */
  tracingOptions?: OperationTracingOptions;
  
  /**
   * Node.js HTTP agent (Node.js only)
   */
  agent?: Agent;
  
  /**
   * Enable browser streams (browser only)
   */
  enableBrowserStreams?: boolean;
  
  /**
   * TLS settings
   */
  tlsSettings?: TlsSettings;
  
  /**
   * Additional request options to override defaults
   */
  requestOverrides?: Record<string, unknown>;
}

import { createPipelineRequest, type TransferProgressEvent } from "@azure/core-rest-pipeline";

// Basic GET request
const getRequest = createPipelineRequest({
  url: "https://api.example.com/data",
  method: "GET",
  headers: { "Accept": "application/json" }
});

// POST request with body and progress tracking
const postRequest = createPipelineRequest({
  url: "https://api.example.com/upload",
  method: "POST",
  body: JSON.stringify({ name: "example" }),
  headers: { "Content-Type": "application/json" },
  timeout: 30000,
  onUploadProgress: (progress: TransferProgressEvent) => {
    console.log(`Uploaded: ${progress.loadedBytes} bytes`);
  }
});

// Request with abort signal
const controller = new AbortController();
const abortableRequest = createPipelineRequest({
  url: "https://api.example.com/long-running",
  method: "GET",
  abortSignal: controller.signal
});

// Abort after 5 seconds
setTimeout(() => controller.abort(), 5000);

/**
 * Metadata about a request being made by the pipeline
 */
interface PipelineRequest {
  /**
   * The URL to make the request to
   */
  url: string;

  /**
   * The HTTP method to use when making the request
   */
  method: HttpMethods;

  /**
   * The HTTP headers to use when making the request
   */
  headers: HttpHeaders;

  /**
   * The number of milliseconds a request can take before automatically being terminated.
   * If the request is terminated, an `AbortError` is thrown.
   * Defaults to 0, which disables the timeout.
   */
  timeout: number;

  /**
   * Indicates whether the user agent should send cookies from the other domain in the case of cross-origin requests.
   * Defaults to false.
   */
  withCredentials: boolean;

  /**
   * A unique identifier for the request. Used for logging and tracing.
   */
  requestId: string;

  /**
   * The HTTP body content (if any)
   */
  body?: RequestBodyType;

  /**
   * Body for a multipart request
   */
  multipartBody?: MultipartRequestBody;

  /**
   * To simulate a browser form post
   */
  formData?: FormDataMap;

  /**
   * A list of response status codes whose corresponding PipelineResponse body should be treated as a stream
   */
  streamResponseStatusCodes?: Set<number>;

  /**
   * Proxy configuration
   */
  proxySettings?: ProxySettings;

  /**
   * If the connection should not be reused
   */
  disableKeepAlive?: boolean;

  /**
   * Used to abort the request later
   */
  abortSignal?: AbortSignalLike;

  /**
   * Tracing options to use for any created Spans
   */
  tracingOptions?: OperationTracingOptions;

  /**
   * Callback which fires upon upload progress
   */
  onUploadProgress?: (progress: TransferProgressEvent) => void;

  /**
   * Callback which fires upon download progress
   */
  onDownloadProgress?: (progress: TransferProgressEvent) => void;

  /**
   * Set to true if the request is sent over HTTP instead of HTTPS
   */
  allowInsecureConnection?: boolean;

  /**
   * Node.js only - A custom http.Agent/https.Agent
   */
  agent?: Agent;

  /**
   * Browser only - Enable browser Streams
   */
  enableBrowserStreams?: boolean;

  /**
   * Settings for configuring TLS authentication
   */
  tlsSettings?: TlsSettings;

  /**
   * Additional options to override existing ones or provide request properties that are not declared
   */
  requestOverrides?: Record<string, unknown>;
}

/**
 * Metadata about a response received by the pipeline
 */
interface PipelineResponse {
  /**
   * The request that generated this response
   */
  request: PipelineRequest;
  
  /**
   * The HTTP status code of the response
   */
  status: number;
  
  /**
   * The HTTP response headers
   */
  headers: HttpHeaders;

  /**
   * The response body as text (string format)
   */
  bodyAsText?: string | null;

  /**
   * Browser only - The response body as a browser Blob
   */
  blobBody?: Promise<Blob>;

  /**
   * Browser only - The response body as a browser ReadableStream
   */
  browserStreamBody?: ReadableStream<Uint8Array>;

  /**
   * Node.js only - The response body as a node.js Readable stream
   */
  readableStreamBody?: NodeJS.ReadableStream;
}

import { type PipelineResponse } from "@azure/core-rest-pipeline";

// Handle different response body types
async function processResponse(response: PipelineResponse) {
  console.log(`Status: ${response.status}`);
  console.log(`Headers:`, response.headers.toJSON());
  
  // Text response
  if (response.bodyAsText) {
    console.log("Text body:", response.bodyAsText);
  }
  
  // Browser blob (browser only)
  if (response.blobBody && typeof window !== "undefined") {
    const blob = await response.blobBody;
    console.log("Blob size:", blob.size);
  }
  
  // Node.js stream (Node.js only)
  if (response.readableStreamBody && typeof process !== "undefined") {
    response.readableStreamBody.on("data", (chunk) => {
      console.log("Stream chunk:", chunk.length);
    });
  }
}

/**
 * Creates a new HttpHeaders collection
 * @param rawHeaders - Initial headers as key-value pairs
 * @returns HttpHeaders instance
 */
function createHttpHeaders(rawHeaders?: RawHttpHeadersInput): HttpHeaders;

/**
 * Represents a set of HTTP headers on a request/response.
 * Header names are treated as case insensitive.
 */
interface HttpHeaders extends Iterable<[string, string]> {
  /**
   * Returns the value of a specific header or undefined if not set
   * @param name - The name of the header to retrieve
   */
  get(name: string): string | undefined;
  
  /**
   * Returns true if the specified header exists
   * @param name - The name of the header to check
   */
  has(name: string): boolean;
  
  /**
   * Sets a specific header with a given value
   * @param name - The name of the header to set
   * @param value - The value to use for the header
   */
  set(name: string, value: string | number | boolean): void;
  
  /**
   * Removes a specific header from the collection
   * @param name - The name of the header to delete
   */
  delete(name: string): void;
  
  /**
   * Accesses a raw JS object that acts as a simple map of header names to values
   */
  toJSON(options?: { preserveCase?: boolean }): RawHttpHeaders;
}

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

import { createHttpHeaders } from "@azure/core-rest-pipeline";

// Create headers from object
const headers = createHttpHeaders({
  "Content-Type": "application/json",
  "Authorization": "Bearer token123",
  "X-Custom-Header": 42
});

// Manipulate headers
headers.set("Accept", "application/json");
headers.delete("X-Custom-Header");

console.log(headers.get("content-type")); // "application/json" (case insensitive)
console.log(headers.has("Authorization")); // true

// Iterate over headers
for (const [name, value] of headers) {
  console.log(`${name}: ${value}`);
}

// Convert to plain object
const rawHeaders = headers.toJSON();
console.log(rawHeaders);

/**
 * Types of bodies supported on the request.
 * NodeJS.ReadableStream and () => NodeJS.ReadableStream is Node only.
 * Blob, ReadableStream<Uint8Array>, and () => ReadableStream<Uint8Array> are browser only.
 */
type RequestBodyType =
  | NodeJS.ReadableStream
  | (() => NodeJS.ReadableStream)
  | ReadableStream<Uint8Array>
  | (() => ReadableStream<Uint8Array>)
  | Blob
  | ArrayBuffer
  | ArrayBufferView
  | FormData
  | string
  | null;

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

interface TransferProgressEvent {
  loadedBytes: number;
}