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 |
|---|---|
| maxWriteBytes() : i64 Most bytes one native write can be handed. The count crosses the FFI as an i32, so a larger one does not fail —it wraps, and the two ways it lands are both silent: a count that comes out negative writes nothing at all, and one that comes out positive writes a prefix and reports success. Refusing above the bound is what turns either into an error the caller can see. |
| 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
#maxWriteBytes
Most bytes one native write can be handed.
The count crosses the FFI as an i32, so a larger one does not fail —
it wraps, and the two ways it lands are both silent: a count that
comes out negative writes nothing at all, and one that comes out
positive writes a prefix and reports success. Refusing above the bound
is what turns either into an error the caller can see.
#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 |
| writeString(self, data : string) : void |
Method detail
#readBytes
#writeString
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 |
| readInto(self, buf : ptr, max : i32) : i32 |
| read(self) : i32 |
| readBytes(self, buf : i8[], offset : i64, len : i64) : i64 |
| skip(self, n : i64) : i64 |
| available(self) : i64 |
| readString(self, max : i32) : string |
| close(self) : void |
Method detail
#rawHandle
#readInto
#read
#readBytes
#skip
#available
#readString
#close
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 |
| writeFrom(self, buf : ptr, len : i32) : void |
| write(self, b : i32) : void |
| writeBytes(self, buf : i8[], offset : i64, len : i64) : void |
| writeString(self, data : string) : void |
| flush(self) : void |
| close(self) : void |
Method detail
#rawHandle
#writeFrom
#write
#writeBytes
#writeString
#flush
#close
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 |
| setTimeoutMillis(self, millis : i32) : void |
| connectWithin(self, millis : i32) : void |
| connectAsync(self) : Future<void> |
| readAsync(self, max : i32) : Future<string> |
| writeAsync(self, data : string) : Future<void> |
| getInputStream(self) : SocketInputStream |
| getOutputStream(self) : SocketOutputStream |
| isConnected(self) : bool |
| getInetAddress(self) : string |
| getPort(self) : i32 |
| close(self) : void |
Method detail
#connect
#setTimeoutMillis
#connectWithin
#connectAsync
#readAsync
#writeAsync
#getInputStream
#getOutputStream
#isConnected
#getInetAddress
#getPort
#close
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 |
| accept(self) : Socket |
| acceptAsync(self) : Future<Socket> |
| getLocalPort(self) : i32 |
| close(self) : void |
Method detail
#bind
#accept
#acceptAsync
#getLocalPort
#close
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 |
| getLocalHost(self) : InetAddress |
| getHostName(self) : string |
| getHostAddress(self) : string |
| isReachable(self, timeoutMillis : i32) : bool |