Tcp

Tcp :: # (opaque)

Connect to TCP servers and exchange buffered byte streams.

See the host runtime behavior for additional runtime details.

Timeout arguments are in milliseconds and apply to the whole operation, including every underlying read/write attempt. A zero timeout fails immediately. Read and write timeouts are returned as TcpReadErr(TimedOut) and TcpWriteErr(TimedOut) respectively.

stream = Tcp.connect!("example.com", 80, 5_000)?
stream.write_utf8!("GET / HTTP/1.0\r\nHost: example.com\r\n\r\n", 5_000)?
status_line = stream.read_line!(1_024, 5_000)?
listen! : Str, U16, U64 => Try(Listener, _)

Bind an address and listen. Port zero reserves an OS-assigned port until this listener is closed. The timeout includes hostname resolution.

connect! : Str, U16, U64 => Try(
    Stream,
    [
        AddrInUse,
        AddrNotAvailable,
        ConnectionRefused,
        Interrupted,
        PermissionDenied,
        TimedOut,
        Unrecognized(
            Str,
        ),
        Unsupported,
    ],
)

Opens a TCP connection, waiting at most timeout_ms milliseconds across DNS resolution and all resolved addresses. A zero timeout fails immediately.

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

Valid hostnames look like 127.0.0.1, ::1, localhost, or roc-lang.org.

connect_err_to_str : [
    AddrInUse,
    AddrNotAvailable,
    ConnectionRefused,
    Interrupted,
    PermissionDenied,
    TimedOut,
    Unsupported,
    Unrecognized(
        a,
    ),
] -> Str

Convert a ConnectErr to a Str you can print.

stream_err_to_str : [
    BrokenPipe,
    ConnectionRefused,
    ConnectionReset,
    Interrupted,
    OutOfMemory,
    PermissionDenied,
    StreamNotFound,
    TimedOut,
    Unrecognized(
        a,
    ),
] -> Str

Convert a StreamErr to a Str you can print.

Listener

Tcp.Listener :: # (opaque)

A listening socket. Final ARC release closes it; close! affects all aliases.

accept! : Listener, U64 => Try(Stream, _)

Accept a connection within the given whole-operation timeout.

close! : Listener => Try({}, _)

Close the listener. Repeated closes succeed.

Stream

Tcp.Stream :: # (opaque)

Represents a TCP stream.

The connection is automatically closed when the last reference to the stream is dropped. It wraps an opaque host-side BufReader<TcpStream> handle.

to_inspect : Stream -> Str

Render the stream without exposing its host handle.

read_exactly! : Stream, U64, U64 => Try(List(U8), _)

Read an exact number of bytes, waiting at most timeout_ms milliseconds.

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

read_until! : Stream, U8, U64, U64 => Try(List(U8), _)

Read until a delimiter or EOF is reached, consuming at most max_bytes and waiting at most timeout_ms milliseconds. If found, the delimiter is included as the last byte. Returns TcpReadLimitExceeded(max_bytes) if the delimiter was not found within the limit.

read_line! : Stream, U64, U64 => Try(Str, _)

Read at most max_bytes through a newline (\n, byte 10) or EOF as UTF-8, waiting at most timeout_ms milliseconds. If found, the newline is included as the last character.

write! : Stream, List(U8), U64 => Try({}, _)

Write bytes, waiting at most timeout_ms milliseconds.

write_utf8! : Stream, Str, U64 => Try({}, _)

Write a string as UTF-8, waiting at most timeout_ms milliseconds.

ConnectErr : [
    PermissionDenied,
    AddrInUse,
    AddrNotAvailable,
    ConnectionRefused,
    Interrupted,
    TimedOut,
    Unsupported,
    Unrecognized(Str),
]

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

StreamErr : [
    StreamNotFound,
    PermissionDenied,
    ConnectionRefused,
    ConnectionReset,
    Interrupted,
    TimedOut,
    OutOfMemory,
    BrokenPipe,
    Unrecognized(Str),
]

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