Configuration.demuxHTTP()

Description

Appends a demuxHTTP filter to the current pipeline layout.

A demuxHTTP filter implements HTTP/1 and HTTP/2 protocol on the server side.

INPUT - Data stream received from the client with HTTP/1 or HTTP/2 requests.
OUTPUT - Data stream to send to the client with HTTP/1 or HTTP/2 responses.
SUB-INPUT - HTTP request Message received from the client.
SUB-OUTPUT - HTTP response Message to send to the client.

A demuxHTTP filter does the following:

At the input to a demuxHTTP filter, HTTP requests are de-multiplexed and decoded from the input Data stream
For each request, a dedicated sub-pipeline is created, whose input is only one decoded request Message
At the output from the demuxHTTP filter, response Messages coming out from all sub-pipelines are encoded and multiplexed into one single output Data stream

One demuxHTTP filter can have more than one sub-pipelines, each of which handles one HTTP request. Compare this to muxHTTP().

HTTP versions

The decoder can detect the version of HTTP protocol used by the input stream and automatically switch to HTTP/2 if requested.

Multiplexing in HTTP/1.1

In HTTP/1.1, multiplexing is done by HTTP pipelining. A message queue is used internally inside demuxHTTP so that output responses from the filter will always come in the same order as the input requests, even when the sub-pipelines output their responses out of order, in which case an early-arrived response will stay in the queue waiting for its turn to come out.

Multiplexing in HTTP/2

In HTTP/2, multiplexing is inherently supported by the protocol itself. With HTTP/2, every virtual stream in the HTTP/2 transport stream runs in a dedicated sub-pipeline. There is no shared queue to wait as in HTTP/1.1, so a delayed response from one sub-pipeline won't affect other sub-pipelines.

Chunked transfer

When encoding an HTTP/1.x response, the Content-Length header needs to come before the body, so demuxHTTP 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('example')
  .demuxHTTP().to(
    subPipelineLayout
  )

pipy()
  .pipeline('example')
    .demuxHTTP({
      bufferSize,
    }).to(
      subPipelineLayout
    )

Parameters

demuxHTTP(options?)

options?

Options including:

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.

Example

pipy()

  .listen(8000)                       // Accept TCP connection on port 8000
  .demuxHTTP().to(                    // De-multiplex and decode HTTP requests
    $=>$.muxHTTP().to(                // Encode and multiplex the request into a shared TCP stream
      $=>$.connect('localhost:8080')  // Send to and receive from localhost:8080
    )
  )