mug

Types

ConnectError

Errors that can occur when establishing a TCP connection.

pub type ConnectError {
  ConnectFailedIpv4(ipv4: Error)
  ConnectFailedIpv6(ipv6: Error)
  ConnectFailedBoth(ipv4: Error, ipv6: Error)
}

Constructors

```
ConnectFailedIpv4(ipv4: Error)
```
```
ConnectFailedIpv6(ipv6: Error)
```

ConnectFailedBoth(ipv4: Error, ipv6: Error)

ConnectionOptions

</>

pub type ConnectionOptions {
  ConnectionOptions(
    host: String,
    port: Int,
    timeout: Int,
    ip_version_preference: IpVersionPreference,
  )
}

Constructors

```
ConnectionOptions(
  host: String,
  port: Int,
  timeout: Int,
  ip_version_preference: IpVersionPreference,
)
```
Arguments

host

The hostname of the server to connect to.

port

The port of the server to connect to.

timeout

A timeout in milliseconds for the connection to be established.

If both IPv4 and IPv6 are being tried (the default) then this timeout will be used twice, so connecting in total could take twice this amount of time.

Note that if the operating system returns a timeout then this package will also return a timeout, even if this timeout value has not been reached yet.

The default is 1000ms.

ip_version_preference

What approach to take selecting between IPv4 and IPv6.

The default is Ipv6Preferred.

Error

</>

Errors that can occur when working with TCP sockets.

For more information on these errors see the Erlang documentation:

https://www.erlang.org/doc/man/file#type-posix
https://www.erlang.org/doc/man/inet#type-posix

pub type Error {
  Closed
  Timeout
  Eaddrinuse
  Eaddrnotavail
  Eafnosupport
  Ealready
  Econnaborted
  Econnrefused
  Econnreset
  Edestaddrreq
  Ehostdown
  Ehostunreach
  Einprogress
  Eisconn
  Emsgsize
  Enetdown
  Enetunreach
  Enopkg
  Enoprotoopt
  Enotconn
  Enotty
  Enotsock
  Eproto
  Eprotonosupport
  Eprototype
  Esocktnosupport
  Etimedout
  Ewouldblock
  Exbadport
  Exbadseq
  Nxdomain
  Eacces
  Eagain
  Ebadf
  Ebadmsg
  Ebusy
  Edeadlk
  Edeadlock
  Edquot
  Eexist
  Efault
  Efbig
  Eftype
  Eintr
  Einval
  Eio
  Eisdir
  Eloop
  Emfile
  Emlink
  Emultihop
  Enametoolong
  Enfile
  Enobufs
  Enodev
  Enolck
  Enolink
  Enoent
  Enomem
  Enospc
  Enosr
  Enostr
  Enosys
  Enotblk
  Enotdir
  Enotsup
  Enxio
  Eopnotsupp
  Eoverflow
  Eperm
  Epipe
  Erange
  Erofs
  Espipe
  Esrch
  Estale
  Etxtbsy
  Exdev
}

Constructors

```
Closed
```
Connection closed
```
Timeout
```
Operation timed out
```
Eaddrinuse
```
Address already in use
```
Eaddrnotavail
```
Cannot assign requested address
```
Eafnosupport
```
Address family not supported
```
Ealready
```
Operation already in progress
```
Econnaborted
```
Connection aborted
```
Econnrefused
```
Connection refused
```
Econnreset
```
Connection reset by peer
```
Edestaddrreq
```
Destination address required
```
Ehostdown
```
Host is down
```
Ehostunreach
```
No route to host
```
Einprogress
```
Operation now in progress
```
Eisconn
```
Socket is already connected
```
Emsgsize
```
Message too long
```
Enetdown
```
Network is down
```
Enetunreach
```
Network is unreachable
```
Enopkg
```
Package not installed
```
Enoprotoopt
```
Protocol not available
```
Enotconn
```
Socket is not connected
```
Enotty
```
Inappropriate ioctl for device
```
Enotsock
```
Socket operation on non-socket
```
Eproto
```
Protocol error
```
Eprotonosupport
```
Protocol not supported
```
Eprototype
```
Protocol wrong type for socket
```
Esocktnosupport
```
Socket type not supported
```
Etimedout
```
Connection timed out
```
Ewouldblock
```
Operation would block
```
Exbadport
```
Bad port number
```
Exbadseq
```
Bad sequence number
```
Nxdomain
```
Non-existent domain
```
Eacces
```
Permission denied
```
Eagain
```
Resource temporarily unavailable
```
Ebadf
```
Bad file descriptor
```
Ebadmsg
```
Bad message
```
Ebusy
```
Device or resource busy
```
Edeadlk
```
Resource deadlock avoided
```
Edeadlock
```
Resource deadlock avoided
```
Edquot
```
Disk quota exceeded
```
Eexist
```
File exists
```
Efault
```
Bad address
```
Efbig
```
File too large
```
Eftype
```
Inappropriate file type or format
```
Eintr
```
Interrupted system call
```
Einval
```
Invalid argument
```
Eio
```
Input/output error
```
Eisdir
```
Is a directory
```
Eloop
```
Too many levels of symbolic links
```
Emfile
```
Too many open files
```
Emlink
```
Too many links
```
Emultihop
```
Multihop attempted
```
Enametoolong
```
File name too long
```
Enfile
```
Too many open files in system
```
Enobufs
```
No buffer space available
```
Enodev
```
No such device
```
Enolck
```
No locks available
```
Enolink
```
Link has been severed
```
Enoent
```
No such file or directory
```
Enomem
```
Out of memory
```
Enospc
```
No space left on device
```
Enosr
```
Out of streams resources
```
Enostr
```
Device not a stream
```
Enosys
```
Function not implemented
```
Enotblk
```
Block device required
```
Enotdir
```
Not a directory
```
Enotsup
```
Operation not supported
```
Enxio
```
No such device or address
```
Eopnotsupp
```
Operation not supported on socket
```
Eoverflow
```
Value too large for defined data type
```
Eperm
```
Operation not permitted
```
Epipe
```
Broken pipe
```
Erange
```
Result too large
```
Erofs
```
Read-only file system
```
Espipe
```
Illegal seek
```
Esrch
```
No such process
```
Estale
```
Stale file handle
```
Etxtbsy
```
Text file busy
```
Exdev
```
Cross-device link

