Axle v0.22.0
Package

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

TypeMethod and description
i8[]
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 a
buffer to hand the byte FFI, and a second transcription loop is a second
place for an off-by-one to live.
i32
streamReadInto(handle : i64, buf : ptr, max : i32) : i32 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.
void
streamWriteFrom(handle : i64, buf : ptr, len : i32) : void Write exactly len bytes to the stream handle names.

Method detail

#stringBytes

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 a
buffer to hand the byte FFI, and a second transcription loop is a second
place for an off-by-one to live.

Parameters
data text whose bytes are copied

#streamReadInto

streamReadInto(handle : i64, buf : ptr, max : i32) : i32 ! IOException

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

streamWriteFrom(handle : i64, buf : ptr, len : i32) : void ! IOException

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

TypeMethod and description
constructor(handle : i64, secure : bool)

Method detail

#constructor

constructor(handle : i64, secure : bool)

Methods

TypeMethod and description
i64
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 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.
void
writeString(self, data : string) : void Send data's bytes, all of them, in chunks a native call can carry.

Method detail

#readBytes

readBytes(self, buf : i8[], offset : i64, len : i64) : i64 ! IOException

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

writeString(self, data : string) : void ! IOException

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, carrying
std::io::InputStream's method shapes. Obtain it from
Socket.getInputStream(). Closing it shuts down the underlying read
side of the TCP connection.

Methods

TypeMethod and description
i64
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.
i32
readInto(self, buf : ptr, max : i32) : i32 Fill buf with up to max bytes from the peer, answering the
count read. 0 means the peer closed the write side (EOF).
i32
read(self) : i32 Next byte 0..255, or -1 at EOF.
i64
readBytes(self, buf : i8[], offset : i64, len : i64) : i64 Read up to len bytes into buf[offset .. offset+len).
i64
skip(self, n : i64) : i64 Skip up to n bytes by reading and discarding them — a socket
cannot seek, so the bytes must come off the wire.
i64
available(self) : i64 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.
string
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.
void
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

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

readInto(self, buf : ptr, max : i32) : i32 ! IOException

Fill buf with up to max bytes from the peer, answering the
count read. 0 means the peer closed the write side (EOF).

Parameters
buf destination buffer of at least max bytes
max maximum byte count to read in one call (clamped to 65536)
Throws
IOException if the underlying read fails.

#read

read(self) : i32 ! IOException

Next byte 0..255, or -1 at EOF.

Throws
IOException if the underlying read fails.

#readBytes

readBytes(self, buf : i8[], offset : i64, len : i64) : i64 ! IOException

Read up to len bytes into buf[offset .. offset+len).

Parameters
buf destination buffer
offset first destination index
len maximum bytes to read; a window above one transfer is
served MAX_TRANSFER_BYTES and the caller reads on
Returns bytes read, or -1 at EOF
Throws
IOException if the underlying read fails.

#skip

skip(self, n : i64) : i64 ! IOException

Skip up to n bytes by reading and discarding them — a socket
cannot seek, so the bytes must come off the wire.

Parameters
n maximum bytes to skip
Returns bytes actually skipped (short at EOF)
Throws
IOException if the underlying read fails.

#available

available(self) : i64

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

readString(self, max : i32) : string ! IOException

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.

Parameters
max maximum byte count to read in one call

#close

close(self) : void ! IOException

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, carrying
std::io::OutputStream's method shapes. Obtain it from
Socket.getOutputStream(). Closing it shuts down the underlying write
side of the TCP connection.

Methods

TypeMethod and description
i64
rawHandle(self) : i64 This stream's handle — see the input stream's twin.
void
writeFrom(self, buf : ptr, len : i32) : void Write exactly len bytes from buf to the peer. Blocks until
every byte has been accepted by the OS send buffer.
void
write(self, b : i32) : void Write the low 8 bits of b as one byte.
void
writeBytes(self, buf : i8[], offset : i64, len : i64) : void Write buf[offset .. offset+len) to the peer, in chunks of at most
MAX_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.
void
writeString(self, data : string) : void Write a string's UTF-8 bytes to the peer, in the same chunks.
void
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.
void
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 are
refused, and the read side is left open.

Method detail

#rawHandle

rawHandle(self) : i64

This stream's handle — see the input stream's twin.

#writeFrom

writeFrom(self, buf : ptr, len : i32) : void ! IOException

Write exactly len bytes from buf to the peer. Blocks until
every byte has been accepted by the OS send buffer.

Parameters
buf source buffer of at least len bytes
len number of bytes to send
Throws
IOException if the underlying write fails.

#write

write(self, b : i32) : void ! IOException

Write the low 8 bits of b as one byte.

Parameters
b source value; only its low 8 bits are emitted

#writeBytes

writeBytes(self, buf : i8[], offset : i64, len : i64) : void ! IOException

Write buf[offset .. offset+len) to the peer, in chunks of at most
MAX_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.

Parameters
buf source buffer
offset first source index
len number of bytes to write
Throws
IOException if the underlying write fails.

#writeString

writeString(self, data : string) : void ! IOException

Write a string's UTF-8 bytes to the peer, in the same chunks.

Parameters
data text to send
Throws
IOException if the underlying write fails.

#flush

flush(self) : void ! IOException

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

