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(
    Stream,
    ConnectErr,
)

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.

Stream

Tcp.Stream :: # (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 : Stream -> Str

Render the stream without exposing its host handle.

read_up_to! : Stream, 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! : Stream, 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! : Stream, U8 => Try(List(U8), _)

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

read_line! : Stream => 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! : Stream, List(U8) => Try({  }, _)

Write bytes to this TCP stream.

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

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

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

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

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

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