Configuration.encodeHTTPResponse()

Description

Appends an encodeHTTPResponse filter to the current pipeline layout.

An encodeHTTPResponse filter encodes HTTP/1 response messages into a raw byte stream.

INPUT - HTTP/1 response Messages to encode.
OUTPUT - Encoded Data stream from the input HTTP/1 response messages.

The encoder expects an input Message to have:

head
- protocol - Can be "HTTP/1.0" or "HTTP/1.1" (Defaults to "HTTP/1.1")
- status - Response status code (Defaults to 200)
- statusText - Response reason phrase (Defaults to "OK")
- headers - Header fields
body - Message body

If any fields are missing in Message.head, their default values will be taken.

This filter only supports HTTP/1.x. For compatibility with HTTP/2, check out demuxHTTP().

Response to HEAD requests

When encoding a response to a HEAD request, you need to tell the filter that the response is supposed to have no body following the header. You do so by the bodiless option in the options parameter. It can be a boolean value or a function that returns a boolean value.

Chunked transfer

When encoding a response, the Content-Length header needs to come before the body, so encodeHTTPRequest has to buffer the entire body until it sees a MessageEnd event, only by then can the filter output a value for Content-Length header, followed by the previously buffered body.

The buffering is limited to 4KB by default. When the buffered data is over 4KB, the encoder will opt for chunked encoding, where a Content-Length header is no longer needed. You can change this limit by the option bufferSize in the options parameter.

Syntax

pipy()
  .pipeline()
  .encodeHTTPResponse()

pipy()
  .pipeline()
  .encodeHTTPResponse({
    final,
    bodiless,
    bufferSize,
  })

Parameters

encodeHTTPResponse(options?)

options?

Options including:

final - (optional) A boolean or a function that returns a boolean indicating whether the response is the last one on this session. Default is false.
bodiless - (optional) A boolean or a function that returns a boolean indicating whether the message is a response to a HEAD request. Default is false.
bufferSize - (optional) Maximum body size above which a message should be transferred in chunks. Can be a number in bytes or a string with a unit suffix such as 'k', 'm', 'g' and 't'. Default is 16KB.

Return Value

The same Configuration object.