Investigate bsdsocket.library support via host-socket passthrough

[sidick]

Summary

Look into implementing bsdsocket.library (the standard AmigaOS TCP/IP stack API, as popularized by AmiTCP/Genesis/Roadshow/Miami) using a host-socket passthrough design, rather than emulating a real guest-side TCP/IP stack (ARP/IP/TCP state machines, retransmission, etc.).

A real, working precedent: Copperline's hostsocket-plugin

Copperline (the cycle-exact Amiga emulator this project already uses for ground-truth testing) has a real, conformance-tested bsdsocket.library implementation at crates/hostsocket-plugin in its own repo, and it already offers exactly this as a second transport option alongside its default embedded smoltcp TCP/IP stack:

• Default transport (net = "loopback"/"nat"/"bridge"): a full embedded smoltcp IP stack running inside the plugin, chosen because Copperline needs cycle-exact, byte-for-byte-deterministic emulation -- a real host socket's timing isn't reproducible, so the guest-visible network stack has to be simulated in full.
• Host-socket backend ([config] transport = "host"): bypasses smoltcp entirely and proxies TCP/UDP socket calls straight onto real host OS sockets via a small, explicit set of host imports: sock_open/connect/send/recv/poll/close/bind/listen/accept/local_addr/peer_addr/sendto/recvfrom/setopt/getopt/dup/shutdown/peek/nread/send_oob/recv_oob. This is the "Amiberry-style" option the plugin's own doc comments name it after -- i.e. the same non-deterministic-but-simple passthrough approach other emulators use.

