or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

index.md
tile.json

tessl/npm-aws-sdk--middleware-host-header

AWS SDK middleware for handling host headers in HTTP/2 and HTTP/1.1 requests with automatic protocol detection and header management

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
npmpkg:npm/@aws-sdk/middleware-host-header@3.873.x

To install, run

npx @tessl/cli install tessl/npm-aws-sdk--middleware-host-header@3.873.0

index.mddocs/

AWS SDK Middleware Host Header

AWS SDK middleware for handling host headers in HTTP/2 and HTTP/1.1 requests with automatic protocol detection and header management. This middleware automatically manages the transition between HTTP/1.1 'host' headers and HTTP/2 ':authority' headers based on the request handler protocol, ensuring compatibility with both HTTP versions.

Package Information

  • Package Name: @aws-sdk/middleware-host-header
  • Package Type: npm
  • Language: TypeScript
  • Installation: npm install @aws-sdk/middleware-host-header

Core Imports

import { 
  HostHeaderInputConfig,
  HostHeaderResolvedConfig,
  resolveHostHeaderConfig,
  hostHeaderMiddleware,
  hostHeaderMiddlewareOptions,
  getHostHeaderPlugin
} from "@aws-sdk/middleware-host-header";

For CommonJS:

const { 
  HostHeaderInputConfig,
  HostHeaderResolvedConfig,
  resolveHostHeaderConfig,
  hostHeaderMiddleware,
  hostHeaderMiddlewareOptions,
  getHostHeaderPlugin
} = require("@aws-sdk/middleware-host-header");

Basic Usage

This middleware is typically used internally by AWS SDK clients and doesn't require direct consumer usage. However, for custom implementations:

import { HttpRequest } from "@smithy/protocol-http";
import { 
  HostHeaderInputConfig,
  HostHeaderResolvedConfig,
  resolveHostHeaderConfig,
  getHostHeaderPlugin
} from "@aws-sdk/middleware-host-header";

// Configuration
const config = resolveHostHeaderConfig({
  requestHandler: myRequestHandler,
});

// Plugin usage (automatic with AWS SDK clients)
const plugin = getHostHeaderPlugin(config);
plugin.applyToStack(clientStack);

Architecture

The middleware integrates into the AWS SDK's request processing pipeline as a build-step plugin with low priority. It operates by:

  1. Protocol Detection: Examining the request handler's metadata to determine HTTP protocol version
  2. Header Management: Setting appropriate headers based on protocol:
    • HTTP/1.1: Sets 'host' header with hostname and optional port
    • HTTP/2: Removes 'host' header and sets ':authority' header instead
  3. Automatic Integration: Applied automatically to all AWS SDK clients without manual configuration

Capabilities

Configuration Interface

Public configuration interface for host header middleware.

/**
 * Configuration interface for the host header middleware
 * Currently empty but extensible for future configuration options
 * @public - This interface is part of the public API
 */
interface HostHeaderInputConfig {}

Configuration Resolution

Resolves configuration for the host header middleware. Internal API - typically used by AWS SDK internals.

/**
 * Resolves the host header configuration by maintaining object identity
 * @param input - Configuration input combining generic type with resolved config
 * @returns The same input object with resolved config typing
 * @internal - This function is part of the internal API
 */
function resolveHostHeaderConfig<T>(
  input: T & PreviouslyResolved & HostHeaderInputConfig
): T & HostHeaderResolvedConfig;

/**
 * Fully resolved configuration for the host header middleware
 * @internal - This interface is part of the internal API
 */
interface HostHeaderResolvedConfig {
  /** The HTTP handler to use (Fetch in browser, Https in Node.js) */
  requestHandler: RequestHandler<any, any>;
}

Host Header Middleware

Core middleware function that handles host header logic for different HTTP protocol versions. Internal API - used by AWS SDK client configuration.

/**
 * Middleware that automatically manages host headers for HTTP/1.1 and HTTP/2 requests
 * @param options - Resolved configuration containing request handler
 * @returns BuildMiddleware function that processes HTTP requests
 * @internal - This middleware is part of the internal API
 */
const hostHeaderMiddleware: <Input extends object, Output extends object>(
  options: HostHeaderResolvedConfig
) => BuildMiddleware<Input, Output>;

