Tcp

Stream

Represents a TCP stream.

ConnectErr

Represents errors that can occur when connecting to a remote host.

StreamErr

Represents errors that can occur when performing an effect with a Stream.

connect! : Str, U16 => Result Stream ConnectErr

Opens a TCP connection to a remote host.

# Connect to localhost:8080
stream = Tcp.connect!("localhost", 8080)?

The connection is automatically closed when the last reference to the stream is dropped. Examples of valid hostnames:

read_up_to! : Stream, U64 => Result (List U8) [TcpReadErr StreamErr]

Read up to a number of bytes from the TCP stream.

# Read up to 64 bytes from the stream
received_bytes = File.read_up_to!(stream, 64)?

To read an exact number of bytes or fail, you can use Tcp.read_exactly! instead.

read_exactly! : Stream, U64 => Result (List U8) [ TcpReadErr StreamErr, TcpUnexpectedEOF ]

Read an exact number of bytes or fail.

bytes = File.read_exactly!(stream, 64)?

TcpUnexpectedEOF is returned if the stream ends before the specfied number of bytes is reached.

read_until! : Stream, U8 => Result (List U8) [TcpReadErr StreamErr]

Read until a delimiter or EOF is reached.

# Read until null terminator
bytes = File.read_until!(stream, 0)?

If found, the delimiter is included as the last byte.

To read until a newline is found, you can use Tcp.read_line! which conveniently decodes to a Str.

read_line! : Stream => Result Str [ TcpReadErr StreamErr, TcpReadBadUtf8 ]

Read until a newline or EOF is reached.

# Read a line and then print it to `stdout`
line_str = File.read_line!(stream)?
Stdout.line(lineStr)?

If found, the newline is included as the last character in the Str.

write! : Stream, List U8 => Result {} [TcpWriteErr StreamErr]

Writes bytes to a TCP stream.

# Writes the bytes 1, 2, 3
Tcp.write!(stream, [1, 2, 3])?

To write a Str, you can use Tcp.write_utf8! instead.

write_utf8! : Stream, Str => Result {} [TcpWriteErr StreamErr]

Writes a Str to a TCP stream, encoded as UTF-8.

# Write "Hi from Roc!" encoded as UTF-8
Tcp.write_utf8!(stream, "Hi from Roc!")?

To write unformatted bytes, you can use Tcp.write! instead.

connect_err_to_str : ConnectErr -> Str

Convert a ConnectErr to a Str you can print.

when err is
    TcpPerfomErr(TcpConnectErr(connectErr)) ->
        Stderr.line!(Tcp.connect_err_to_str(connectErr))

stream_err_to_str : StreamErr -> Str

Convert a StreamErr to a Str you can print.

when err is
    TcpPerformErr(TcpReadErr(err)) ->
        errStr = Tcp.stream_err_to_str(err)
        Stderr.line!("Error while reading: ${errStr}")

    TcpPerformErr(TcpWriteErr(err)) ->
        errStr = Tcp.stream_err_to_str(err)
        Stderr.line!("Error while writing: ${errStr}")