Module Eio_net_memSource

In-memory Eio.Net network.

For hermetic tests: client and server code talk through Eio.Net without binding OS sockets, over stream and datagram sockets. Each call to v makes a network of its own: two of them share no socket. The library eio-net.chaos tests programs and networks with it.

Where Linux, macOS and Windows differ, the network follows one, chosen by ?os: `Linux, the default, `Macos or `Windows. The choice comes from the argument, never from the host, so a test sees the same network on every machine. macOS lists what `Macos changes and Windows what `Windows changes. Its answers are those recorded on Linux, macOS and Windows, and Eio_net_chaos.conformance checks them.

Errors

A bind that fails in listen or datagram_socket raises the Eio.Io error eio_posix raises there, carrying Eio_unix.Unix_error, so that one handler serves both: EADDRINUSE, EADDRNOTAVAIL or EINVAL from "bind", and ENAMETOOLONG with the path for a Unix path sun_path cannot hold. A socket option the kernel refuses raises the error eio_posix raises (Socket options). Every other error is an Eio.Io error marked by one of these codes, unclassified unless the code's doc names its class. Below, "raises Closed" means raises the Eio.Io error marked by Closed, and likewise for each code.

Sourcetype Eio.Exn.Backend.t +=
  1. | Closed
    (*

    The backend code carried by the connection reset a mem flow raises, where a TCP socket raises one:

    • A write after this end shut its send, an empty one included, as eio_posix sends it with sendmsg(2). On TCP the write reports a pending reset, so a read after it returns end of file.
    • A write after the peer closed: the first is lost and answered with a reset, which every later write raises; reads keep returning end of file, which came first. On a Unix-domain connection the first write raises the reset, as EPIPE.
    • A read, once the queued bytes are read, and a write after the peer closed with bytes of ours unread.
    • A read and a write on a connection its listener closed before accepting it.
    • A write to a TCP peer that shut down both ways: the first is lost and resets the connection, as Linux resets it then, so the peer's next read raises the reset and every later write does. A write to a full queue waits, as Linux holds data the peer's window refuses and the peer's reads free no room, until the peer closes.
    • A write on a Unix-domain connection whose peer shut its receive side, as EPIPE. One that waits on a full queue raises it once its own end shuts its send side or the peer shuts its receive side, as a blocking write(2) on Linux and eio_linux do; eio_posix keeps waiting, as Linux's poll(2) reports no change then.

    The first read or write that raises the reset reports it, as a socket clears its pending error: reads after it raise End_of_file, and writes keep raising the reset. On a Unix-domain connection only a read reports it: a write raises the reset as EPIPE and leaves it to the next read.

    A read after the peer closed or shut its send otherwise raises End_of_file once the queued bytes are read. A read after this end shut its receive side returns the bytes queued, and raises End_of_file once none is; under `Macos it drops them and raises End_of_file at once. As Linux then advertises no more room to the writer, what it reads frees none: a writer waiting on a full queue keeps waiting, and the bytes it writes into room left at the shutdown arrive and are read too. A read into an empty buffer raises End_of_file, as Eio's backends do. On TCP, a write after the peer shut its receive side, and only that, is queued and read in the same way. A read, a write or a shutdown on a flow after its own close raises Invalid_argument, as Eio's own sockets do. One already in flight finishes against the open socket, and the socket closes once none is, as Eio defers a descriptor's close to its users: a read waiting across its flow's close still gets what the peer writes.

    *)
  2. | No_listener
    (*

    The backend code carried by the connection failure connect raises when no listener is bound at a TCP address, or the listener closes while the connection waits for it, or at a Unix path a client is bound at, as a real socket raises Connection_failure (Refused _), and of the one a datagram send raises at an abstract address no socket of its type binds. It is also the code of the Eio.Fs.Not_found error a connect or a datagram send raises at a Unix path no socket binds, which has no file.

    *)
  3. | Address_in_use
    (*

    The code of the error a connect bound with bind_to raises at an address a socket holds, or at port 0 when every port of the dynamic range is held, where bind(2) fails with EADDRINUSE. A connect that fails holds the address it was bound at until its switch finishes, as eio_posix keeps its socket there and Linux its address; under `Macos a TCP one is free at once, as macOS frees it. listen and datagram_socket raise eio_posix's error instead (Errors).

    *)
  4. | No_destination
    (*

    The code of the error a UDP send without a destination raises, as a socket that is not connected fails it with EDESTADDRREQ.

    *)
  5. | Message_too_long
    (*

    The code of the error a datagram send raises for a datagram longer than a socket sends, where a socket fails with EMSGSIZE.

    *)
  6. | Invalid_port
    (*

    The code of the error a datagram send to UDP port 0 raises, where Linux fails it with EINVAL.

    *)
  7. | Network_unreachable
    (*

    The code of the error a connect bound to an IPv6 address raises at an IPv4-mapped one, and a datagram send from such a socket, where Linux fails with ENETUNREACH; and of the one a connect to a broadcast or multicast address raises, which no route reaches. The network has the loopback interface only, so a connect or a datagram send to an address off it raises it too, as on a host with loopback only, from any source: any but 127.0.0.0/8, ::1, the wildcard addresses and their IPv4-mapped forms, IPv4 multicast and broadcast aside. An IPv4-compatible address such as ::127.0.0.1 and an IPv6 multicast one are off it. A datagram to an IPv4 broadcast or multicast address from a socket bound at a wildcard address raises it too, as that socket has no route to send it. From an IPv4-mapped address, a connect or a datagram to an IPv6 address off loopback raises it before Address_family, as Linux finds no route first, and a connect to a link-local one raises Invalid_address.

    *)
  8. | Address_family
    (*

    The code of the error a connect bound to an IPv4-mapped address raises at an IPv6 one, and a datagram send from such a socket, where a socket fails with EAFNOSUPPORT.

    *)
  9. | Wrong_socket_type
    (*

    The code of the error a datagram send raises at the path of a stream socket, and a connect at the path of a datagram socket, where a socket fails with EPROTOTYPE.

    *)
  10. | Not_connected
    (*

    The code of the error a Unix-domain datagram send without a destination raises, as Linux fails it with ENOTCONN. Under `Macos the send raises No_destination, as macOS says EDESTADDRREQ.

    *)
  11. | Address_not_available
    (*

    The code of the error a connect with bind_to raises at an IP address no interface has, where bind(2) fails with EADDRNOTAVAIL; listen and datagram_socket raise eio_posix's. A connect without bind_to raises it when no port of the dynamic range is free toward its destination (Streams), as connect(2) fails on Linux. The network has the loopback interface only: an IPv4 socket binds an address of 127.0.0.0/8, the broadcast address or a multicast one, an IPv6 one ::1, either the wildcard address of its family, and an IPv6 one the IPv4-mapped form of those IPv4 addresses, as on Linux.

    *)
  12. | Name_too_long
    (*

    The code of the error raised for a Unix path of 108 bytes or more, which Linux's sun_path cannot hold with its NUL, where OCaml's Unix fails with ENAMETOOLONG: by connect, bind_to and a datagram send. listen and datagram_socket raise eio_posix's.

    *)
  13. | Invalid_address
    (*

    The code of the error a connect raises when its socket cannot bind the address bind_to gives: an IPv4 one for an IPv6 destination, or an IP one for a Unix path, where bind(2) fails with EINVAL on Linux, or binds a link-local IPv6 address, or a multicast one of interface or link scope, which needs a scope that Eio's addresses do not carry, or any IPv6 multicast one; listen and datagram_socket raise eio_posix's. It is also the code of the one a connect raises at a link-local address or at the empty Unix path; and of the one a datagram send raises at an address its socket cannot send to, described in Datagrams.

    *)
  14. | Broadcast
    (*

    The backend code of the Eio.Fs.Permission_denied error a datagram send raises at 127.255.255.255, the broadcast address of loopback's network, or at 255.255.255.255 from a socket bound at a loopback address, where Linux fails it with EACCES as the socket has no SO_BROADCAST. The network refuses it whatever SO_BROADCAST says.

    *)
  15. | Host_unreachable
    (*

    The code of the error raised under `Macos where macOS finds no route to a host, with EHOSTUNREACH: a connect to a link-local address, and the datagram sends Datagrams lists.

    *)
  16. | Exclusive_address
    (*

    The backend code of the Eio.Fs.Permission_denied error raised under `Windows by a bind with reuse_addr at an address a socket without it holds, where Windows fails it with WSAEACCES.

    *)
  17. | Shut_down
    (*

    The code of the error a read raises under `Windows once its end shut its receive side, where Windows fails it with WSAESHUTDOWN.

    *)

Networks

Sourceval v : ?os:[< `Linux | `Macos | `Windows ] -> ?capacity:int -> clock:_ Eio.Time.Mono.t -> sw:Eio.Switch.t -> unit -> [ `Generic ] Eio.Net.ty Eio.Resource.t

v ~os ~capacity ~clock ~sw () is a network following the kernel os (defaults to `Linux) whose listen and connect operations are paired in memory, whose datagram sockets deliver to each other, and whose TCP timers run on clock. Streams, Datagrams and Unix paths say how its sockets behave. Host resolution says how getaddrinfo and getnameinfo answer.

