HTTP/1.1 Handler

/**
 * A request handler that uses the Node.js http and https modules.
 */
class NodeHttpHandler implements HttpHandler<NodeHttpHandlerOptions> {
  /**
   * Create a new HTTP handler instance
   * @param options - Handler configuration options or provider function
   */
  constructor(options?: NodeHttpHandlerOptions | Provider<NodeHttpHandlerOptions | void>);
  
  /**
   * Factory method to create handler instance or return existing HttpHandler
   * @param instanceOrOptions - Existing handler, options, or provider function
   * @returns NodeHttpHandler instance
   */
  static create(
    instanceOrOptions?: HttpHandler<any> | NodeHttpHandlerOptions | Provider<NodeHttpHandlerOptions | void>
  ): NodeHttpHandler;
  
  /**
   * Handle HTTP request and return response
   * @param request - HTTP request object
   * @param options - Request-specific options including abort signal
   * @returns Promise resolving to response object
   */
  handle(request: HttpRequest, options?: HttpHandlerOptions): Promise<{ response: HttpResponse }>;
  
  /**
   * Clean up handler resources and close connection pools
   */
  destroy(): void;
  
  /**
   * Update a specific configuration option
   * @param key - Configuration key to update
   * @param value - New value for the configuration key
   */
  updateHttpClientConfig(key: keyof NodeHttpHandlerOptions, value: NodeHttpHandlerOptions[typeof key]): void;
  
  /**
   * Get current handler configuration
   * @returns Current NodeHttpHandlerOptions configuration
   */
  httpHandlerConfigs(): NodeHttpHandlerOptions;
  
  /**
   * Handler metadata indicating protocol version
   */
  readonly metadata: { handlerProtocol: "http/1.1" };
  
  /**
   * Static utility method to check socket usage and log warnings
   * @param agent - HTTP or HTTPS agent instance
   * @param socketWarningTimestamp - Timestamp for rate limiting warnings
   * @param logger - Optional logger instance
   * @returns Updated warning timestamp
   */
  static checkSocketUsage(agent: Agent, socketWarningTimestamp: number, logger?: Logger): number;
}

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

// Basic handler with default options
const handler = new NodeHttpHandler();

// Handler with custom configuration
const configuredHandler = new NodeHttpHandler({
  requestTimeout: 30000,
  connectionTimeout: 5000,
  socketTimeout: 10000,
  httpsAgent: new Agent({
    keepAlive: true,
    maxSockets: 50
  })
});

// Using factory method
const factoryHandler = NodeHttpHandler.create({
  requestTimeout: 60000
});

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

const { response } = await handler.handle(getRequest);
console.log(response.statusCode); // 200
console.log(response.headers); // Response headers object

// Handle a POST request with body
const postRequest = new HttpRequest({
  method: "POST",
  hostname: "api.example.com", 
  path: "/users",
  headers: {
    "Content-Type": "application/json"
  },
  body: JSON.stringify({ name: "John", email: "john@example.com" })
});

const { response: postResponse } = await handler.handle(postRequest, {
  abortSignal: AbortSignal.timeout(5000) // 5 second timeout
});

// Update configuration dynamically
handler.updateHttpClientConfig("requestTimeout", 45000);

// Clean up when done
handler.destroy();

/**
 * A default of 0 means no timeout.
 */
const DEFAULT_REQUEST_TIMEOUT: number;

// Re-exported from @smithy/types
interface NodeHttpHandlerOptions {
  /**
   * The maximum time in milliseconds that a socket may remain idle before it
   * is closed.
   */
  requestTimeout?: number;
  
  /**
   * The maximum time in milliseconds that a socket may wait for a connection to be established.
   */
  connectionTimeout?: number;
  
  /**
   * The maximum time in milliseconds that a socket may remain idle.
   */
  socketTimeout?: number;
  
  /**
   * The HTTP agent to use for http requests.
   */
  httpAgent?: Agent;
  
  /**
   * The HTTPS agent to use for https requests.
   */
  httpsAgent?: Agent;
  
  /**
   * The amount of time in milliseconds to wait before warning about socket usage saturation.
   */
  socketAcquisitionWarningTimeout?: number;
}