volamos doesn't have Copperline's determinism constraint (it's not trying to be cycle-exact or reproducible in that sense), so the host-socket backend -- not the embedded-stack default -- is the directly applicable model: implement bsdsocket.library's LVOs by translating each call onto Rust's std::net/mio, the same shape as Copperline's sock_* host-import boundary, without ever needing an embedded TCP/IP stack at all.

Concretely worth reading before starting:

• crates/hostsocket-plugin/src/lib.rs's HostFdSlot/Board::host_backend section (search // -- Host-socket backend) -- the design rationale for keeping this a small, separate code path rather than folding it into the smoltcp-backed fd table: "every unimplemented call ... is simply absent from fds, so fd_index reports it as no-such-descriptor (ENOTSOCK/EBADF) exactly like any other invalid fd, with no risk to the existing [default] path at all." Same incremental, low-risk shape volamos's own library-gap work already follows (implement what's needed, fail cleanly/honestly on what isn't).
• crates/hostsocket-plugin/docs/bsdsocktest-status.md -- a real conformance record against the external bsdsocktest suite. The host backend passes 126/142 (loopback tier); the remaining gaps are documented and instructive for scoping a first volamos pass: shutdown(), MSG_PEEK, sendmsg/recvmsg, FIONREAD, SO_EVENTMASK/GetSocketEvents, and a partial MSG_OOB (out-of-band) gap. Worth pulling this same test suite into volamos's own test flow once there's something to test.

Open questions to research before implementing

• Which bsdsocket.library version/API surface to target (original AmiTCP 4.x bsdsocket.library LVOs vs. later Roadshow extensions) -- check the NDK/FD files for the LVO table and exact register conventions (the ndk32-autodocs skill, or amitools' fd/ directory).
• How guest struct sockaddr_in/hostent/etc. layouts (big-endian, Amiga struct packing) map onto host equivalents -- probably a straightforward byte-order/field-order translation layer, similar to how dosfile.rs already translates AmigaDOS structures to host I/O. Copperline's sock_* ABI already made these decisions (e.g. ip/port as plain i32s at the host-import boundary) and is a ready reference.
• Blocking semantics: real bsdsocket.library calls can block the calling task; volamos is currently single-tasking/synchronous (per crate::exectask's scope). Copperline's Phase 2 replaced an initial guest-side busy-spin with real Wait/Signal-based blocking via a guest-installed interrupt server -- worth understanding before deciding volamos's own approach (a plain blocking host call may be simpler and sufficient for a single-tasked guest).
• WaitSelect/select() multiplexing across multiple sockets and/or Exec signals.
• Any corpus binary that would actually exercise this (AmiTCP-era CLI tools, an FTP/telnet client, etc.) to validate against, similar to how other library work in this project has been grounded against real Aminet binaries rather than guesswork.
• Sandboxing/security implications of giving guest code real host network access -- worth a deliberate opt-in decision before this ships, unlike e.g. filesystem access which is already opt-in via -V/-a.

Scope

Research/design only for now -- no implementation plan committed yet. Copperline's hostsocket-plugin (specifically its host-backend transport, not its default smoltcp stack) is the closest real precedent and worth reading in full before designing volamos's own approach.

[sidick]

Appendix: the actual host-side reference code

Went deeper into Copperline's source (src/wasmboard.rs, not just the plugin crate) to find the real implementation of the sock_* host imports -- this is the directly reusable part, since it's already plain Rust with no WASM-specific concerns except the Caller/linear-memory plumbing volamos doesn't need at all (volamos's LVO handlers already run natively, with direct &mut dyn AddressSpace access -- no host/guest memory-copy boundary to cross).

Crate: socket2 (use socket2::{Domain, SockAddr, Socket, Type};). Every socket is opened non-blocking immediately and stays that way:

// sock_open(domain, type_) -> handle or -errno
let socket = Socket::new(Domain::IPV4, Type::STREAM /* or Type::DGRAM */, None)?;
socket.set_nonblocking(true)?;
// store in a HashMap<i32, Socket>, hand back the key as the "handle"

// sock_connect(handle, ip, port) -> 0 | -EINPROGRESS | -errno
let addr = SocketAddr::V4(SocketAddrV4::new(Ipv4Addr::from((ip as u32).to_be_bytes()), port as u16));
match socket.connect(&SockAddr::from(addr)) {
    Ok(()) => Ok(0),
    Err(e) if is_connect_in_progress(&e) => Ok(-EINPROGRESS),
    Err(e) => Ok(-translate_errno(&e)),
}

ip/port are carried as a big-endian-packed i32 everywhere in this ABI -- worth keeping as the convention if volamos follows this shape, since it maps 1:1 onto a real Amiga struct sockaddr_in's own big-endian s_addr/sin_port fields with no extra byte-swapping.

sock_send/sock_recv are plain non-blocking Socket::write/Socket::read, returning a byte count, 0 at EOF (recv only), or -errno (-EAGAIN when it would block -- there's no separate blocking mode; see the plan doc's note on how the guest's own retry-loop or Wait/Signal blocking supplies that instead, not the socket itself).

sock_poll(handle) -> bitmask is the one piece with no portable socket2 equivalent (no cross-platform poll()/select() in that crate) -- Copperline's own comment on it:

socket2 has no portable select()/poll(), so this approximates the same way a caller without an event loop would: a zero-consuming MSG_PEEK for readability (true at EOF too, same as a real socket), and take_error() + peer_addr() for connect-completion.

Bitmask: bit 0 readable, bit 1 writable, bit 2 error-pending, bit 3 peer-hangup (set alongside bit 0, so a caller distinguishing "real data" from "EOF" without consuming anything can, needed for GetSocketEvents()'s FD_CLOSE edge). Their own comment flags a real poll()-backed wakeup (so an interrupt fires the instant a socket is ready, rather than only when the guest happens to re-poll) as later, unimplemented work -- worth deciding upfront whether volamos needs that or whether guest-retry-driven polling (what they shipped first) is good enough for a first pass.

sock_bind/sock_listen/sock_accept are plain non-blocking BSD bind()/listen()/accept() through the same Socket type, sock_close just drops the HashMap entry (no-op on an unknown handle -- the plugin's own fd table, not this layer, is where "closing twice is an error" gets enforced, worth mirroring: keep this host-socket layer itself forgiving, put real-AmigaOS-shaped error behavior in the LVO-handler layer above it).

Errno translation -- prefers the real host OS errno when available, only falls back to a std::io::ErrorKind guess otherwise:

fn translate_errno(e: &std::io::Error) -> i32 {
    if let Some(code) = e.raw_os_error().and_then(from_raw_errno) {
        return code;
    }
    use std::io::ErrorKind::*;
    match e.kind() {
        WouldBlock => EAGAIN,
        ConnectionRefused => ECONNREFUSED,
        ConnectionReset => ECONNRESET,
        NotConnected => ENOTCONN,
        TimedOut => ETIMEDOUT,
        AddrInUse => EADDRINUSE,
        BrokenPipe => EPIPE,
        _ => EIO,
    }
}

from_raw_errno maps a host OS errno to the fixed BSD numbering bsdsocket.library itself documents (Amiga programs read these via Errno()/SetErrnoPtr(), not the host's own /usr/include/sys/errno.h numbering, which differs by platform) -- this table would need porting verbatim; it's the one piece genuinely specific to matching real AmigaOS behavior rather than just wrapping a Rust API.

Resource bound: MAX_OPEN_HOST_SOCKETS: usize = 64 -- a plain cap on the handle table, returning -EMFILE past it. Worth having some such cap in volamos too (unbounded socket creation from guest code is an easy accidental-DoS vector even without adversarial intent).

Suggested volamos shape

Given volamos's existing module conventions (crate::dosfile's DosState, crate::execmem's heap-backed allocator, etc.), the natural fit is a new crate::bsdsocket module:

• BsdSocketState { sockets: HashMap<i32, socket2::Socket>, next_id: i32 }, living on DosState or its own top-level Runtime field the same way DosState/GuestHeap already do.
• LVO handlers translate guest struct sockaddr_in/pointers directly against ctx.mem (no linear-memory-copy step needed at all, unlike the WASM boundary Copperline's plugin has to cross) and call straight into the socket2-based primitives above.
• Blocking: decide early whether a first pass just does real blocking host calls (simplest, matches this runtime's already-synchronous single-tasking model) versus non-blocking + guest retry/Wait-Signal (what Copperline ended up needing, but only because it has real concurrent guest tasks and interrupts to integrate with -- volamos may not need that complexity at all for its own use cases).

Still research/design only -- no code written yet. This appendix is meant to make picking this up later a "port this shape" task rather than a "figure out the shape" task.

[sidick]

Appendix 2: the real bsdsocket.library LVO table and struct layouts

Pulled from a real Roadshow NDK bundle (`~/Downloads/ndk32/SANA+RoadshowTCP-IP/`) -- `bsdsocket_lib.fd` (via amitools' bundled copy, identical content) for the LVO table, `sys/socket.h`/`netinet/in.h` for the wire structs. This replaces guesswork with the actual register conventions.

LVO table (bias 30, i.e. `socket` is the first function; standard -6-per-entry spacing)

The core set Copperline's `hostsocket-plugin` host backend implements (see appendix 1) is a subset of this -- worth using as the prioritization order for a first volamos pass, skipping the rest (`bpf_*`, routing, network-monitor hooks -- a separate `##bias 366`/`432` block in the .fd, clearly optional/advanced):

```
-30 socket(domain,type,protocol) d0/d1/d2
-36 bind(sock,name,namelen) d0/a0/d1
-42 listen(sock,backlog) d0/d1
-48 accept(sock,addr,addrlen) d0/a0/a1
-54 connect(sock,name,namelen) d0/a0/d1
-60 sendto(sock,buf,len,flags,to,tolen) d0/a0/d1/d2/a1/d3
-66 send(sock,buf,len,flags) d0/a0/d1/d2
-72 recvfrom(sock,buf,len,flags,addr,addrlen) d0/a0/d1/d2/a1/a2
-78 recv(sock,buf,len,flags) d0/a0/d1/d2
-84 shutdown(sock,how) d0/d1
-90 setsockopt(sock,level,optname,optval,optlen) d0/d1/d2/a0/d3
-96 getsockopt(sock,level,optname,optval,optlen) d0/d1/d2/a0/a1
-102 getsockname(sock,name,namelen) d0/a0/a1
-108 getpeername(sock,name,namelen) d0/a0/a1
-114 IoctlSocket(sock,req,argp) d0/d1/a0
-120 CloseSocket(sock) d0
-126 WaitSelect(nfds,readfds,writefds,exceptfds,timeout,signals) d0/a0/a1/a2/a3/d1
-132 SetSocketSignals(int_mask,io_mask,urgent_mask) d0/d1/d2
-138 getdtablesize() (none)
-144 ObtainSocket(id,domain,type,protocol) d0/d1/d2/d3
-150 ReleaseSocket(sock,id) d0/d1
-156 ReleaseCopyOfSocket(sock,id) d0/d1
-162 Errno() (none)
-168 SetErrnoPtr(errno_ptr,size) a0/d0
-174 Inet_NtoA(ip) d0
-180 inet_addr(cp) a0
-186 Inet_LnaOf(in) d0
-192 Inet_NetOf(in) d0
-198 Inet_MakeAddr(net,host) d0/d1
-204 inet_network(cp) a0
-210 gethostbyname(name) a0
-216 gethostbyaddr(addr,len,type) a0/d0/d1
-222 getnetbyname(name) a0
-228 getnetbyaddr(net,type) d0/d1
-234 getservbyname(name,proto) a0/a1
-240 getservbyport(port,proto) d0/a0
-246 getprotobyname(name) a0
-252 getprotobynumber(proto) d0
-258 vsyslog(pri,msg,args) d0/a0/a1
-264 Dup2Socket(old_socket,new_socket) d0/d1
-270 sendmsg(sock,msg,flags) d0/a0/d1
-276 recvmsg(sock,msg,flags) d0/a0/d1
-282 gethostname(name,namelen) a0/d0
-288 gethostid() (none)
-294 SocketBaseTagList(tags) a0
-300 GetSocketEvents(event_ptr) a0
```

(All arithmetic re-derived and verified from the real `.fd` line order, not eyeballed -- `bias 30` + 6 per subsequent entry, standard AmigaOS LVO spacing.)

The wire structs (Roadshow's own headers, real byte layout)

`struct sockaddr` (`sys/socket.h`) -- note this is 4.3BSD-style with `sa_len`, not the older 4.2BSD sockaddr some very old Unix ports assume:
```c
struct sockaddr {
UBYTE sa_len; /* total length /
sa_family_t sa_family; / address family, 1 byte /
UBYTE sa_data[14]; / address value /
}; / 16 bytes total */
```

`struct sockaddr_in` follows the same 16-byte shape (standard BSD layout, consistent with the `sa_len`-prefixed `sockaddr` above -- not separately present as a distinct header file in this particular NDK snapshot, but implied and universally standardized):
```c
struct sockaddr_in {
UBYTE sin_len; /* 16 /
sa_family_t sin_family; / AF_INET = 2 /
in_port_t sin_port; / network byte order (big-endian) /
struct in_addr sin_addr; / 4 bytes, network byte order /
char sin_zero[8]; / padding to 16 bytes */
};
```
`struct in_addr { in_addr_t s_addr; }` -- just a 4-byte wrapper, `AF_INET = 2`, `SOCK_STREAM = 1`, `SOCK_DGRAM = 2` (matches what Copperline's `sock_open` already hard-codes).

Gotcha worth flagging now: `sys/socket.h`'s own comment says AmigaOS `struct timeval` (used by `WaitSelect`'s `timeout` and `SO_RCVTIMEO`/`SO_SNDTIMEO`) is `<devices/timer.h>`'s struct, whose fields are named `tv_secs`/`tv_micro` -- not POSIX's `tv_sec`/`tv_usec` -- the netinclude headers `#define tv_sec tv_secs` themselves to paper over it for C callers, but a from-scratch volamos implementation reading this struct out of guest memory needs to use the real Amiga field layout/names, not assume POSIX naming lines up.

`WaitSelect`'s `signals` parameter (`D1`): takes an Exec signal mask directly -- confirms the earlier open question about blocking/concurrency: even `WaitSelect` itself (not just plain blocking `recv`) is documented to integrate with Exec's `Wait()`/signal mechanism (a caller can `WaitSelect` on socket readiness and an arbitrary signal simultaneously, waking on whichever comes first) -- this is a real, load-bearing part of the LVO contract, not an incidental detail, so a "just block the host thread" first pass would need to at least accept and honor this parameter's shape even if it doesn't do real multi-signal waiting yet (e.g. treat a nonzero `signals` as an immediate small polling loop rather than silently ignoring it).

This should now be enough to write real LVO table code (`crate::lvos::bsdsocket`, mirroring every other library's `LvoEntry` table in this codebase) as a first concrete step, whenever this gets picked up.

[sidick]

Implemented (a first, real slice) -- commit 34b0a5f

Went ahead and implemented this rather than leaving it as research. Real, working bsdsocket.library via host-socket passthrough:

• New: crates/volamos-core/src/bsdsocket.rs (handlers, using socket2) + crates/volamos-core/src/lvos/bsdsocket.rs (LVO table, hand-transcribed from the real Roadshow .fd referenced above).
• Implemented LVOs: socket/bind/listen/accept/connect/send/recv/sendto/recvfrom/shutdown/getsockname/getpeername/CloseSocket/getdtablesize/Errno/SetErrnoPtr/Inet_NtoA/inet_addr -- real outbound and inbound TCP, plus UDP, real error reporting.
• Not yet implemented (traps as an ordinary unknown-call, same as any other library's gap in this codebase): setsockopt/getsockopt, WaitSelect/SetSocketSignals (needs a real design decision on Exec-signal integration -- see the module docs), gethostbyname/DNS, Dup2Socket/ObtainSocket/ReleaseSocket, sendmsg/recvmsg/vsyslog/SocketBaseTagList/GetSocketEvents.
• Opt-in, not always-on: unlike every other real library this runtime implements, bsdsocket.library is only registered via Runtime::enable_bsdsocket(), wired to a new CLI --net flag (deliberately CLI-only, not settable via ~/.volamos) -- matches the "real network access needs deliberate opt-in" point raised earlier in this issue, and mirrors how filesystem access is already opt-in via -V/-a.
• Verified for real: a genuine UDP bind()+getsockname() round trip against an OS-assigned ephemeral port, and a real non-blocking TCP connect() against a live local HTTP server -- not just unit-level mocking.

Leaving this issue open to track the remaining LVO surface (WaitSelect in particular is real, load-bearing work, not a quick add) rather than closing it as fully done.

[sidick]

gethostbyname implemented -- commit ba61fb0

Real forward DNS via `std::net`'s `(name, 0u16).to_socket_addrs()` (the host's own resolver, blocking call -- no async dance needed since this runtime's handlers already run synchronously, unlike Copperline's WASM-hosted plugin). Builds a real `struct hostent` (confirmed Roadshow `<netdb.h>` layout) plus its name/alias/address allocations on the guest heap, freed and rebuilt on each call per the real "reused static buffer" contract. Failures report `HOST_NOT_FOUND`/`TRY_AGAIN` through the same `Errno()` channel -- a real AmigaOS quirk (h_errno has no dedicated LVO, it's read back through `Errno()` on real hardware too), not a shortcut.

Verified with two real lookups: `"localhost"` through the actual host resolver, and a guaranteed-unresolvable `.invalid` name failing cleanly.

`gethostbyaddr` (reverse/PTR) stays unimplemented -- `std::net` has no portable reverse-DNS primitive, same wall Copperline's own implementation hit.

Remaining scope: `setsockopt`/`getsockopt`, `WaitSelect`/`SetSocketSignals`, `Dup2Socket`/`ObtainSocket`/`ReleaseSocket`, `sendmsg`/`recvmsg`/`vsyslog`/`SocketBaseTagList`/`GetSocketEvents`.