or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

http-handler.mdhttp2-handler.mdindex.mdstream-collector.md
tile.json

tessl/npm-smithy--node-http-handler

HTTP request handlers for Node.js environments in the Smithy TypeScript ecosystem

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
npmpkg:npm/@smithy/node-http-handler@4.2.x

To install, run

npx @tessl/cli install tessl/npm-smithy--node-http-handler@4.2.0

index.mddocs/

Smithy Node HTTP Handler

The Smithy Node HTTP Handler provides HTTP request handling functionality for Node.js environments in the Smithy TypeScript ecosystem. It implements default request handlers using Node.js built-in HTTP modules to enable HTTP client communication for Smithy-generated SDK clients.

Package Information

  • Package Name: @smithy/node-http-handler
  • Package Type: npm
  • Language: TypeScript
  • Installation: npm install @smithy/node-http-handler
  • Minimum Node.js: 18.0.0

Core Imports

import { NodeHttpHandler, NodeHttp2Handler, streamCollector } from "@smithy/node-http-handler";

For CommonJS:

const { NodeHttpHandler, NodeHttp2Handler, streamCollector } = require("@smithy/node-http-handler");

Basic Usage

import { NodeHttpHandler, NodeHttp2Handler } from "@smithy/node-http-handler";
import { HttpRequest } from "@smithy/protocol-http";

// HTTP/1.1 handler
const httpHandler = new NodeHttpHandler({
  requestTimeout: 30000,
  connectionTimeout: 5000
});

// HTTP/2 handler
const http2Handler = new NodeHttp2Handler({
  requestTimeout: 30000,
  sessionTimeout: 300000
});

// Handle a request
const request = new HttpRequest({
  method: "GET",
  hostname: "example.com",
  path: "/api/data",
  headers: {
    "Content-Type": "application/json"
  }
});

const { response } = await httpHandler.handle(request);

Architecture

The package is built around several key components:

  • HTTP/1.1 Handler: NodeHttpHandler using Node.js http and https modules
  • HTTP/2 Handler: NodeHttp2Handler using Node.js http2 module
  • Connection Management: HTTP/2 connection pooling and session management
  • Stream Processing: Utilities for collecting response body streams
  • Timeout Management: Comprehensive timeout handling for connections and requests

Capabilities

HTTP/1.1 Request Handler

Primary request handler using Node.js http and https modules with connection pooling, timeout management, and socket configuration.

class NodeHttpHandler implements HttpHandler<NodeHttpHandlerOptions> {
  constructor(options?: NodeHttpHandlerOptions | Provider<NodeHttpHandlerOptions | void>);
  
  static create(
    instanceOrOptions?: HttpHandler<any> | NodeHttpHandlerOptions | Provider<NodeHttpHandlerOptions | void>
  ): NodeHttpHandler;
  
  static checkSocketUsage(agent: Agent, socketWarningTimestamp: number, logger?: Logger): number;
  
  handle(request: HttpRequest, options?: HttpHandlerOptions): Promise<{ response: HttpResponse }>;
  destroy(): void;
  updateHttpClientConfig(key: keyof NodeHttpHandlerOptions, value: NodeHttpHandlerOptions[typeof key]): void;
  httpHandlerConfigs(): NodeHttpHandlerOptions;
  
  readonly metadata: { handlerProtocol: "http/1.1" };
}

const DEFAULT_REQUEST_TIMEOUT: number;

HTTP/1.1 Handler

HTTP/2 Request Handler

Request handler using Node.js http2 module with session pooling, stream management, and concurrent request support.

class NodeHttp2Handler implements HttpHandler<NodeHttp2HandlerOptions> {
  constructor(options?: NodeHttp2HandlerOptions | Provider<NodeHttp2HandlerOptions | void>);
  
  static create(
    instanceOrOptions?: HttpHandler<any> | NodeHttp2HandlerOptions | Provider<NodeHttp2HandlerOptions | void>
  ): NodeHttp2Handler;
  
  handle(request: HttpRequest, options?: HttpHandlerOptions): Promise<{ response: HttpResponse }>;
  destroy(): void;
  updateHttpClientConfig(key: keyof NodeHttp2HandlerOptions, value: NodeHttp2HandlerOptions[typeof key]): void;
  httpHandlerConfigs(): NodeHttp2HandlerOptions;
  
  readonly metadata: { handlerProtocol: "h2" };
}

interface NodeHttp2HandlerOptions {
  requestTimeout?: number;
  sessionTimeout?: number;
  disableConcurrentStreams?: boolean;
  maxConcurrentStreams?: number;
}

HTTP/2 Handler

Stream Collection

Utilities for converting Node.js streams and Web API ReadableStreams to byte arrays for response body processing.

const streamCollector: StreamCollector;

type StreamCollector = (stream: Readable | ReadableStream): Promise<Uint8Array>;

class Collector extends Writable {
  constructor(options?: WritableOptions);
  bufferedBytes: Buffer[];
  _write(chunk: Buffer, encoding: string, callback: (err?: Error) => void): void;
}

Stream Collection

Types

// Re-exported from @smithy/types
interface NodeHttpHandlerOptions {
  requestTimeout?: number;
  connectionTimeout?: number;
  socketTimeout?: number;
  httpAgent?: Agent;
  httpsAgent?: Agent;
  // ... other options from @smithy/types
}

// From @smithy/protocol-http
interface HttpRequest {
  method: string;
  hostname?: string;
  port?: number;
  path?: string;
  headers?: Record<string, string>;
  body?: any;
  // ... other properties
}

interface HttpResponse {
  statusCode: number;
  headers: Record<string, string>;
  body?: any;
  // ... other properties
}

interface HttpHandler<T> {
  handle(request: HttpRequest, options?: HttpHandlerOptions): Promise<{ response: HttpResponse }>;
}

interface HttpHandlerOptions {
  abortSignal?: AbortSignal;
}

// From @smithy/types
type Provider<T> = T | (() => T) | (() => Promise<T>);

// From Node.js http/https modules
interface Agent {
  destroy(): void;
  // ... other Agent properties
}

// From @smithy/types
interface Logger {
  warn?(message: string): void;
  // ... other Logger methods
}

// From Node.js stream module
interface Readable {
  pipe<T extends Writable>(destination: T): T;
  on(event: string, listener: Function): this;
  // ... other Readable properties
}

// From Node.js stream module
interface WritableOptions {
  highWaterMark?: number;
  objectMode?: boolean;
  // ... other Writable options
}

// From stream/web (Node.js 16.5.0+)
interface ReadableStream<R = any> {
  getReader(): ReadableStreamDefaultReader<R>;
  // ... other ReadableStream properties
}

Error Handling

The handlers provide comprehensive error handling for various network conditions:

  • Connection timeouts and socket errors
  • HTTP/2 stream errors and session management
  • Request cancellation via AbortSignal
  • Node.js specific timeout error handling for network interruptions