@debugr/http-common
v3.0.0-rc.6
Published
Common interfaces and utility functions for HTTP plugins
Downloads
1,041
Readme
Common HTTP interfaces and utilities
This package defines the shape of the data
included in entries which
represent HTTP requests or responses. Plugins which produce or consume such entries
should conform to this shape. Unless you're developing a Debugr plugin
or log handler, you usually don't need to worry about this package, as it will
be installed and used automatically when required.
For plugin developers
The package exports the following type definitions:
export interface HttpHeaders {
[header: string]: number | string | string[] | undefined;
}
export interface HttpRequestData {
method: string; // The uppercase HTTP request method, e.g. 'GET', 'POST' etc.
uri: string; // The request URI including query string, if any
headers?: HttpHeaders; // A map of HTTP headers to values or lists of values. Header names should be lower-case.
ip?: string; // The client IP, if it can be determined.
body?: string; // The request body as a string, if the request body was captured.
bodyLength?: number; // Request body length in bytes derived from the actual request data, NOT from the Content-Length header.
lengthMismatch?: boolean; // This should be `true` if the actual request body length didn't match the Content-Length header.
}
export interface HttpResponseData {
status: number; // HTTP response status code.
message?: string; // HTTP response status message.
headers?: HttpHeaders; // A map of HTTP headers; same format as for request headers.
body?: string; // The response body as a string, if the response body was captured.
bodyLength?: number; // Response body length in bytes derived from the actual response data, NOT from the Content-Length header.
lengthMismatch?: boolean; // This should be `true` if the actual response body length didn't match the Content-Length header.
}
export interface HttpRequestLogEntry<
TTaskContext extends TContextBase = TContextBase,
TGlobalContext extends TContextShape = TContextShape,
> extends LogEntry<TTaskContext, TGlobalContext> {
type: 'http.request';
data: HttpRequestData;
}
export interface HttpResponseLogEntry<
TTaskContext extends TContextBase = TContextBase,
TGlobalContext extends TContextShape = TContextShape,
> extends LogEntry<TTaskContext, TGlobalContext> {
type: 'http.response';
data: HttpResponseData;
}
There is also a number of utility functions exported:
getHttpStatusMessage(status: number): string
- This function will return the standard HTTP status message for a given status code, or(unknown)
if no message is defined for the status code.formatHttpHeaders(headers: HttpHeaders): string
- This function will format a HTTP header map similarly to the way the headers would be formatted in an actual request or response header. This is intended to be a formatting shortcut for log handlers trying to display information about a request or a response, there is no guarantee that headers formatted this way will be spec-compliant or usable in an actual request or response.createHttpHeadersFilter(exclude?: string[]): HeaderFilter
- This function will create a filter callback which you can use to replace the value of any headers in theexclude
list with the string**redacted**
. Typically, you'd use this for headers containing sensitive information, likeCookie
orAuthorization
.createHttpCaptureChecker(option: CaptureBodyOption = false): CaptureBodyChecker
- This function will create a callback which you can use to check whether a particular request or response body should be captured according to rules defined by the providedCaptureBodyOption
. Aboolean
means what you'd expect it to mean:true
means always capture,false
means never capture. If you pass in anumber
, it is interpreted as the maximum body size in bytes. If you pass in astring
or astring[]
, it will be converted to a pattern which will be tested against theContent-Type
header. The pattern can contain an asterisk (*
) to represent one or more characters; the string can also contain multiple patterns separated by a comma (,
) or one or more whitespace characters. All of the following are examples of valid patterns:text/html
,text/*
,text/*, application/json
,['image/svg', 'text/*, application/json']
. The last form theCaptureBodyOption
can take is aRecord<string, boolean | number>
, where the keys are patterns matched against theContent-Type
header and the values are either booleans or numbers with the same semantics as described above; when no matching entry exists for a particular content type,false
is assumed.normalizeContentType(type?: number | string | string[]): string | undefined
- This function normalizes the content type from a request or response header map into a string, optionally stripping any postfixes after the first;
character.normalizeContentLength(length?: number | string | string[]): number | undefined
- This function normalizes the content length from a request or response header map into a number.