or run

npx @tessl/cli init

Version

Tile

Overview

Evals

Files

docs

extension-configuration.md field-management.md handler-configuration.md http-messages.md index.md

tile.json

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

Workspace: tessl
Visibility: Public
Created: 3 months ago
Last updated: 3 months ago
Describes: pkg:npm/@smithy/protocol-http@5.2.x

To install, run

npx @tessl/cli install tessl/npm-smithy--protocol-http@5.2.0

@smithy/protocol-http

Package Information

Package Name: @smithy/protocol-http
Package Type: npm
Language: TypeScript
Installation: npm install @smithy/protocol-http

Core Imports

import { 
  Field, 
  Fields, 
  HttpRequest, 
  HttpResponse, 
  isValidHostname,
  HttpHandler,
  HttpHandlerUserInput
} from "@smithy/protocol-http";

For CommonJS:

const { 
  Field, 
  Fields, 
  HttpRequest, 
  HttpResponse, 
  isValidHostname 
} = require("@smithy/protocol-http");

Basic Usage

import { Field, Fields, HttpRequest, HttpResponse, isValidHostname } from "@smithy/protocol-http";
import { FieldPosition } from "@smithy/types";

// Create HTTP fields (headers/trailers)
const headerField = new Field({
  name: "Content-Type",
  kind: FieldPosition.HEADER,
  values: ["application/json"]
});

// Manage field collections
const fields = new Fields({ fields: [headerField] });
const contentType = fields.getField("content-type"); // Case insensitive

// Create HTTP requests
const request = new HttpRequest({
  method: "POST",
  hostname: "api.example.com", 
  path: "/users",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({ name: "Alice" })
});

// Create HTTP responses
const response = new HttpResponse({
  statusCode: 200,
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({ id: 123, name: "Alice" })
});

// Validate hostnames
if (isValidHostname("api.example.com")) {
  console.log("Valid hostname");
}

Architecture

@smithy/protocol-http is built around several key components:

Field System: Field and Fields classes for managing HTTP metadata (headers, trailers) with case-insensitive access
Message Types: HttpRequest and HttpResponse classes providing concrete implementations with cloning capabilities
Handler Interface: HttpHandler type and configuration for pluggable HTTP client implementations
Validation Utilities: Hostname validation and type guards for runtime safety
Extension System: Configuration hooks for protocol-specific HTTP handler customization
Type Compatibility: Deprecated type re-exports maintaining backward compatibility with existing code

Capabilities

HTTP Field Management

HTTP field handling for headers and trailers with case-insensitive operations and value management.

class Field {
  constructor(options: { name: string; kind?: FieldPosition; values?: string[] });
  add(value: string): void;
  set(values: string[]): void;
  remove(value: string): void;
  toString(): string;
  get(): string[];
}

class Fields {
  constructor(options: { fields?: Field[]; encoding?: string });
  setField(field: Field): void;
  getField(name: string): Field | undefined;
  removeField(name: string): void;
  getByType(kind: FieldPosition): Field[];
}

Field Management

HTTP Request and Response

HTTP message implementations with cloning support and type validation.

class HttpRequest {
  constructor(options: HttpRequestOptions);
  static clone(request: IHttpRequest): HttpRequest;
  static isInstance(request: unknown): request is HttpRequest;
  clone(): HttpRequest; // @deprecated
}

class HttpResponse {
  constructor(options: { statusCode: number; reason?: string; headers?: HeaderBag; body?: any });
  static isInstance(response: unknown): response is HttpResponse;
}

HTTP Messages

HTTP Handler Configuration

HTTP handler interfaces and user input types for configurable request handling.

/**
 * @internal
 */
type HttpHandler<HttpHandlerConfig extends object = {}> = RequestHandler<
  HttpRequest,
  HttpResponse,
  HttpHandlerOptions
> & {
  updateHttpClientConfig(key: keyof HttpHandlerConfig, value: HttpHandlerConfig[typeof key]): void;
  httpHandlerConfigs(): HttpHandlerConfig;
};

type HttpHandlerUserInput =
  | HttpHandler
  | NodeHttpHandlerOptions
  | FetchHttpHandlerOptions
  | Record<string, unknown>;

Handler Configuration

Hostname Validation

Hostname format validation utility for URL construction and validation.

function isValidHostname(hostname: string): boolean;

Extension System

Internal extension configuration system for HTTP handler customization.

interface HttpHandlerExtensionConfiguration<HandlerConfig extends object = {}> {
  setHttpHandler(handler: HttpHandler<HandlerConfig>): void;
  httpHandler(): HttpHandler<HandlerConfig>;
  updateHttpClientConfig(key: keyof HandlerConfig, value: HandlerConfig[typeof key]): void;
  httpHandlerConfigs(): HandlerConfig;
}

Extension Configuration

Deprecated Type Re-exports

Type aliases maintaining backward compatibility with existing code. These types are deprecated and users should migrate to @smithy/types.

/** @deprecated Use FieldOptions from @smithy/types instead */
type FieldOptions = __FieldOptions;

/** @deprecated Use FieldPosition from @smithy/types instead */
type FieldPosition = __FieldPosition;

/** @deprecated Use HeaderBag from @smithy/types instead */
type HeaderBag = __HeaderBag;

/** @deprecated Use HttpMessage from @smithy/types instead */
type HttpMessage = __HttpMessage;

/** @deprecated Use HttpHandlerOptions from @smithy/types instead */
type HttpHandlerOptions = __HttpHandlerOptions;