mirror of
https://github.com/jmcorgan/fips.git
synced 2026-10-05 19:18:25 +00:00
Johnathan Corgan
462b9daf0a
The how-to told an author writing a client in another language that a queued empty datagram leaves the socket with no events pending, while a closed peer sets POLLHUP. That is false, and a client written to it reproduces the defect the receive path has just had fixed, in their code rather than ours. It also told them to poll with an events mask of zero. The library stopped doing that when the macOS port landed, because a poll that requests nothing registers no filter on Darwin and returns no events for a peer that has in fact closed. A client following the old instruction would never detect a close on macOS at all. The reference page carried both errors and asserted that a zero-byte read is an empty datagram and only that. Both pages now describe what the code does. Request POLLIN. Treat a hang-up as end of file only when FIONREAD reports nothing queued behind the read. Design around the one case neither check can resolve, by never giving a zero-length payload a meaning of its own.
Reference
Information-oriented technical descriptions for lookup on demand. Reference content describes what is: wire formats, configuration keys, command-line flags, control-socket commands, default values, file paths, exit codes. It is consulted, not read end-to-end.
Reference is austere by design: minimal narrative, no opinions, no guidance on when to use a feature. The "why" lives in design/; the "how do I accomplish X" lives in how-to/.
Available Reference
| Document | Scope |
|---|---|
| wire-formats.md | All FMP and FSP message byte layouts, encapsulation walkthrough |
| configuration.md | Full YAML configuration reference for the daemon and gateway |
| security.md | nftables baseline, peer ACL, cryptographic primitives, rekey defaults, threat-resistance matrix |
| nostr-events.md | Kind 37195 advert, Kind 21059 traversal signaling, Kind 10050 inbox relays |
| transports.md | Per-transport statistics counter inventory |
| control-socket.md | Line-delimited JSON control protocol for the daemon and gateway |
| native-api.md | Native datagram API: the Rust surface, addressing and ports, errno table, ceilings, line protocol, command reference |
| cli-fips.md | fips daemon CLI: options, exit codes, environment, files |
| cli-fipsctl.md | fipsctl control-client: subcommands, options, exit codes |
| cli-fipstop.md | fipstop live-status TUI: tabs, keybindings |
| cli-fips-gateway.md | fips-gateway service CLI: options, exit codes, files |