tessl/npm-smithy--protocol-http
Protocol HTTP utilities for Smithy TypeScript clients and servers, providing HTTP request/response handling, field management, hostname validation, and extension configuration for HTTP-based protocol implementations
—
handler-configuration.mddocs/
HTTP Handler Configuration
HTTP handler interfaces and user input types for configurable request handling. Provides abstractions for pluggable HTTP client implementations with configuration management capabilities.
Capabilities
HttpHandler Interface
Generic HTTP handler interface extending RequestHandler with configuration management methods. Enables pluggable HTTP client implementations.
/**
* @internal
* HTTP handler interface with configuration management
*/
type HttpHandler<HttpHandlerConfig extends object = {}> = RequestHandler<
HttpRequest,
HttpResponse,
HttpHandlerOptions
> & {
updateHttpClientConfig(key: keyof HttpHandlerConfig, value: HttpHandlerConfig[typeof key]): void;
httpHandlerConfigs(): HttpHandlerConfig;
};The HttpHandler type combines:
RequestHandler<HttpRequest, HttpResponse, HttpHandlerOptions>- Core request handling capability- Configuration management methods for runtime HTTP client updates
Update HTTP Client Config
Updates HTTP client configuration at runtime for a specific configuration key.
/**
* @internal
* Update HTTP client configuration
* @param key - Configuration key to update
* @param value - New value for the configuration key
*/
updateHttpClientConfig(key: keyof HttpHandlerConfig, value: HttpHandlerConfig[typeof key]): void;Get HTTP Handler Configs
Retrieves the current HTTP handler configuration object.
/**
* @internal
* Get current HTTP handler configuration
* @returns Current handler configuration object
*/
httpHandlerConfigs(): HttpHandlerConfig;HttpHandlerUserInput Type
Union type representing accepted user inputs for the requestHandler field of client constructors. Provides flexibility in how users configure HTTP handling.
/**
* @public
*
* A type representing the accepted user inputs for the `requestHandler` field
* of a client's constructor object.
*
* You may provide an instance of an HttpHandler, or alternatively
* provide the constructor arguments as an object which will be passed
* to the constructor of the default request handler.
*
* The default class constructor to which your arguments will be passed
* varies. The Node.js default is the NodeHttpHandler and the browser/react-native
* default is the FetchHttpHandler. In rarer cases specific clients may be
* configured to use other default implementations such as Websocket or HTTP2.
*
* The fallback type Record<string, unknown> is part of the union to allow
* passing constructor params to an unknown requestHandler type.
*/
type HttpHandlerUserInput =
| HttpHandler
| NodeHttpHandlerOptions
| FetchHttpHandlerOptions
| Record<string, unknown>;Usage Examples:
import { HttpHandlerUserInput } from "@smithy/protocol-http";
// Option 1: Provide HttpHandler instance
const customHandler: HttpHandler = {
handle: (request) => Promise.resolve(/* response */),
updateHttpClientConfig: (key, value) => { /* update logic */ },
httpHandlerConfigs: () => ({ /* config */ })
};
// Option 2: Provide Node.js handler options
const nodeOptions: NodeHttpHandlerOptions = {
connectionTimeout: 5000,
socketTimeout: 10000,
httpAgent: new HttpAgent({ keepAlive: true })
};
// Option 3: Provide Fetch handler options
const fetchOptions: FetchHttpHandlerOptions = {
requestTimeout: 8000,
keepAlive: true
};
// Option 4: Provide custom configuration
const customConfig = {
timeout: 5000,
retries: 3,
customProperty: "value"
};
// All are valid HttpHandlerUserInput
const inputs: HttpHandlerUserInput[] = [
customHandler,
nodeOptions,
fetchOptions,
customConfig
];Handler Input Types
The HttpHandlerUserInput union accommodates different runtime environments:
HttpHandler Instance
Direct HttpHandler implementation with full control over request handling and configuration.
NodeHttpHandlerOptions
Configuration options for Node.js HTTP handler in server environments:
- Connection and socket timeouts
- HTTP agent configuration
- Certificate and proxy settings
- Keep-alive behavior
FetchHttpHandlerOptions
Configuration options for Fetch-based handler in browser/React Native environments:
- Request timeout settings
- Keep-alive configuration
- Fetch API specific options
Generic Configuration
Fallback Record<string, unknown> type allows custom configuration objects for specialized HTTP handler implementations like WebSocket or HTTP2.
Platform-Specific Defaults
The actual HttpHandler implementation varies by platform:
- Node.js: Defaults to
NodeHttpHandlerwith Node.js native HTTP modules - Browser/React Native: Defaults to
FetchHttpHandlerusing the Fetch API - Specialized Clients: May use WebSocket handlers, HTTP2 handlers, or other protocol-specific implementations
This design allows clients to accept handler configuration without tightly coupling to specific HTTP implementation details.
Install with Tessl CLI
npx tessl i tessl/npm-smithy--protocol-http