or run

npx @tessl/cli init

Version

Tile

Overview

Evals

Files

docs

index.md

tile.json

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:

Protocol Detection: Examining the request handler's metadata to determine HTTP protocol version
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
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)