IpVersionPreference

</>

What approach to take with selection between IPv4 and IPv6

IPv6 is superior when available, but unfortunately not all networks support it.

pub type IpVersionPreference {
  Ipv4Only
  Ipv4Preferred
  Ipv6Only
  Ipv6Preferred
}

Constructors

```
Ipv4Only
```
Only connect over IPv4.
```
Ipv4Preferred
```
Attempt to connect over IPv4 first, attempting IPv6 if connection with IPv4 did not succeed.
```
Ipv6Only
```
Only connect over IPv6.
```
Ipv6Preferred
```
Attempt to connect over IPv6 first, attempting IPv4 if connection with IPv6 did not succeed.

Socket

</>

A TCP socket, used to send and receive TCP messages.

pub type Socket

TcpMessage

</>

Messages that can be sent by the socket to the process that controls it.

pub type TcpMessage {
  Packet(Socket, BitArray)
  SocketClosed(Socket)
  TcpError(Socket, Error)
}

Constructors

```
Packet(Socket, BitArray)
```
A packet has been received from the client.
```
SocketClosed(Socket)
```
The socket has been closed by the client.
```
TcpError(Socket, Error)
```
An error has occurred on the socket.

Values

connect

</>

pub fn connect(
  options: ConnectionOptions,
) -> Result(Socket, ConnectError)

Establish a TCP connection to the server specified in the connection options.

Returns an error if the connection could not be established.

The socket is created in passive mode, meaning the the receive function is to be called to receive packets from the client. The receive_next_packet_as_message function can be used to switch the socket to active mode and receive the next packet as an Erlang message.

describe_error

</>

pub fn describe_error(error: Error) -> String

Convert an error into a human-readable description

ip_version_preference

</>

pub fn ip_version_preference(
  options: ConnectionOptions,
  preference: IpVersionPreference,
) -> ConnectionOptions

What approach to take selecting between IPv4 and IPv6. See the IpVersionPreference type for documentation.

The default is Ipv6Preferred.

new

</>

pub fn new(host: String, port port: Int) -> ConnectionOptions

Create a new set of connection options.

receive

</>

pub fn receive(
  socket: Socket,
  timeout_milliseconds timeout: Int,
) -> Result(BitArray, Error)

Receive a message from the client.

Errors if the socket is closed, if the timeout is reached, or if there is some other problem receiving the packet.

receive_exact

</>

pub fn receive_exact(
  socket: Socket,
  byte_size size: Int,
  timeout_milliseconds timeout: Int,
) -> Result(BitArray, Error)

Receive the specified number of bytes from the client, unless the socket was closed, from the other side. In that case, the last read may return less bytes. If the specified number of bytes is not available to read from the socket then the function will block until the bytes are available, or until the timeout is reached. This directly calls the underlying Erlang function gen_tcp:recv/3.

Errors if the socket is closed, if the timeout is reached, or if there is some other problem receiving the packet.

receive_next_packet_as_message

</>

pub fn receive_next_packet_as_message(socket: Socket) -> Nil

Switch the socket to active mode, meaning that the next packet received on the socket will be sent as an Erlang message to the socket owner’s inbox.

This is useful for when you wish to have an OTP actor handle incoming messages as using the receive function would result in the actor being blocked and unable to handle other messages while waiting for the next packet.

Messages will be send to the process that controls the socket, which is the process that established the socket with the connect function.

select_tcp_messages

</>

pub fn select_tcp_messages(
  selector: process.Selector(t),
  mapper: fn(TcpMessage) -> t,
) -> process.Selector(t)

Configure a selector to receive messages from TCP sockets.

Note this will receive messages from all TCP sockets that the process controls, rather than any specific one. If you wish to only handle messages from one socket then use one process per socket.

send

</>

pub fn send(
  socket: Socket,
  message: BitArray,
) -> Result(Nil, Error)

Send a message to the client.

send_builder

</>

pub fn send_builder(
  socket: Socket,
  packet: bytes_tree.BytesTree,
) -> Result(Nil, Error)

Send a message to the client, the data in BytesBuilder. Using this function is more efficient turning an BytesBuilder or a StringBuilder into a BitArray to use with the send function.

shutdown

</>

pub fn shutdown(socket: Socket) -> Result(Nil, Error)

Close the socket, ensuring that any data buffered in the socket is flushed to the operating system kernel socket first.

timeout

</>

pub fn timeout(
  options: ConnectionOptions,
  milliseconds timeout: Int,
) -> ConnectionOptions

Specify a timeout for the connection to be established, in milliseconds.

The default is 1000ms.

Constructors

Constructors

Arguments

Constructors

Constructors

Constructors