Each direction of a connection queues at most capacity bytes: a write takes what fits and waits while the queue is full, as a socket's send buffer makes it wait, so a test with a small capacity shows a peer that writes without reading. It defaults to 4 MiB over TCP and 256 KiB over a Unix path, at least what Linux's default buffers hold on loopback: a writer queues about 2.6 MiB over TCP before it waits, and at most about 250 KiB over AF_UNIX, less in small writes. Under `Macos it defaults to 1 MiB over TCP, what macOS's buffers grow to on loopback from about 330 KiB, and 8 KiB over AF_UNIX, as macOS holds. A capacity is what every connection queues, over TCP and over a Unix path, above the default too, and it bounds what a socket's send and receive buffers give (Socket options).

The end of a TCP connection whose FIN went first holds its address in TIME_WAIT for 60 seconds, as Linux holds it (Streams), or 30 seconds under `Macos.

Each end of a TCP connection gone silent (Private.silence) gives up on its peer as Linux does, measured over loopback. With SO_KEEPALIVE and no byte unacknowledged, it probes once TCP_KEEPIDLE has passed since the last segment it received. Its probes go TCP_KEEPINTVL apart, and it gives up one interval after the TCP_KEEPCNTth, or with TCP_USER_TIMEOUT at the first probe that long after that segment. A byte it sent unacknowledged stops the probes, and ends the connection TCP_USER_TIMEOUT later, or 948.6 seconds later, as tcp_retries2 at 15 does. The first read or write then raises ETIMEDOUT; later reads return end-of-file and writes raise EPIPE. With no keepalive and nothing unacknowledged, a wait on it lasts for ever.

