Struct Net 

pub struct Net<'a> { /* private fields */ }

A handle to the network service.

Authority

Carries none of its own. Every call rides the caller’s existing send capability to net-stack, granted by its spawn request (a contract declares it as ipc_send = ["net-stack"], CLAUDE.md 13.6); a task granted none gets Error::Unreachable, exactly as for any peer it cannot reach. There is no ambient network (§3.1, and docs/networking.md says the same).

Implementations

impl<'a> Net<'a>

pub fn socket<'n>(&'n mut self) -> Result<Socket<'n, 'a>, Error>

Open a UDP socket and receive a CAPABILITY to it (7.10).

The returned Socket is the authority to send through one source port. It is minted by net-stack, validated by the kernel on every use, and revoked when net-stack restarts - at which point operations return Error::Revoked and you open another.

Blocks up to NET_SECS. Authority: the caller’s existing net-stack capability; opening a socket grants nothing the spawn request did not already grant.

Errors

• Error::Unavailable - net-stack would not open one. Usually no usable NIC.
• Error::Failed - it answered without a capability.
• Opening is idempotent from the caller’s side, so a no-answer error is safe to retry - though it may leave a socket behind in net-stack.

pub fn listen<'n>(&'n mut self, port: u16) -> Result<Listener<'n, 'a>, Error>

Listen on a TCP port and receive a CAPABILITY to the listener.

The returned Listener is the authority to accept connections on one port, and nothing else. net-stack refuses a port already listened on, so two programs cannot silently share one.

Blocks up to NET_SECS. Authority: the caller’s existing net-stack capability.

Errors

• Error::Unavailable - net-stack would not listen: the port is taken, the listener table is full, or there is no usable NIC. Its log says which.
• Error::Failed - it agreed and sent no capability.

pub fn connect<'n>( &'n mut self, ip: Ipv4, port: u16, ) -> Result<Stream<'n, 'a>, Error>

Open a TCP connection to ip:port and receive a CAPABILITY to it.

Unlike tcp, which is one request and one reply, the returned Stream is a conversation: send, read, send again, for as long as both ends keep it open. That is what a protocol with a handshake needs - TLS above all.

Blocks until the connection is established or refused, up to TCP_SECS. Authority: the caller’s existing net-stack capability; the connection’s capability grants only that one connection.

Errors

• Error::Unavailable - net-stack could not connect: no answer, refused, no usable NIC, or its connection table is full. Its log says which.
• Error::Failed - it agreed and sent no capability.

pub fn new(ctx: &'a ServiceContext) -> Net<'a>

Take a network handle. Cheap, allocates nothing, grants nothing.

pub fn with_notice(ctx: &'a ServiceContext, notice: &'a dyn Fn()) -> Net<'a>

A network handle that tells you when a call is taking a while.

notice is fired once, after a couple of seconds, if a request has not been answered. It takes nothing and returns nothing: it means only “this is lasting”. An interactive program prints [q] quit and starts watching the keyboard; a daemon might log it; most programs do not need it at all.

This exists because services/shell could not otherwise move onto this library without dropping that affordance on exactly the calls where a person needs it - a tcp to an unreachable host waits the full deadline in silence. Losing that would have been a regression dressed up as a migration.

pub fn keeping(self, keep: &'a dyn Fn(u8)) -> Net<'a>

Hand every key a noticing wait reads, other than a quit key, to keep, in order, instead of discarding it - as Fs::keeping does (backlog/fixed/80 H16).

pub fn watching(self, watch: &'a dyn Watch) -> Net<'a>

Lend this handle the command’s watch (call::Watch): every request then shows the command’s [q] quit once the COMMAND has run 2 s, and stops at the next request after a quit. Takes precedence over a notice; a watch that is not active leaves the handle’s own notice, if any, else the plain wait.

pub fn status(&mut self) -> Result<Status, Error>

What the machine currently believes about the network.

Blocks briefly. Read-only, so every no-answer failure is safe to retry.

pub fn resolve(&mut self, host: &str) -> Result<Ipv4, Error>

Resolve a hostname to an address. A host that is already an address, in dotted-quad (192.168.4.40), is that address, and no name server is asked: a resolver answers “no such name” for it, which made a link to a machine on the local network fail before it connected.

Blocks up to NET_SECS: this leaves the machine and a name server may be slow or absent. Read-only, so a retry is always safe.

Errors

Error::NotFound if the name does not resolve. Error::OutcomeUnknown if no answer arrives in time - harmless here, since resolving twice costs only time.

pub fn ping(&mut self, ip: Ipv4) -> Result<bool, Error>

Send one ICMP echo and wait for the reply.

Blocks up to NET_SECS. Returns true if the host answered.

A host that does not answer is Ok(false), not an error: silence is a legitimate result from a reachable network, and conflating it with “the request failed” is how a diagnostic tool starts lying about which half is broken.

pub fn arp(&mut self, ip: Ipv4) -> Result<Option<[u8; 6]>, Error>

Resolve one host’s MAC address on the local link.

Blocks. Ok(None) means nothing answered, which on a local link usually means the host is not there - again a result rather than a failure.

pub fn tcp( &mut self, ip: Ipv4, port: u16, request: &[u8], buf: &mut [u8], ) -> Result<usize, Error>

One whole TCP transaction: connect, send request, read the reply, close.

Writes the reply into buf and returns how many bytes landed there.

Blocks up to TCP_SECS. This one changes state on the far side: it is a request to somebody else’s server, and that server may act on it. On Error::OutcomeUnknown the request may have been delivered and acted upon, and re-sending it is a SECOND transaction - which for anything that is not a plain fetch is exactly the double-submit problem. Error::retry_is_safe answers false there for that reason.

Errors

Error::Failed if the connection could not be made or was closed with nothing returned.

pub fn renew(&mut self) -> Result<(), Error>

Re-run the address dance in place, for a link that came up after boot.

Blocks. Changes state: it may replace the machine’s address. On Error::OutcomeUnknown call status to find out what happened rather than renewing again.