http-util

Set of utilities to aid in building from-scratch node:http2 stream compatible services.

• Header parsers
• Stream Response methods
• Body parser

Header Parsers / Encoders

From Client:

• Accept Encoding - parse and select based on server/client values

• Accept Language - parse and select

• Accept - parse and select

• Content Type - returns structured data object for use with Body/etc

• Forwarded - parse with select-right-most helper

• Multipart - parse into FormData

• Content Disposition - for use inside of Multipart

• Conditionals - Etag / FixDate for IfMatch, IfModifiedSince etc

• Client Hints

• Forwarded

• Applied Preferences

Server Sent:

• Rate Limit
• Server Timing
• Cache Control
• Clear Site Data
• Conditional (Etag / IMF Date)
• Content Range
• Preferences
• WWW Auth
• STS

import {
  Accept,
  MIME_TYPE_JSON,
  MIME_TYPE_TEXT
} from '@johntalton/http-util/headers'

// assuming our path/method/server supports content in json or text
const supportedType = [ MIME_TYPE_JSON, MIME_TYPE_TEXT ]

// from request.header.accept (client prefers json)
const acceptHeader = 'application/json;q=.5, */*;q.4'

const bestMatchingType = Accept.select(acceptHeader, supportedType)
// bestMatchingType === 'application/json'

Response

All responders take in a stream as well as a metadata object to hint on servername and origin strings etc.

• sendAccepted
• sendConflict
• sendContentTooLarge
• sendCreated
• sendError - 500
• sendForbidden
• sendGone
• sendImATeapot
• sendInsufficientStorage
• sendJSON - Standard Ok response with encoding
• sendMovedPermanently
• sendMultipleChoices
• sendNoContent
• sendNotAcceptable
• sendNotAllowed - Method not supported / allowed
• sendNotFound - 404
• sendNotImplemented
• sendNotModified
• sendPartialContent
• sendPermanentRedirect
• sendPreconditionFailed
• sendPreflight - Response to OPTIONS with CORS headers
• sendRangeNotSatisfiable
• sendSeeOther
• sendTemporaryRedirect
• sendTimeout
• sendTooManyRequests - Rate limit response (429)
• sendTrace
• sendUnauthorized - Unauthorized
• sendUnavailable
• sendUnprocessable
• sendUnsupportedMediaType
• sendSSE - SSE header (leave the stream open)

Responses allow for optional CORS headers as well as Server Timing meta data.

Response Object

The response methods sendXYZ are also wrapped in a Response object which can make imports simpler and help organize code.

import { Response } from '@johntalton/http-util/response/object'

// ... sendNotFound becomes .notFound
Response.notFound(stream, meta)

Body

The requestBody method returns a fetch-like response. Including methods blob, arrayBuffer, bytes, text, formData, json as well as a body as a ReadableStream.

The return is a deferred response that does NOT consume the steam until calling one of the above methods.

Optional byteLimit, contentLength and contentType can be provided to hint the parser, as well as a AbortSignal to abandoned the reader.

import { requestBody } from '@johntalton/http-util/body'

const signal = // from someplace like a timeout for the overall request

// limit time and size for the body
// note: this does not consume the stream
const futureBody = requestBody(stream, {
  byteLimit: 1000 * 1000,
  signal
})

// ... a few moments later ...

// consume the stream
const body = futureBody.json()

Response method API

All response methods take in the stream and a meta property.

Additional parameters are specific to each return type.

Each return type semantic may also expose header (in addition to the standard headers) to the calling code as needed.

Some common objects can be passed such as EtagItem, CacheControlOptions and Metadata have their own structure.

Many parameters accept undefined to skip/ignore the usage

Response.accepted

Parameters:

• stream
• meta

Response.conflict

Parameters:

• stream
• meta

Response.created

Parameters:

• stream
• location - URL to newly create object
• etag - etag of the related object
• meta

Additional Exposed Headers:

• location

Response.error

Parameters:

• stream
• meta

Response.forbidden

Parameters:

• stream
• meta

Response.gone

Parameters:

• stream
• meta

Response.movedPermanently

Parameters:

• steam
• location
• meta

Additional Exposed Headers:

• location

Response.json

Parameters:

• stream
• object
• encoding - undefined | 'identity' | 'br' | 'gzip' | 'deflate' | 'zstd'
• etag
• age
• cacheControl
• supportedQueryTypes - undefined | Array of supported query types
• meta

Additional Exposed Headers

• age
• accept-query

Response.noContent

Parameters:

• stream
• etag
• meta

Response.notAcceptable

Parameters:

• stream
• acceptedTypes - mime types list this route can generate
• meta

Response.notAllowed

Parameters:

• stream
• methods - Array of allowed methods
• meta

Additional Exposed Headers:

• allow

Response.notFound

Parameters:

• stream
• message
• meta

Response.notImplemented

Parameters:

• stream
• message
• meta

Response.notModified

Parameters:

• stream
• etag
• age
• cacheControl
• meta

Additional Exposed Headers:

• age

Response.preconditionFailed

Parameters:

• stream
• meta

Response.preflight

Parameters:

• stream
• methods
• supportedQueryTypes - undefined | Array of supported types
• acceptRanges
• meta

Additional Exposed Headers:

• accept-query
• accept-ranges

Response.rangeNotSatisfiable

Parameters:

• stream
• directive - specify size of acceptable range of bytes
• meta

Additional Exposed Headers:

• content-range

Response.sse

Parameters:

• stream
• meta

Response.timeout

Parameters:

• stream
• meta

Response.tooManyRequests

Parameters:

• stream
• limitInfo - RateLimitInfo
• policies - Array of RateLimitPolicyInfo
• meta

Additional Exposed Headers:

• retry-after
• rate-limit
• rate-limit-policy

Response.trace

Parameters:

• stream
• method
• url
• headers
• meta

Response.unauthorized

Parameters:

• stream
• challenge
• meta

Response.unavailable

Parameters:

• stream
• message
• retryAfter
• meta

Additional Exposed Headers:

• retry-after

Response.unprocessable

Parameters:

• stream
• meta

Response.unsupportedMediaType

Parameters:

• stream
• supportedPostType
• supportedPatchType
• supportedQueryTypes
• meta

Additional Exposed Headers:

• accept-query
• accept-post