std/net
std/net — TCP sockets + HTTP client.
Handle-backed classes — single handle : i64 field,
ctor params surfaced through explicit constructor(...).
Host-side queries (DNS resolve, reachability probes, IP literal
classification) live in std/dns as free functions.
A socket's two streams are SocketInputStream / SocketOutputStream,
and they carry std::io's InputStream / OutputStream method
shapes exactly — read() : i32, readBytes(buf, offset, len) : i64,skip, available, and their write counterparts. They do not yet
declare conformance: a handle-backed class cannot implement a trait,
because trait dispatch hands the receiver as a pointer while a handle
class's methods take the i64 handle. Matching the shapes is what
makes the conformance a one-word change once that seam is fixed, and
what stops a second byte-stream contract from being invented here in
the meantime.
The native boundary underneath speaks bytes (readInto / writeFrom).
The string conveniences on top are written here, in Axle, and are the
only place a byte sequence is interpreted as text.
Free functions
| Type | Method and description |
|---|---|
| stringBytes(data : string) : i8[] A string's UTF-8 bytes, as an owned byte array of exactly that length. One copy, written once: both the socket writer and the [ Wire] need abuffer to hand the byte FFI, and a second transcription loop is a second place for an off-by-one to live. |
| streamReadInto(handle : i64, buf : ptr, max : i32) : i32 Read up to max bytes from the stream handle names, answering thecount — 0 at end of stream.Free, and taking the handle, because the HTTP message parser reads through a transport that is either a socket or TLS and names the one it holds by handle. The stream classes delegate here, so one read has one FFI symbol and one contract. |
| streamWriteFrom(handle : i64, buf : ptr, len : i32) : void Write exactly len bytes to the stream handle names. |
Method detail
#stringBytes
A string's UTF-8 bytes, as an owned byte array of exactly that length.
One copy, written once: both the socket writer and the [Wire] need a
buffer to hand the byte FFI, and a second transcription loop is a second
place for an off-by-one to live.
data text whose bytes are copied#streamReadInto
Read up to max bytes from the stream handle names, answering the
count — 0 at end of stream.
Free, and taking the handle, because the HTTP message parser reads
through a transport that is either a socket or TLS and names the one it
holds by handle. The stream classes delegate here, so one read has one
FFI symbol and one contract.
#streamWriteFrom
Write exactly len bytes to the stream handle names.
C class Wire
The transport an HTTP message is read and written through: a socket's
byte streams, or a TLS connection.
Two scalars and no owner. The connection's lifetime stays where it was
opened — the caller's defer closes it — so a Wire can be passed down
a parser without any question of who frees what.
The switch is here rather than at each of the parser's ten read sites,
which is the whole reason the type exists.
Constructors
| Type | Method and description |
|---|---|
| constructor(handle : i64, secure : bool) |
Method detail
#constructor
Methods
| Type | Method and description |
|---|---|
| readBytes(self, buf : i8[], offset : i64, len : i64) : i64 Read up to len bytes into buf at offset, answering the count.0 means the peer is done — which HTTP/1.1 framing by EOF reads asthe end of a body, not as a failure. A failure raises, on both transports: a truncated body that reads as a clean ending is how a network error becomes a wrong answer instead of an error. The two halves raise by different routes and that is the whole asymmetry: streamReadInto is an ! IOException shim, so it hasalready raised by the time it answers its -1 sentinel and controlnever reaches the line below; axle_tls raises nothing, so itssentinel is turned into a throw here. |
| writeString(self, data : string) : void Send data's bytes, all of them, in chunks a native call can carry. |
Method detail
#readBytes
Read up to len bytes into buf at offset, answering the count.0 means the peer is done — which HTTP/1.1 framing by EOF reads as
the end of a body, not as a failure. A failure raises, on both
transports: a truncated body that reads as a clean ending is how a
network error becomes a wrong answer instead of an error.
The two halves raise by different routes and that is the whole
asymmetry: streamReadInto is an ! IOException shim, so it has
already raised by the time it answers its -1 sentinel and control
never reaches the line below; axle_tls raises nothing, so its
sentinel is turned into a throw here.
#writeString
Send data's bytes, all of them, in chunks a native call can carry.
C class SocketInputStream
A readable byte stream over a connected socket, carryingstd::io::InputStream's method shapes. Obtain it fromSocket.getInputStream(). Closing it shuts down the underlying read
side of the TCP connection.
Methods
| Type | Method and description |
|---|---|
| rawHandle(self) : i64 This stream's handle. A handle class is its i64 across the FFI,so a body cannot name its own receiver; this asks for it back. |
| readInto(self, buf : ptr, max : i32) : i32 Fill buf with up to max bytes from the peer, answering thecount read. 0 means the peer closed the write side (EOF). |
| read(self) : i32 Next byte 0..255, or -1 at EOF. |
| readBytes(self, buf : i8[], offset : i64, len : i64) : i64 Read up to len bytes into buf[offset .. offset+len). |
| skip(self, n : i64) : i64 Skip up to n bytes by reading and discarding them — a socketcannot seek, so the bytes must come off the wire. |
| available(self) : i64 Always 0. The contract is a lower bound on what is readablewithout blocking, and answering the true count for a socket needs a FIONREAD/ioctl the boundary does not expose. 0 is thehonest lower bound; it never claims a byte is ready. |
| readString(self, max : i32) : string Read up to max bytes and interpret them as UTF-8 text.This is the convenience, not the contract: a byte that is not valid UTF-8 becomes U+FFFD here, so a binary payload must go through readBytes instead. Returns "" at EOF. |
| close(self) : void Shuts down the read side and releases this stream handle. A read already waiting on it answers end of stream; the write side is left open. |
Method detail
#rawHandle
This stream's handle. A handle class is its i64 across the FFI,
so a body cannot name its own receiver; this asks for it back.
#readInto
Fill buf with up to max bytes from the peer, answering the
count read. 0 means the peer closed the write side (EOF).
buf destination buffer of at least max bytesmax maximum byte count to read in one call (clamped to 65536)IOException if the underlying read fails.#read
Next byte 0..255, or -1 at EOF.
IOException if the underlying read fails.#readBytes
Read up to len bytes into buf[offset .. offset+len).
buf destination bufferoffset first destination indexlen maximum bytes to read; a window above one transfer isserved
MAX_TRANSFER_BYTES and the caller reads onIOException if the underlying read fails.#skip
Skip up to n bytes by reading and discarding them — a socket
cannot seek, so the bytes must come off the wire.
n maximum bytes to skipIOException if the underlying read fails.#available
Always 0. The contract is a lower bound on what is readable
without blocking, and answering the true count for a socket needs
a FIONREAD/ioctl the boundary does not expose. 0 is the
honest lower bound; it never claims a byte is ready.
#readString
Read up to max bytes and interpret them as UTF-8 text.
This is the convenience, not the contract: a byte that is not
valid UTF-8 becomes U+FFFD here, so a binary payload must go
through readBytes instead. Returns "" at EOF.
max maximum byte count to read in one call#close
Shuts down the read side and releases this stream handle. A read
already waiting on it answers end of stream; the write side is left
open.
C class SocketOutputStream
A writable byte stream over a connected socket, carryingstd::io::OutputStream's method shapes. Obtain it fromSocket.getOutputStream(). Closing it shuts down the underlying write
side of the TCP connection.
Methods
| Type | Method and description |
|---|---|
| rawHandle(self) : i64 This stream's handle — see the input stream's twin. |
| writeFrom(self, buf : ptr, len : i32) : void Write exactly len bytes from buf to the peer. Blocks untilevery byte has been accepted by the OS send buffer. |
| write(self, b : i32) : void Write the low 8 bits of b as one byte. |
| writeBytes(self, buf : i8[], offset : i64, len : i64) : void Write buf[offset .. offset+len) to the peer, in chunks of at mostMAX_TRANSFER_BYTES so a large buffer is one call's worth at a timerather than a count that would not cross the FFI whole. |
| writeString(self, data : string) : void Write a string's UTF-8 bytes to the peer, in the same chunks. |
| flush(self) : void Flush any buffered bytes to the peer. For TCP streams this is a no-op at the Rust layer (the OS manages send buffering), but the call still propagates any pending socket errors. |
| close(self) : void Shuts down the write side and releases this stream handle. A write already waiting on it ends with an IOException, later writes arerefused, and the read side is left open. |
Method detail
#rawHandle
This stream's handle — see the input stream's twin.
#writeFrom
Write exactly len bytes from buf to the peer. Blocks until
every byte has been accepted by the OS send buffer.
buf source buffer of at least len byteslen number of bytes to sendIOException if the underlying write fails.#write
Write the low 8 bits of b as one byte.
b source value; only its low 8 bits are emitted#writeBytes
Write buf[offset .. offset+len) to the peer, in chunks of at mostMAX_TRANSFER_BYTES so a large buffer is one call's worth at a time
rather than a count that would not cross the FFI whole.
buf source bufferoffset first source indexlen number of bytes to writeIOException if the underlying write fails.#writeString
Write a string's UTF-8 bytes to the peer, in the same chunks.
data text to sendIOException if the underlying write fails.#flush
Flush any buffered bytes to the peer. For TCP streams this is a
no-op at the Rust layer (the OS manages send buffering), but the
call still propagates any pending socket errors.
#close
Shuts down the write side and releases this stream handle. A write
already waiting on it ends with an IOException, later writes are
refused, and the read side is left open.
C class Socket
A client-side TCP connection. The ctor records host + port; the
actual three-way handshake happens on connect(). I/O streams are
surfaced as SocketInputStream / SocketOutputStream handle-backed
objects.
Constructors
| Type | Method and description |
|---|---|
| constructor(host : string, port : i32) Records the target endpoint; opens no connection. Call connect()to perform the handshake. |
Method detail
#constructor
Records the target endpoint; opens no connection. Call connect()
to perform the handshake.
host hostname or IP literal of the peerport TCP port (1..65535)Methods
| Type | Method and description |
|---|---|
| connect(self) : void Performs the TCP three-way handshake to the recorded host/port. Blocks until connected. |
| setTimeoutMillis(self, millis : i32) : void Bounds how long a blocking read or write on this socket may wait.0 restores the OS default, which is to wait forever.Both directions: a peer that stops reading hangs a write exactly as a peer that stops writing hangs a read. Set it after connect() — it applies to the live connection. |
| connectWithin(self, millis : i32) : void Connect under a deadline covering both phases — resolving the name and opening the connection. 0 keeps the default network deadline.Distinct from [ setTimeoutMillis], which bounds reads and writes on aconnection that already exists: a caller who asked for 300 ms meant the whole wait, and a name that resolves slowly would otherwise spend the default deadline before the bound applied to anything. |
| connectAsync(self) : Future<void> Non-blocking connect — the returned future resolves on the event loop once the TCP handshake completes. The socket then belongs to the async verbs (readAsync / writeAsync). |
| readAsync(self, max : i32) : Future<string> Read the next inbound chunk (up to max bytes) without blocking the event loop. An empty string means the peer closed. The bytes are rendered as an owned string through the validating bytebridge: an interior NUL is refused with IllegalArgumentExceptionrather than copied, because a payload is also read as a C string at the libc boundary ( Console::print stops at the first NUL). A payload thatmay hold NUL bytes is binary and belongs on getInputStream() /SocketInputStream.readBytes, which moves bytes unchanged. |
| writeAsync(self, data : string) : Future<void> Flush every byte of data to the peer without blocking the event loop. |
| getInputStream(self) : SocketInputStream Returns a SocketInputStream for reading inbound bytes from the peer.The returned object shares the underlying TcpStream with thissocket; closing the stream shuts down the read side. |
| getOutputStream(self) : SocketOutputStream Returns a SocketOutputStream for writing outbound bytes to the peer.The returned object shares the underlying TcpStream with thissocket; closing the stream shuts down the write side. |
| isConnected(self) : bool Whether the underlying socket is currently connected. |
| getInetAddress(self) : string Resolved IP address of the remote peer, as a string. |
| getPort(self) : i32 Remote port this socket is connected to. |
| close(self) : void Closes the connection and releases the socket handle. Both directions end: a read already waiting answers end of stream, a write already waiting ends with an IOException. |
Method detail
#connect
Performs the TCP three-way handshake to the recorded host/port.
Blocks until connected.
IOException if the host is unreachable or the connectionis refused
#setTimeoutMillis
Bounds how long a blocking read or write on this socket may wait.0 restores the OS default, which is to wait forever.
Both directions: a peer that stops reading hangs a write exactly
as a peer that stops writing hangs a read. Set it afterconnect() — it applies to the live connection.
millis deadline in milliseconds, or 0 for no deadlineIOException if the socket is not connected#connectWithin
Connect under a deadline covering both phases — resolving the name
and opening the connection. 0 keeps the default network deadline.
Distinct from [setTimeoutMillis], which bounds reads and writes on a
connection that already exists: a caller who asked for 300 ms meant the
whole wait, and a name that resolves slowly would otherwise spend the
default deadline before the bound applied to anything.
millis the deadline in milliseconds; 0 for the defaultIOException if the name does not resolve or the peer refuses#connectAsync
Non-blocking connect — the returned future resolves on the
event loop once the TCP handshake completes. The socket then
belongs to the async verbs (readAsync / writeAsync).
#readAsync
Read the next inbound chunk (up to max bytes) without blocking
the event loop. An empty string means the peer closed.
The bytes are rendered as an owned string through the validating byte
bridge: an interior NUL is refused with IllegalArgumentException
rather than copied, because a payload is also read as a C string at the
libc boundary (Console::print stops at the first NUL). A payload that
may hold NUL bytes is binary and belongs on getInputStream() /SocketInputStream.readBytes, which moves bytes unchanged.
IOException when the read fails or a close ends itIllegalArgumentException when the received bytes hold a NUL#writeAsync
Flush every byte of data to the peer without blocking the
event loop.
#getInputStream
Returns a SocketInputStream for reading inbound bytes from the peer.
The returned object shares the underlying TcpStream with this
socket; closing the stream shuts down the read side.
IOException if the socket is not connected or the handleis invalid
#getOutputStream
Returns a SocketOutputStream for writing outbound bytes to the peer.
The returned object shares the underlying TcpStream with this
socket; closing the stream shuts down the write side.
IOException if the socket is not connected or the handleis invalid
#isConnected
Whether the underlying socket is currently connected.
#getInetAddress
Resolved IP address of the remote peer, as a string.
#getPort
Remote port this socket is connected to.
#close
Closes the connection and releases the socket handle. Both directions
end: a read already waiting answers end of stream, a write already
waiting ends with an IOException.
C class ServerSocket
A listening TCP socket. bind() claims the port, then eachaccept() blocks until an inbound connection arrives and returns it
as a connected Socket.
Constructors
| Type | Method and description |
|---|---|
| constructor(port : i32) Records the listen port; claims nothing until bind(). |
Method detail
#constructor
Records the listen port; claims nothing until bind().
port TCP port to listen on (1..65535; 0 lets the OS pick)Methods
| Type | Method and description |
|---|---|
| bind(self) : void Binds and starts listening on the recorded port. |
| accept(self) : Socket Blocks until an inbound connection arrives and returns it as a connected Socket. |
| acceptAsync(self) : Future<Socket> Accept the next peer without blocking the event loop — the future resolves to a connected Socket. |
| getLocalPort(self) : i32 Local port actually bound (useful when the ctor port was 0). |
| close(self) : void Stops listening and releases the socket handle. |
Method detail
#bind
Binds and starts listening on the recorded port.
IOException if the port is already in use or denied#accept
Blocks until an inbound connection arrives and returns it as a
connected Socket.
#acceptAsync
Accept the next peer without blocking the event loop — the
future resolves to a connected Socket.
#getLocalPort
Local port actually bound (useful when the ctor port was 0).
#close
Stops listening and releases the socket handle.
C class InetAddress
Pattern: InetAddress::getByName(host) resolves a hostname,InetAddress::getLocalHost() returns the machine's primary
address. Static-style calls go through the synthesised
zero-arg ctor + method dispatch (new InetAddress().method).
Methods
| Type | Method and description |
|---|---|
| getByName(self, host : string) : InetAddress Resolves host to an address. On failure the returned handle iszero — detect via getHostAddress() == "". |
| getLocalHost(self) : InetAddress The local machine's primary address. |
| getHostName(self) : string Hostname associated with this address. |
| getHostAddress(self) : string Dotted/colon IP string, or empty if the address is unresolved. |
| isReachable(self, timeoutMillis : i32) : bool Non-throwing for the same codegen reason — false on unreachable or invalid handle. |
Method detail
#getByName
Resolves host to an address. On failure the returned handle is
zero — detect via getHostAddress() == "".
host hostname or IP literal to resolve#getLocalHost
The local machine's primary address.
#getHostName
Hostname associated with this address.
#getHostAddress
Dotted/colon IP string, or empty if the address is unresolved.
#isReachable
Non-throwing for the same codegen reason — false on
unreachable or invalid handle.
timeoutMillis reachability probe timeout in milliseconds