HTTP Request & Response

/**
 * HTTP request interface representing a complete HTTP request
 * Used throughout the SDK for service communication
 */
interface HttpRequest extends HttpMessage {
  /** HTTP method (GET, POST, PUT, DELETE, etc.) */
  method: string;
  /** Protocol scheme (http: or https:) */
  protocol: string;
  /** Target hostname */
  hostname: string;
  /** Optional port number (defaults based on protocol) */
  port?: number;
  /** Request path including any path parameters */
  path: string;
  /** Optional query parameters */
  query?: QueryParameterBag;
}

/**
 * Base HTTP message interface containing common request/response properties
 * Shared between HttpRequest and HttpResponse
 */
interface HttpMessage {
  /** HTTP headers collection */
  headers: HeaderBag;
  /** Optional request/response body */
  body?: any;
}

/**
 * HTTP headers collection interface
 * Provides case-insensitive header access and manipulation
 */
interface HeaderBag {
  [name: string]: string | undefined;
}

/**
 * AWS-specific headers interface with enhanced manipulation methods
 * Extends Map with AWS-specific header operations
 */
interface Headers extends Map<string, string> {
  /**
   * Returns a new instance of Headers with the specified header set
   * Does not modify the original Headers instance
   */
  withHeader(headerName: string, headerValue: string): Headers;
  
  /**
   * Returns a new instance of Headers without the specified header
   * Does not modify the original Headers instance
   */
  withoutHeader(headerName: string): Headers;
}

/**
 * Query parameter collection interface
 * Supports both single values and arrays for multi-value parameters
 */
interface QueryParameterBag {
  [key: string]: string | Array<string> | undefined;
}

import { HttpRequest, HeaderBag, QueryParameterBag } from "@aws-sdk/types";

// Basic HTTP request
const request: HttpRequest = {
  method: "GET",
  protocol: "https:",
  hostname: "s3.amazonaws.com",
  path: "/my-bucket/my-object",
  headers: {
    "Authorization": "AWS4-HMAC-SHA256 Credential=...",
    "Content-Type": "application/json"
  }
};

// Request with query parameters
const requestWithQuery: HttpRequest = {
  method: "GET",
  protocol: "https:",
  hostname: "dynamodb.us-east-1.amazonaws.com",
  path: "/",
  headers: {
    "X-Amz-Target": "DynamoDB_20120810.Query"
  },
  query: {
    "TableName": "my-table",
    "AttributesToGet": ["id", "name"]
  }
};

/**
 * HTTP response interface representing a complete HTTP response
 * Contains status information and response body
 */
interface HttpResponse extends HttpMessage {
  /** HTTP status code (200, 404, 500, etc.) */
  statusCode: number;
  /** Optional reason phrase */
  reason?: string;
}

/**
 * Resolved HTTP response with string body
 * Used when response body has been fully read and decoded
 */
interface ResolvedHttpResponse extends HttpResponse {
  /** Response body as a string */
  body: string;
}

/**
 * Response metadata interface containing AWS-specific response information
 * Attached to all successful AWS service responses
 */
interface ResponseMetadata {
  /** HTTP status code from the response */
  httpStatusCode?: number;
  /** AWS request ID for tracking and debugging */
  requestId?: string;
  /** Extended request ID for additional tracking */
  extendedRequestId?: string;
  /** CloudFront distribution ID if applicable */
  cfId?: string;
  /** Number of retry attempts made */
  attempts?: number;
  /** Total delay from all retry attempts */
  totalRetryDelay?: number;
}

/**
 * Interface for objects that carry response metadata
 * All AWS service response objects implement this interface
 */
interface MetadataBearer {
  /** Response metadata from AWS service */
  $metadata: ResponseMetadata;
}

import { 
  HttpResponse, 
  ResolvedHttpResponse, 
  MetadataBearer,
  ResponseMetadata 
} from "@aws-sdk/types";

// Handle HTTP response
const handleResponse = (response: HttpResponse) => {
  if (response.statusCode >= 200 && response.statusCode < 300) {
    console.log("Success:", response.statusCode);
  } else {
    console.error("Error:", response.statusCode, response.reason);
  }
};

// AWS service response with metadata
interface S3GetObjectOutput extends MetadataBearer {
  Body?: ReadableStream;
  ContentType?: string;
  ContentLength?: number;
}

const s3Response: S3GetObjectOutput = {
  Body: new ReadableStream(),
  ContentType: "application/json",
  ContentLength: 1024,
  $metadata: {
    httpStatusCode: 200,
    requestId: "abc123-def456-ghi789",
    attempts: 1,
    totalRetryDelay: 0
  }
};

/**
 * Enhanced headers interface extending Map with AWS-specific functionality
 * Provides case-insensitive header access and immutable operations
 */
interface Headers extends Map<string, string> {
  /**
   * Create a new Headers object with an additional header
   * @param headerName - Name of the header to add
   * @param headerValue - Value of the header to add
   * @returns New Headers object with the added header
   */
  withHeader(headerName: string, headerValue: string): Headers;
  
  /**
   * Create a new Headers object with a header removed
   * @param headerName - Name of the header to remove
   * @returns New Headers object without the specified header
   */
  withoutHeader(headerName: string): Headers;
}

import { Headers } from "@aws-sdk/types";

// Working with enhanced headers
const headers: Headers = new Map([
  ["Content-Type", "application/json"],
  ["Authorization", "Bearer token123"]
]);

// Add a header (immutable operation)
const headersWithDate = headers.withHeader("Date", new Date().toISOString());

// Remove a header (immutable operation)
const headersWithoutAuth = headers.withoutHeader("Authorization");

// Case-insensitive access
const contentType = headers.get("content-type"); // Works regardless of case

/**
 * Options for HTTP request handling
 * Used to configure timeout, connection pooling, and other HTTP client behavior
 */
interface HttpHandlerOptions {
  /** Request timeout in milliseconds */
  requestTimeout?: number;
  /** Connection timeout in milliseconds */
  connectionTimeout?: number;
  /** Maximum number of sockets to allow per host */
  maxSockets?: number;
  /** Keep sockets alive between requests */
  keepAlive?: boolean;
  /** Maximum time to keep socket alive when idle */
  keepAliveMsecs?: number;
}

/**
 * Service endpoint configuration
 * Defines the target endpoint for AWS service requests
 */
interface Endpoint {
  /** Protocol scheme (http or https) */
  protocol: string;
  /** Hostname or IP address */
  hostname: string;
  /** Port number */
  port?: number;
  /** Base path for the endpoint */
  path?: string;
  /** Additional query parameters */
  query?: QueryParameterBag;
}

import { Endpoint, HttpHandlerOptions } from "@aws-sdk/types";

// Configure custom endpoint
const customEndpoint: Endpoint = {
  protocol: "https",
  hostname: "my-private-s3.example.com",
  port: 9000,
  path: "/api/v1"
};

// Configure HTTP handler options
const httpOptions: HttpHandlerOptions = {
  requestTimeout: 30000,      // 30 seconds
  connectionTimeout: 5000,    // 5 seconds
  maxSockets: 50,            // Max connections per host
  keepAlive: true,
  keepAliveMsecs: 1000
};

/**
 * Internal request representation used within the SDK
 * @internal
 */
interface Request {
  /** Target destination URL */
  destination: URL;
  /** Optional request body */
  body?: any;
}

/**
 * Internal response representation used within the SDK
 * @internal
 */
interface Response {
  /** Response body */
  body: any;
}