Sourceval pair : ?os:[< `Linux | `Macos | `Windows ] -> ?capacity:int -> unit -> [ `Generic ] Eio.Net.stream_socket_ty Eio.Resource.t * [ `Generic ] Eio.Net.stream_socket_ty Eio.Resource.t

pair ~os ~capacity () is a connected pair of in-memory stream sockets, following the kernel os (defaults to `Linux): bytes written on one are read on the other, and vice versa, preserving order. Each direction queues at most capacity bytes (defaults to 4 MiB), as for v. Unlike v it binds no address and needs no listen and connect handshake: it is the bare transport for a test, or a wrapper such as an adversarial flow, that needs two connected ends. Its ends take socket options as a connection of v does. Blocking reads suspend the calling fiber until data arrives, so both ends must run under an Eio event loop; the two ends may be in different domains. No switch closes them: the caller does.

Streams

Stream sockets follow Linux, and Eio's own sockets where Eio decides: a use after close raises Invalid_argument, and a close waits for the calls already in flight. macOS lists what `Macos changes.

Listening

Connecting

Connections

Held addresses

Ports of a connect

Connecting from a bound address

Socket options

setsockopt, getsockopt and the options of a connect take every option Eio.Net.Sockopt names, and the Unix options of Eio_unix.Net, on every socket, and answer as the chosen kernel does on a host with loopback only, as recorded through eio_posix:

Datagrams

