Tcp

Tcp :: # (opaque)

Connect to TCP servers and exchange buffered byte streams.

Connect, read, and write operations have a 30-second host timeout. Materialized reads are limited to 8 MiB; callers should use repeated read_up_to! operations for larger protocols.

connect! : Str, U16 => Try(Connection, ConnectErr(a))

Opens a TCP connection to a remote host.

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

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

connect_err_to_str : [AddrInUse, AddrNotAvailable, CapacityExhausted, 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, ReadLimitExceeded, StreamBusy, StreamNotFound, TimedOut, Unrecognized(a)] -> Str

Convert a StreamErr to a Str you can print.

Connection

Tcp.Connection :: # (opaque)

Represents a TCP stream.

The connection is automatically closed when the last reference to the stream is dropped. The host synchronizes stream access, so it is safe to retain in application context. A concurrent operation returns TcpReadErr(StreamBusy) or TcpWriteErr(StreamBusy).

to_inspect : Connection -> Str

Render the stream without exposing its host handle.

read_up_to! : Connection, U64 => Try(List(U8), _)

Read up to a number of bytes from this TCP stream. Requests larger than 8 MiB return TcpReadErr(ReadLimitExceeded).

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

Read an exact number of bytes or fail.

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

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

Read until a delimiter or EOF is reached. If found, the delimiter is included as the last byte.

read_line! : Connection => Try(Str, _)

Read until a newline (\n, byte 10) or EOF is reached as UTF-8. If found, the newline is included as the last character.

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

Write bytes to this TCP stream.

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

Write a string to this TCP stream, encoded as UTF-8.

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

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

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

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