CtrlK
BlogDocsLog inGet started
Tessl Logo

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

—

Pending
Overview
Eval results
Files

http-messages.mddocs/

HTTP Messages

HTTP message implementations providing concrete HttpRequest and HttpResponse classes with cloning support, type validation, and URI handling. These classes implement the Smithy HTTP message interface with additional utility methods.

Capabilities

HttpRequest Class

HTTP request implementation with URI components, headers, query parameters, and body handling. Supports static cloning with proper deep/shallow copying behavior.

/**
 * HTTP request implementation
 */
class HttpRequest implements HttpMessage, URI {
  method: string;
  protocol: string;
  hostname: string;
  port?: number;
  path: string;
  query: QueryParameterBag;
  headers: HeaderBag;
  username?: string;
  password?: string;
  fragment?: string;
  body?: any;
  
  constructor(options: HttpRequestOptions);
  static clone(request: IHttpRequest): HttpRequest;
  static isInstance(request: unknown): request is HttpRequest;
  clone(): HttpRequest; // @deprecated
}

type HttpRequestOptions = Partial<HttpMessage> & Partial<URI> & { 
  method?: string;
};

Usage Examples:

import { HttpRequest, IHttpRequest } from "@smithy/protocol-http";

// Create HTTP request
const request = new HttpRequest({
  method: "POST",
  hostname: "api.example.com",
  port: 443,
  path: "/users",
  protocol: "https:",
  query: { limit: "10", offset: "0" },
  headers: { 
    "Content-Type": "application/json",
    "Authorization": "Bearer token123"
  },
  body: JSON.stringify({ name: "Alice", email: "alice@example.com" }),
  username: "user",
  password: "pass",
  fragment: "section1"
});

// Clone request (deep clone headers/query, shallow clone body)
const clonedRequest = HttpRequest.clone(request);
clonedRequest.headers["X-Custom"] = "value"; // Won't affect original
clonedRequest.query.page = "2"; // Won't affect original

// Type checking
if (HttpRequest.isInstance(someObject)) {
  console.log(`Method: ${someObject.method}`);
}

Request Constructor

Creates a new HTTP request with default values and proper URI formatting.

/**
 * Creates HTTP request with default values
 * @param options - Request configuration options
 */
constructor(options: HttpRequestOptions);

Default values:

  • method: "GET"
  • hostname: "localhost"
  • protocol: "https:" (auto-adds colon if missing)
  • path: "/" (auto-adds leading slash if missing)
  • query: {}
  • headers: {}

Static Clone Method

Clones an HTTP request with deep-cloned headers and query parameters but shallow-cloned body.

/**
 * Note: this does not deep-clone the body.
 * @param request - Request to clone
 * @returns Cloned HttpRequest instance
 */
static clone(request: IHttpRequest): HttpRequest;

Static Instance Check

Type guard to check if an object conforms to the HttpRequest interface.

/**
 * This method only actually asserts that request is the interface IHttpRequest,
 * and not necessarily this concrete class. Left in place for API stability.
 * 
 * Do not call instance methods on the input of this function, and
 * do not assume it has the HttpRequest prototype.
 * @param request - Object to check
 * @returns Type guard result
 */
static isInstance(request: unknown): request is HttpRequest;

Instance Clone Method (Deprecated)

/**
 * @deprecated use static HttpRequest.clone(request) instead. It's not safe to call
 * this method because HttpRequest.isInstance incorrectly
 * asserts that IHttpRequest (interface) objects are of type HttpRequest (class).
 */
clone(): HttpRequest;

HttpResponse Class

HTTP response implementation with status code, headers, and body handling.

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

type HttpResponseOptions = Partial<HttpMessage> & {
  statusCode: number;
  reason?: string;
};

Usage Examples:

import { HttpResponse } from "@smithy/protocol-http";

// Create HTTP response
const response = new HttpResponse({
  statusCode: 200,
  reason: "OK",
  headers: {
    "Content-Type": "application/json",
    "Cache-Control": "no-cache"
  },
  body: JSON.stringify({ 
    success: true, 
    data: { id: 123, name: "Alice" }
  })
});

// Error response
const errorResponse = new HttpResponse({
  statusCode: 400,
  reason: "Bad Request",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({ 
    error: "Invalid input", 
    code: "VALIDATION_ERROR" 
  })
});

// Type checking
if (HttpResponse.isInstance(someObject)) {
  console.log(`Status: ${someObject.statusCode}`);
}

Response Constructor

Creates a new HTTP response with required status code and optional headers/body.

/**
 * Creates HTTP response
 * @param options - Response configuration options
 */
constructor(options: HttpResponseOptions);

Response Instance Check

Type guard to validate if an object conforms to the HttpResponse interface.

/**
 * Determine if response is a valid HttpResponse
 * @param response - Object to check
 * @returns Type guard result
 */
static isInstance(response: unknown): response is HttpResponse;

Types

type HttpRequestOptions = Partial<HttpMessage> & Partial<URI> & { 
  method?: string;
};

type HttpResponseOptions = Partial<HttpMessage> & {
  statusCode: number;
  reason?: string;
};

interface IHttpRequest extends HttpMessage, URI {
  method: string;
  protocol: string;
  hostname: string;
  port?: number;
  path: string;
  query: QueryParameterBag;
  headers: HeaderBag;
  username?: string;
  password?: string;
  fragment?: string;
  body?: any;
}

Hostname Validation

Utility function for validating hostname format using regex pattern matching.

/**
 * Validates hostname format
 * @param hostname - Hostname string to validate
 * @returns True if hostname format is valid
 */
function isValidHostname(hostname: string): boolean;

Usage Examples:

import { isValidHostname } from "@smithy/protocol-http";

// Valid hostnames
console.log(isValidHostname("example.com")); // true
console.log(isValidHostname("api.example.com")); // true
console.log(isValidHostname("sub-domain.example.co.uk")); // true

// Invalid hostnames  
console.log(isValidHostname("")); // false
console.log(isValidHostname("example.")); // false
console.log(isValidHostname(".example.com")); // false

The validation uses the pattern: /^[a-z0-9][a-z0-9\.\-]*[a-z0-9]$/

Install with Tessl CLI

npx tessl i tessl/npm-smithy--protocol-http

docs

extension-configuration.md

field-management.md

handler-configuration.md

http-messages.md

index.md

tile.json