API reference
The whole surface, by package.
Every public value, type, method and error, generated from the package interfaces and the comments beside the code.
moonnet/spec
The contract: one exchange, whatever carries it.
The first field named name, matched without regard to case.
name: value lines, the form a head is shown in by a person reading a log.
Every field of a head as one lower-cased name to its value, the last one winning, as a map lookup would.
Where a message's body comes from.
No body: the message ends where its head does.
A body that is at hand, sent in full before the reply is read.
A body the caller sends with send after the exchange is open, in pieces whose length is not known when the head goes out.
One field of a message head: the name, and the value, as they go on the wire.
The name in the form a comparison uses: HTTP field names are case-insensitive (RFC 9110 §5.1), and a lower-case copy is what every lookup compares.
What a connection will not do.
The peer's octets are not what the protocol allows.
The request, or the peer, asks for something this connection does not do.
The connection ended before the exchange did.
The socket failed under the connection.
A request: what to ask for, and what to carry along.
A reply head: the status and the fields. The body is read through the connection, because it may be larger than anything worth holding at once.
One exchange on a connection, named by the connection rather than by the protocol underneath: on a connection that carries one exchange at a time it is 1, and on one that multiplexes it is whatever that connection gave out.
The one contract a connection presents, whatever carries it: HTTP/1.1, HTTP/2, HTTP/3 or WebSocket. Code written against this runs on any of them; an implementation is all a new protocol needs.
An exchange is opened, the request body is sent through it, and the reply's head and body are read from it. A connection that carries one exchange at a time says so through is_ready, which a caller waits on before opening the next.
Open an exchange on request, and send its head and whatever body came with it.
Send more of the request's body; end marks the last of it. Only an exchange opened with Body::Streaming takes this.
The reply's head, once the peer has sent it.
The next run of the reply's body, read as it arrives; None ends it.
The fields that came after the body, once read has ended it.
Whether another exchange can start on this connection now. False while one is in flight on a connection that carries them one at a time, and after it has ended.
The protocol the connection settled on, as ALPN names it: http/1.1, h2, h3.
End the connection, in whatever way the protocol under it asks for.
moonnet/adapt/h1
HTTP/1.1, RFC 9112.
A client over a connection that is already open to authority, the host[:port] the Host field carries.
An HTTP/1.1 client connection: one exchange at a time, its head and body framed as RFC 9112 says, over the tcp connection underneath.
Where an exchange stands.
moonnet/adapt/h2
HTTP/2, RFC 9113.
An HTTP/2 client connection: many exchanges over one connection, each on its own stream, framed as RFC 9113 says.
moonnet/adapt/h3
HTTP/3, RFC 9114, over QUIC.
An HTTP/3 client connection: one QUIC connection, a control stream carrying this side's settings, and a bidirectional stream for every exchange (RFC 9114 §6).
moonnet/adapt/ws
WebSocket, RFC 6455.
A session over a connection that is already open to the server.
A WebSocket session over a connection. The exchange is the upgrade: open sends the handshake, response is the 101, and from then on read yields whole messages and send writes them.
The close code and reason the peer gave, once the session has closed; 0 before.
The reason the peer gave with its close, empty when it gave none.
Whether the session has closed, from either side.
moonnet/tcp
TCP, and TLS over it: connections, the listener, the dialler.
How long a TLS handshake may take, in milliseconds: asyncio's and hypercorn's 60 seconds. A peer that connects and never finishes holds a connection slot until then.
The address a server listens on when none is given: loopback only, as uvicorn and Starlette default to, so a development server is not reachable from the network by accident.
The port every server in the family listens on by default.
One TCP connection, in the clear or under TLS 1.3. It reads and writes through @io.Reader and @io.Writer either way, so a protocol driver serves both with the same code.
One task may read while another writes. Writes are serialised, so two tasks writing at once put whole messages on the wire, one after the other, and TLS records stay in sequence.
The application protocol ALPN settled on (RFC 7301). None in the clear.
Close the socket. Call shutdown first for a clean end under TLS.
Whether the connection runs under TLS.
The certificate chain the peer presented, DER, leaf first. Empty in the clear.
A connection in the clear.
The host name the client asked for (RFC 6066 §3). None in the clear.
The TLS connection underneath, for what the accessors here do not say: the suite, the key update, the refusal reason. None in the clear.
A bound, listening socket. Connections queue from the moment listen returns, so a caller can connect to it, or hand its port out, without racing the server.
The address listened on; with port 0 asked for, the port the system chose.
Stop listening.
What a connection will not do.
secure or upgrade on a connection that is TLS already.
moonnet/udp
The datagram socket, and the client end of a QUIC connection.
How long a QUIC dial gives one address before it tries the next one as well: the connection attempt delay of RFC 8305 §5, at the 250 ms §8 recommends.
The clock a QUIC connection counts in: microseconds since the epoch, which is the unit the recovery, idle and closing-period timers are measured in (RFC 9002 §6). Reading it in milliseconds leaves every timer a thousand times too long, so a lost packet is never sent again.
A QUIC connection driven by one task: the client half of what moonquic states and this package puts on a datagram socket. Reading is a poll, because a connection that also carries control and QPACK streams cannot hand every arrival to one caller.
The ALPN the handshake settled on.
Close the socket the connection runs on.
Whether the peer has ended stream, with every octet of it read. A stream the peer reset is over too, however much of it arrived.
The next bidirectional stream this side opens: 0, 4, 8, … as RFC 9000 §2.1 numbers them.
The next unidirectional stream, from 2 upwards.
How the peer ended stream abruptly, if it did: Reset for a stream this side was reading, Stopped for one it was writing. None while the stream is live, and after a clean FIN — which is what ended reports.
Abandon stream as a sender: send RESET_STREAM carrying code, and drop what the send loop still holds for it (RFC 9000 §3.5, §19.4). Zero, the default, is NO_ERROR (§20.1). Writing on the stream afterwards raises Reset. A stream this side only reads may be reset too: it closes this side's sending half, which is what a reply abandoned half way needs.
Ask the peer to stop sending on stream, with STOP_SENDING carrying code (RFC 9000 §19.5): the octets already on their way are dropped when they arrive, and take raises Reset if the peer answers with one. Zero, the default, is NO_ERROR (§20.1).
The octets that arrived on stream since the last call; empty when none have. What arrived before a reset is still handed over first: RFC 9000 §3.2 keeps the octets received up to the final size readable, and it is the end that is an error. An empty read raises Reset once the peer has abandoned the stream.
Put bytes on stream, and end it when fin. Raises Stopped when the peer has asked this side to stop sending on the stream, and Reset when this side abandoned it.
What a QUIC connection will not do.
The handshake did not complete in the time this waited.
The socket or the connection under it failed.
The connection is over.
The stream was abandoned with this application code: the peer sent RESET_STREAM when this side was reading it, or this side sent one itself (RFC 9000 §19.4).
The peer sent STOP_SENDING with this code, which says it will read no more of the stream; sending on it is over (RFC 9000 §19.5).
A datagram socket. One task may receive while others send; two tasks receiving at once would each take half the datagrams, so a connection that needs one reader keeps one.
The address bound; with port 0 asked for, the port the system chose.
Stop using the socket.
moonnet/pool
Connections kept by host, port and ALPN.
The presets: an idle connection lives half a minute, a key keeps eight, the pool holds sixty-four, a reused one is peeked at, and a caller waits five seconds for a slot. These are the values curl and Go's transport settle near; what matters more is that all five are named and can be changed.
How a pool behaves. Every one of these is a number a caller will want to change, so all of them are here rather than in the code.
A connection handed out by a pool: the contract's eight methods, and a close that puts the connection back for the next caller instead of shutting the socket.
A connection kept in the pool, and the moment it stops being worth reusing.
What makes two connections interchangeable: the host, the port, and the protocol ALPN settled on. A connection kept under one key is never handed out for another.
What a reused connection is asked before it is handed out again.
Nothing: a connection that served an exchange is taken on trust until the next one fails, which is what most clients do.
A read that does not wait. A peer that has closed is dropped; one that has said something while idle keeps what it said for the next exchange.
A socket and the connection that presents it as the contract. The two stay bound for as long as both live: a protocol's connection carries state a fresh one over the same socket would not have — HTTP/2 sends its preface once, and a WebSocket session is one upgrade and then messages.
A pair for a socket the caller has just dialled, with conn the adapter over it.
The connections kept for another exchange, handed out as the contract. A caller takes one with get and gives it back by closing it; a connection that is never closed is not counted as idle and stays against max_total.
Close every idle connection and refuse further use. A connection out on loan is closed when its holder gives it back.
How many connections are idle under key.
A pool that opens a connection with open when it has none to hand out.
How many connections the pool holds open, in use or idle.
What a pool will not do.
The pool is full and no slot came free in time.
The pool was closed.
Opening a connection failed.
Where a handed-out connection stands. A connection is reused only from InUse; an exchange that failed, or one that was cut short, leaves it Broken and the socket is shut rather than handed on.
moonnet
The front door: one import for the connection, the datagram socket and the contract.
What connect settled on.