Behavior:

  • For HTTP/2 requests (when handlerProtocol contains "h2"):
    • Removes existing 'host' header
    • Sets ':authority' header with hostname and optional port
  • For HTTP/1.1 requests:
    • Sets 'host' header with hostname and optional port (only if not already present)
  • Only processes HttpRequest instances, passes through other request types unchanged
  • Includes port in header values when specified in the request

Plugin Factory

Creates a pluggable middleware for integration with client stacks. Internal API - used by AWS SDK client configuration.

/**
 * Creates a pluggable middleware for client stack integration
 * @param options - Resolved configuration containing request handler
 * @returns Pluggable object with applyToStack method
 * @internal - This plugin is part of the internal API
 */
const getHostHeaderPlugin: (options: HostHeaderResolvedConfig) => Pluggable<any, any>;

Middleware Options

Configuration options for the middleware integration. Internal API - used by AWS SDK middleware stack configuration.

/**
 * Middleware configuration options defining execution context
 * @internal - These options are part of the internal API
 */
const hostHeaderMiddlewareOptions: BuildHandlerOptions & AbsoluteLocation = {
  name: "hostHeaderMiddleware";
  step: "build";
  priority: "low";
  tags: ["HOST"];
  override: true;
};

Types

import { 
  RequestHandler, 
  BuildHandlerOptions, 
  BuildMiddleware, 
  Pluggable, 
  AbsoluteLocation 
} from "@smithy/types";
import { HttpRequest } from "@smithy/protocol-http";

/**
 * Interface for resolved configuration that must include requestHandler
 * Used internally by the configuration resolution process
 * @internal - This interface is part of the internal API
 */
interface PreviouslyResolved {
  requestHandler: RequestHandler<any, any>;
}

/**
 * Fully resolved configuration for the host header middleware
 * Contains the HTTP handler needed for protocol detection
 * @internal - This interface is part of the internal API
 */
interface HostHeaderResolvedConfig {
  /** The HTTP handler to use. Fetch in browser and Https in Nodejs. */
  requestHandler: RequestHandler<any, any>;
}

Error Handling

The middleware handles edge cases gracefully:

  • Non-HttpRequest instances: Passed through unchanged without processing
  • Missing protocol metadata: Defaults to HTTP/1.1 behavior when handlerProtocol is undefined
  • Existing headers: Preserves existing host headers for HTTP/1.1 requests, removes for HTTP/2
  • Port handling: Automatically includes port in header values when present in the request

No explicit exceptions are thrown by this middleware - it relies on underlying HTTP request processing for error handling.

Usage Examples

Automatic AWS SDK Integration

import { S3Client } from "@aws-sdk/client-s3";

// Host header middleware is automatically applied
const client = new S3Client({ region: "us-east-1" });

// For HTTP/1.1 requests, 'host' header is automatically set
// For HTTP/2 requests, ':authority' header is automatically set

Custom Request Handler Integration

import { HttpRequest } from "@smithy/protocol-http";
import { hostHeaderMiddleware, resolveHostHeaderConfig } from "@aws-sdk/middleware-host-header";

// Custom request handler with HTTP/2 support
const customHandler = {
  handle: async (request) => { /* ... */ },
  metadata: { handlerProtocol: "h2" }
};

// Configure middleware
const config = resolveHostHeaderConfig({
  requestHandler: customHandler
});

// Create middleware
const middleware = hostHeaderMiddleware(config);

// Apply to request (automatically handles protocol-specific headers)
const request = new HttpRequest({
  hostname: "example.amazonaws.com",
  port: 443
});

Protocol-Specific Behavior

// HTTP/1.1 request - sets 'host' header
const http1Request = new HttpRequest({
  hostname: "api.amazonaws.com",
  port: 443
});
// Results in: headers: { "host": "api.amazonaws.com:443" }

// HTTP/2 request - sets ':authority' header and removes 'host'
const http2Request = new HttpRequest({
  hostname: "api.amazonaws.com", 
  port: 443,
  headers: { host: "existing-host" }
});
// With HTTP/2 handler, results in: 
// headers: { ":authority": "api.amazonaws.com:443" }
// (host header removed)