Configuration.connect()

Description

Appends a connect filter to the current pipeline layout.

A connect filter establishes a TCP connection to a remote host.

INPUT - Data stream to send to the host.
OUTPUT - Data stream received from the host.

A connect filter does the following:

It establishes a TCP or UDP connection to a remote host specified in the target parameter
Input Data stream to the filter is sent to that host after the connection is established
Data stream received from that host comes out from the filter's output

Target address

The target address to connect to is given by the target parameter. It can be a string in form of "<host>:<port>" or a function that returns that string, where host can be an IP address or a domain name and port must be a valid port number.

When using an IPv6 address, wrap it inside a pair of brackets. For example, "[::1]:8080".

Outbound data buffer

No limit is set to how fast input Data can go into a connect filter, but an outgoing TCP connection does have a limit depending on the network condition. When outgoing traffic is too slow and incoming traffic is too fast, Data will be backed up in the filter's internal buffer.

By default, the buffer can grow unlimitedly. You can set a limit to how much data is allowed to stay in memory by option bufferLimit in the options parameter. It can be a number in bytes or a string with a unit suffix such as 'k', 'm', 'g' and 't'.

When data in the buffer goes over that limit, the overflowed data is discarded and you will see an error message from the standard error:

Outbound: xxx to host = xxx port = nnn buffer overflow, size = nnn

Syntax

pipy()
  .pipeline()
  .connect(target)

pipy()
  .pipeline()
  .connect(
    () => getTarget()
  )

pipy()
  .pipeline()
  .connect(
    () => getTarget(),
    {
      bufferLimit,
      retryCount,
      retryDelay,
      connectTimeout,
      readTimeout,
      writeTimeout,
      idleTimeout,
    }
  )

Parameters

connect(target, options?)

target

The target to connect to, in form of "<host>:<port>", or a function that returns the target.

options?

Options including:

protocol - Protocol to use. Can be "TCP" or "UDP". Default is "TCP".
bind - A string in form of "<IP>:<port>" providing the local IP and port to bind to or a function that returns that.
congestionLimit - Size threshold of data backlog in output buffer where congestion feedback starts. Can be a number in bytes or a string with a unit suffix such as 'k', 'm', 'g' and 't'.
bufferLimit - Maximum size of data allowed to stay in output buffer as a result of insufficient outbound bandwidth. Can be a number in bytes or a string with a unit suffix such as 'k', 'm', 'g' and 't'.
retryCount - How many times it should retry connection after a failure, or -1 for the infinite retries. Defaults to 0.
retryDelay - Time duration to wait between connection retries. Defaults to 0.
connectTimeout - Timeout while connecting. Can be a number in seconds or a string with one of the time unit suffixes such as s, m or h. Defaults to no timeout.
readTimeout - Timeout while reading. Can be a number in seconds or a string with one of the time unit suffixes such as s, m or h. Defaults to no timeout.
writeTimeout - Timeout while writing. Can be a number in seconds or a string with one of the time unit suffixes such as s, m or h. Defaults to no timeout.
idleTimeout - Duration before connection is closed due to no active reading or writing. Can be a number in seconds or a string with one of the time unit suffixes such as s, m or h. Defaults to 1 minute.
keepAlive - Enable sending of keep-alive messages on TCP connections. Defaults to true.
noDelay - If set, disable the Nagle algorithm. Defaults to true.

Return Value

The same Configuration object.

Example

pipy()

  .listen(8000)      // Accept connections via port 8000
  .dump('>>>')       // Dump all outgoing data
  .connect(
    'localhost:8080' // Connect to localhost:8080
  )
  .dump('<<<')       // Dump all received data