HTTP Clients

/**
 * Basic HTTP/1.1 client for single connections to an origin
 * Supports request pipelining for improved performance
 */
class Client extends Dispatcher {
  constructor(url: string | URL, options?: Client.Options);
  
  /** Current pipelining factor (number of concurrent requests) */
  readonly pipelining: number;
  
  /** Whether the client is closed */
  readonly closed: boolean;
  
  /** Whether the client is destroyed */
  readonly destroyed: boolean;
  
  /** Client statistics */
  readonly stats: Client.SocketInfo;
}

interface Client.Options extends Dispatcher.DispatchOptions {
  /** The maximum number of requests to pipeline. Default: 1 */
  pipelining?: number;
  
  /** Timeout for each request in milliseconds */
  headersTimeout?: number;
  
  /** Timeout for request body in milliseconds */
  bodyTimeout?: number;
  
  /** Maximum number of concurrent requests */
  connections?: number;
  
  /** Keep-alive timeout in milliseconds */
  keepAliveTimeout?: number;
  
  /** Maximum keep-alive timeout in milliseconds */
  keepAliveMaxTimeout?: number;
  
  /** Keep-alive timeout threshold in milliseconds */
  keepAliveTimeoutThreshold?: number;
  
  /** TLS/SSL connection options */
  tls?: {
    ca?: string | Buffer | Array<string | Buffer>;
    cert?: string | Buffer;
    key?: string | Buffer;
    rejectUnauthorized?: boolean;
  };
  
  /** Custom socket connector function */
  connect?: buildConnector.connector;
}

interface Client.SocketInfo {
  connected: number;
  connecting: number;
  pending: number;
  queued: number;
  running: number;
  size: number;
}

import { Client } from "undici-types";

// Basic client
const client = new Client("https://api.example.com");

// Client with options
const client = new Client("https://api.example.com", {
  pipelining: 10,
  headersTimeout: 30000,
  bodyTimeout: 30000,
  keepAliveTimeout: 4000
});

// Make requests
const response = await client.request({
  path: "/users",
  method: "GET"
});

// Close client when done
await client.close();

/**
 * Connection pool managing multiple clients to a single origin
 * Automatically handles connection lifecycle and load distribution
 */
class Pool extends Dispatcher {
  constructor(url: string | URL, options?: Pool.Options);
  
  /** Whether the pool is closed */
  readonly closed: boolean;
  
  /** Whether the pool is destroyed */
  readonly destroyed: boolean;
  
  /** Pool statistics */
  readonly stats: Pool.PoolStats;
}

interface Pool.Options extends Client.Options {
  /** Maximum number of clients in the pool */
  connections?: number;
  
  /** Factory function for creating clients */
  factory?: (origin: URL, opts: object) => Dispatcher;
}

interface Pool.PoolStats {
  connected: number;
  free: number;
  pending: number;
  queued: number;
  running: number;
  size: number;
}

import { Pool } from "undici-types";

// Basic pool
const pool = new Pool("https://api.example.com");

// Pool with custom configuration
const pool = new Pool("https://api.example.com", {
  connections: 50,
  pipelining: 10,
  keepAliveTimeout: 60000
});

// High-throughput requests
const promises = Array.from({ length: 100 }, (_, i) =>
  pool.request({
    path: `/data/${i}`,
    method: "GET"
  })
);

const responses = await Promise.all(promises);

/**
 * HTTP agent managing multiple origin pools
 * Automatically routes requests to appropriate pools based on origin
 */
class Agent extends Dispatcher {
  constructor(options?: Agent.Options);
  
  /** Whether the agent is closed */
  readonly closed: boolean;
  
  /** Whether the agent is destroyed */
  readonly destroyed: boolean;
  
  /** Dispatch method for making requests */
  dispatch(options: Agent.DispatchOptions, handler: Dispatcher.DispatchHandler): boolean;
  
  /** Per-origin statistics */
  readonly stats: Record<string, Pool.PoolStats>;
}

interface Agent.Options extends Pool.Options {
  /** Factory function for creating pools */
  factory?: (origin: URL, opts: object) => Dispatcher;
  
  /** Maximum number of queued requests per origin */
  maxRedirections?: number;
}

interface Agent.DispatchOptions extends Dispatcher.DispatchOptions {
  /** Origin for the request (required) */
  origin?: string | URL;
}

import { Agent, setGlobalDispatcher } from "undici-types";

// Create and set global agent
const agent = new Agent({
  connections: 100,
  pipelining: 10
});
setGlobalDispatcher(agent);

// Agent automatically handles multiple origins
const [response1, response2] = await Promise.all([
  agent.request({
    origin: "https://api1.example.com",
    path: "/users",
    method: "GET"
  }),
  agent.request({
    origin: "https://api2.example.com", 
    path: "/posts",
    method: "GET"
  })
]);

/**
 * Load-balancing pool distributing requests across multiple upstreams
 * Provides high availability and load distribution
 */
class BalancedPool extends Dispatcher {
  constructor(url: string | URL | string[], options?: Pool.Options);
  
  /** Add an upstream server to the pool */
  addUpstream(upstream: string | URL): BalancedPool;
  
  /** Remove an upstream server from the pool */
  removeUpstream(upstream: string | URL): BalancedPool;
  
  /** Get list of upstream servers */
  upstreams: string[];
  
  /** Whether the pool is closed */
  readonly closed: boolean;
  
  /** Whether the pool is destroyed */
  readonly destroyed: boolean;
}

import { BalancedPool } from "undici-types";

// Create balanced pool with multiple upstreams
const pool = new BalancedPool([
  "https://server1.example.com",
  "https://server2.example.com",
  "https://server3.example.com"
]);

// Dynamically manage upstreams
pool.addUpstream("https://server4.example.com");
pool.removeUpstream("https://server1.example.com");

// Requests are automatically load balanced
const response = await pool.request({
  path: "/api/data",
  method: "GET"
});

/**
 * HTTP/2 cleartext client for unencrypted HTTP/2 connections
 * Supports HTTP/2 features like multiplexing and server push
 */
class H2CClient extends Client {
  constructor(url: string | URL, options?: H2CClient.Options);
}

interface H2CClient.Options extends Client.Options {
  /** HTTP/2 settings */
  settings?: {
    headerTableSize?: number;
    enablePush?: boolean;
    maxConcurrentStreams?: number;
    initialWindowSize?: number;
    maxFrameSize?: number;
    maxHeaderListSize?: number;
  };
}

import { H2CClient } from "undici-types";

// HTTP/2 cleartext client
const client = new H2CClient("http://http2.example.com", {
  settings: {
    enablePush: true,
    maxConcurrentStreams: 100
  }
});

// Use HTTP/2 multiplexing
const [response1, response2] = await Promise.all([
  client.request({ path: "/api/users", method: "GET" }),
  client.request({ path: "/api/posts", method: "GET" })
]);

interface Dispatcher.DispatchOptions {
  origin?: string | URL;
  path: string;
  method?: HttpMethod;
  body?: BodyInit;
  headers?: HeadersInit;
  query?: Record<string, any>;
  idempotent?: boolean;
  upgrade?: string;
  headersTimeout?: number;
  bodyTimeout?: number;
  reset?: boolean;
  throwOnError?: boolean;
  expectContinue?: boolean;
}

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

type BodyInit = 
  | ArrayBuffer | ArrayBufferView | NodeJS.ReadableStream 
  | string | URLSearchParams | FormData | Blob | null;

type HeadersInit = 
  | Headers | Record<string, string | string[]> 
  | Iterable<readonly [string, string]> | string[][];