# coro-net

Documentation for the module coro-net, version 3.2.1.

coro-net is a library for handling TCP and generally pipes, with an optional secure-layer support using a synchronous style interface.

# Installation 

lit install creationix/coro-net

On Lit search.

# Functions

# connect(options)

Establishes a connection with a TCP handle or with a pipe handle.

  • Both IPv4 and IPv6 can be used for TCP connections.
  • Pipe handles created by this cannot be used for IPC.

# Parameters

Param Type Description
options boolean/table See Options for details.

# Returns

On Success:

Name Type Description
read function The stream read wrapper, if one of options.decode or options.scan is supplied; this would be a coro-wrapper’s adapter, otherwise it’d be coro-channel’s reader. Adapters can be stacked up if multiple options are passed.
write function The stream write wrapper, if options.encode is supplied; this would be a coro-wrapper’s adapter, otherwise it’d be coro-channel’s writer.
socket uv_tcp_t/uv_pipe_t The stream handle of the said established connection.
updateDecoder function A function that takes a single function argument and sets options.decode to that input.
updateEncoder function A function that takes a single function argument and sets options.encode to that input.
close function Waits for any queued operations to finish and closes the socket completely using coro-channel’s closer.

On Failure:

Name Type Description
fail nil If the first return is nil, that means failure has occurred.
err string The error message explaining what went wrong.

# createServer(options, onConnect)

Creates and binds a server instance to a TCP or pipe handle, while asynchronously executing the supplied callback.

# Parameters

Param Type Description
options table See Options for details.
onConnect function See Callback for details.

# Returns

Name Type Description
server uv_tcp_t/uv_pipe_t The stream handle representing the bound server.

# Callback: onConnect(read, write, socket, updateDecoder, updateEncoder)

A callback that’d be called every time a new incoming connection is received.

Callback Parameters:

Param Type Description
read function The stream read wrapper.
write function The stream write wrapper.
socket uv_tcp_t/uv_pipe_t The stream handle the server was bound to.
updateDecoder function A function that takes a single function argument and sets options.decode to that input.
updateEncoder function A function that takes a single function argument and sets options.encode to that input.

Returns:

Return Type Description
success boolean Whether or not your callback has succeeded.
failure string An error message that will be print to stdout explaining what went wrong, without raising an actual error.

# makeCallback([timeout])

Resumes the current coroutine after timeout ms, otherwise returns a function that when called resumes it.

  • Resumes with data on success, nil, err on failure.

Note: this function is suppose to be used with luv async calls.

# Parameters

Param Type Description Optional
timeout number How many millisecond to wait before resuming the coroutine. ✔️

# Returns

Return Type Description
resume function Resumes the coroutine if not already resumed, can be used as a callback that accepts two arguments err, data.

# Structures

# Options

A string-indexed table structure offering different configurations of how coro-net should be interacting and behaving.

# Fields

Field Type Description Required
path string The pipe name the stream refers to, only relevant if host and port aren’t provided. Either path or port/host must be provided.
host string The hostname a TCP connection should be referring to. If port is provided but host isn’t, the default value’s used. Either path or port/host must be provided.
Default: "127.0.0.1".
port number The port of the TCP host the connection refers to. Required if host is provided.
tls boolean/table Whether or not to use secure-layer on top of the connection. A table value for using secure-layer with further configurations, see TLS Options for more details. Optional
timeout number How many millisecond should be wait before canceling the connection out. An undefined amount of seconds is used if nothing is provided. Optional
socktype string The socket type should be used for outgoing connections. Optional
Default: "stream".
family string The outgoing connection family (type). Optional
Default: "inet".
scan function A merger adapter to be used around the read wrapper. Optional
decode function A decoder adapter to be used around the read wrapper. Optional
encode function An encoder adapter to be used around the write wrapper. Optional

# TLS Options

An optional string-indexed table that offers further configurations over the used secure-layer.

Note: When using createServer you must supply cert and key.

# Fields

Field Type Description
protocol string The transport-layer-secure protocol to use. Supported values depends on lua-openssl version, openssl TLS 1.3 compatible supports: TLS (default) or DTLS. LibreSSL and others uses SSLv23 by default, and may support other protocols.
Default: "TLS" or "SSLv23".
ciphers string The encryption algorithm to encrypt the stream with, value MUST be a valid cipher suite string.
Default: "TLS_AES_128_GCM_SHA256:TLS_AES_128_CCM_SHA256" for TLS 1.3, "ECDHE-RSA-AES128-SHA256:AES128-GCM-SHA256" for LTS 1.2, "RC4:HIGH:!MD5:!aNULL:!EDH" for LTS 1.0.
key string The PEM key of the supplied certification (if cert field is passed).
cert string The SSL/TLS x509 certification used for the handshake as string. Used alongside with field key or it gets ignored.
ca string/table The x509 root certificates authority to check against.
Default: a root certification authority (root_ca.dat file) when available.
insecure boolean Weather or not to accept invalid certificates on handshakes.
Default: false.