close(self) : void ! IOException

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

TypeMethod and description
constructor(host : string, port : i32) Records the target endpoint; opens no connection. Call connect()
to perform the handshake.

Method detail

#constructor

constructor(host : string, port : i32)

Records the target endpoint; opens no connection. Call connect()
to perform the handshake.

Parameters
host hostname or IP literal of the peer
port TCP port (1..65535)

Methods

TypeMethod and description
void
connect(self) : void Performs the TCP three-way handshake to the recorded host/port.
Blocks until connected.
void
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.
void
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 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.
Future<void>
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).
Future<string>
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 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.
Future<void>
writeAsync(self, data : string) : Future<void> Flush every byte of data to the peer without blocking the
event loop.
SocketInputStream
getInputStream(self) : SocketInputStream 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.
SocketOutputStream
getOutputStream(self) : SocketOutputStream 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.
bool
isConnected(self) : bool Whether the underlying socket is currently connected.
string
getInetAddress(self) : string Resolved IP address of the remote peer, as a string.
i32
getPort(self) : i32 Remote port this socket is connected to.
void
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

connect(self) : void ! IOException

Performs the TCP three-way handshake to the recorded host/port.
Blocks until connected.

Throws
IOException if the host is unreachable or the connection
is refused

#setTimeoutMillis

setTimeoutMillis(self, millis : i32) : void ! IOException

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.

Parameters
millis deadline in milliseconds, or 0 for no deadline
Throws
IOException if the socket is not connected

#connectWithin

connectWithin(self, millis : i32) : void ! IOException

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.

Parameters
millis the deadline in milliseconds; 0 for the default
Throws
IOException if the name does not resolve or the peer refuses

#connectAsync

connectAsync(self) : Future<void> ! IOException

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

readAsync(self, max : i32) : Future<string> ! IOException, IllegalArgumentException

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.

Throws
IOException when the read fails or a close ends it
IllegalArgumentException when the received bytes hold a NUL

#writeAsync

writeAsync(self, data : string) : Future<void> ! IOException

Flush every byte of data to the peer without blocking the
event loop.

#getInputStream

getInputStream(self) : SocketInputStream ! IOException

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.

Throws
IOException if the socket is not connected or the handle
is invalid

#getOutputStream

getOutputStream(self) : SocketOutputStream ! IOException

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.

Throws
IOException if the socket is not connected or the handle
is invalid

#isConnected

isConnected(self) : bool

Whether the underlying socket is currently connected.

#getInetAddress

getInetAddress(self) : string

Resolved IP address of the remote peer, as a string.

#getPort

getPort(self) : i32

Remote port this socket is connected to.

#close

close(self) : void ! IOException

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 each
accept() blocks until an inbound connection arrives and returns it
as a connected Socket.

Constructors

TypeMethod and description
constructor(port : i32) Records the listen port; claims nothing until bind().

Method detail

#constructor

constructor(port : i32)

Records the listen port; claims nothing until bind().

Parameters
port TCP port to listen on (1..65535; 0 lets the OS pick)

Methods

TypeMethod and description
void
bind(self) : void Binds and starts listening on the recorded port.
Socket
accept(self) : Socket Blocks until an inbound connection arrives and returns it as a
connected Socket.
Future<Socket>
acceptAsync(self) : Future<Socket> Accept the next peer without blocking the event loop — the
future resolves to a connected Socket.
i32
getLocalPort(self) : i32 Local port actually bound (useful when the ctor port was 0).
void
close(self) : void Stops listening and releases the socket handle.

Method detail

#bind

bind(self) : void ! IOException

Binds and starts listening on the recorded port.

Throws
IOException if the port is already in use or denied

#accept

accept(self) : Socket ! IOException

Blocks until an inbound connection arrives and returns it as a
connected Socket.

#acceptAsync

acceptAsync(self) : Future<Socket> ! IOException

Accept the next peer without blocking the event loop — the
future resolves to a connected Socket.

#getLocalPort

getLocalPort(self) : i32

Local port actually bound (useful when the ctor port was 0).

#close

close(self) : void ! IOException

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

TypeMethod and description
InetAddress
getByName(self, host : string) : InetAddress Resolves host to an address. On failure the returned handle is
zero — detect via getHostAddress() == "".
InetAddress
getLocalHost(self) : InetAddress The local machine's primary address.
string
getHostName(self) : string Hostname associated with this address.
string
getHostAddress(self) : string Dotted/colon IP string, or empty if the address is unresolved.
bool
isReachable(self, timeoutMillis : i32) : bool Non-throwing for the same codegen reason — false on
unreachable or invalid handle.

Method detail

#getByName

getByName(self, host : string) : InetAddress

Resolves host to an address. On failure the returned handle is
zero — detect via getHostAddress() == "".

Parameters
host hostname or IP literal to resolve

#getLocalHost

getLocalHost(self) : InetAddress

The local machine's primary address.

#getHostName

getHostName(self) : string

Hostname associated with this address.

#getHostAddress

getHostAddress(self) : string

Dotted/colon IP string, or empty if the address is unresolved.

#isReachable

isReachable(self, timeoutMillis : i32) : bool

Non-throwing for the same codegen reason — false on
unreachable or invalid handle.

Parameters
timeoutMillis reachability probe timeout in milliseconds