Datagram sockets follow Linux. macOS lists what `Macos changes.

Binding

Delivery

Shutdown

Errors of a send

Unix paths

Listeners, datagram sockets and clients bound with bind_to share one namespace of Unix paths, as they share a file system: a path one holds is in use to the others. A connect at a datagram socket's path raises Wrong_socket_type, and so does a datagram sent to a listener's or a client's path. A connect or a datagram sent at a path no socket holds raises Eio.Fs.Not_found.

The namespace is not a file system: a socket binds a path whose directory does not exist, or that it may not write, where a real socket fails with ENOENT or EACCES, since modelling them would need the file system the path names. A path with a NUL past its first byte names no file, as OCaml's Unix refuses it: listen, datagram_socket, connect, bind_to and a datagram send raise Eio.Fs.Not_found. A path of 108 bytes or more raises ENAMETOOLONG, or Name_too_long (Errors).

With reuse_addr, a listen at a Unix-domain path, not at an abstract address, takes the path over, as Eio's backends remove the socket file there before they bind: the listener that held it stays open, and no connect reaches it. A listener or a datagram socket removes its file as it closes, by hand or with its switch, as Eio's backends do: a connect or a datagram sent there then raises Eio.Fs.Not_found, and a socket may bind the path again. A listener whose path was taken over removes the new listener's file as it closes, as unlink(2) removes whichever file is there, and no connect reaches either.

A listener, a datagram socket or a client bound with bind_to at the empty path binds an abstract address of its own, a NUL and five hexadecimal digits, as Linux autobinds it: listening_addr reports it, an accept sees it as its client's address, and a reply sent there reaches it. An address that starts with a NUL is in Linux's abstract namespace, which has no files: a socket there leaves nothing behind when it closes. The namespace is one per socket type, as on Linux: a stream socket and a datagram one may bind the same abstract address, and a connect or a datagram sent where no socket of its type binds raises No_listener.

Host resolution

Host resolution reads numbers as glibc's getaddrinfo(3) does, on a dual-stack host with no services database and no name server. The service is read first: as strtoul(3) reads it in base 10, the whole string, with leading spaces and a sign, the empty one as 0, kept to its low 32 bits and taken modulo 65536; a negative one, or any other string, raises Address_lookup_failed SERVICE, service names such as "http" included. The host is an IPv4 address as inet_aton(3) reads it ("127.1", "0x7f.1"), an IPv6 one without brackets, which may name a scope after a % as glibc takes one, a number of 32 bits or, for a link-local address or a multicast one of interface or link scope, "lo", the only interface; or "localhost" in any case, or the empty name, the last two standing for ::1 then 127.0.0.1. Any other name, "localhost." included, maps to no address, as /etc/hosts does not hold it and there is no name server to ask, and so do an empty host and service; a host with a name server may resolve it. Each address comes once as a stream address and once as a datagram one. On a real system the loopback order, and whether IPv6 addresses come at all, depend on the host's addresses and its /etc/hosts: glibc leaves them out on a host with no IPv6 address but loopback, and turns "localhost"'s ::1 into 127.0.0.1. The order here is glibc's on a dual-stack host, ::1 before 127.0.0.1 and each address as a stream one before a datagram one, fixed so that a test sees the same addresses everywhere. Under `Macos each address comes as a datagram one first, as macOS orders them.

getnameinfo names 127.0.0.1, IPv4-mapped, IPv4-compatible (::7f00:1) or neither, and ::1 "localhost", as /etc/hosts does, and gives any other address as a number, as glibc gives one that no name server knows: an IPv4-compatible one in inet_ntop(3)'s dotted form, such as ::0.1.0.0. The service stays a number, "80" where glibc says "http", as there is no services database. The host of a Unix address is "localhost", as there is no host name, where glibc gives the host's, and its service is its path up to the first NUL, as glibc reads a C string: an abstract address has none.

macOS

Under `Macos the network follows macOS where it differs from Linux, as the kernel traces record it through eio_posix on macOS 27.3:

Where macOS's loopback delivers a segment asynchronously, the network delivers it at once, as if the next call came after it.

Windows

Under `Windows the network follows Windows where it differs from Linux, as the kernel traces record it through eio_windows on GitHub's windows-latest (Windows Server 2025), and Eio's documented contract where eio_windows breaks it: a refused connect raises Connection_failure where eio_windows waits for ever, a read after a receive shutdown raises where eio_windows waits, and a write after a send shutdown raises a connection reset where eio_windows raises WSAESHUTDOWN unclassified.

Not modelled: SO_EXCLUSIVEADDRUSE, which neither Eio nor OCaml's Unix reaches; the socket options' defaults and values, which follow Linux but for a UDP socket's receive buffer, so one set with SO_RCVBUF holds twice what Windows holds; which addresses a connect or a datagram reaches across families and the edge addresses, which follow Linux; sends off loopback and port exhaustion, which the recordings leave out; and a connect's timeout, 21 seconds as Windows documents it, which no trace records. Eio_net_chaos.conformance leaves those scenarios out under `Windows and names each answer it allows as an eio_windows defect.