librats 1.0.2 → 2.2.0

package/native-src/src/librats/transport/udp_mux.h

@@ -0,0 +1,363 @@
+#pragma once
+
+/**
+ * @file udp_mux.h
+ * @brief One UDP socket, every peer: demultiplexing, admission and timers.
+ *
+ * The whole point of running peer connections over UDP is that they share a
+ * single socket and a single port. That is what makes a NAT hold one mapping
+ * instead of one per peer, what makes hole punching possible at all, and what
+ * makes the port a peer observes us sending from the same port it can dial us
+ * back on. The price is that the kernel no longer separates the peers for us, so
+ * this class does it: every datagram carries a connection id (see udp_packet.h)
+ * that resolves to a UdpStream in one hash lookup.
+ *
+ * Responsibilities, and deliberately nothing more:
+ *   - own the socket and the streams on it;
+ *   - route each datagram to its stream, creating one for an unrecognised Syn
+ *     (after asking the delegate whether a new inbound peer is welcome);
+ *   - answer a datagram for a stream we do not have with a Reset, so the peer
+ *     learns immediately instead of retransmitting into a void;
+ *   - run every stream's timers off one deadline queue (see below);
+ *   - keep a stream alive briefly after its connection is gone, so the last
+ *     bytes it owes the peer still get delivered (see release());
+ *   - move datagrams in batches rather than one syscall at a time (see
+ *     flush_output()).
+ *
+ * ── Why the timers are scheduled, not swept ─────────────────────────────────
+ * Every stream owes its peer some work on a deadline: a retransmission timeout, a
+ * delayed acknowledgement, a keep-alive, and the idle timeout that ends it. The
+ * obvious way to serve those is a fixed sweep — visit every stream every 20 ms and
+ * ask each what it needs. It is simple, and it is wrong in both directions:
+ *
+ *   - it costs O(streams) whether or not anything is due, and
+ *   - far worse, it wakes the reactor fifty times a second *forever*. A connected
+ *     stream that is doing nothing genuinely needs to be visited once per
+ *     keep-alive — every 10 s — and a node with no datagram streams at all needs
+ *     no timer whatsoever. A sweep pays 500x that, and a dial-only node pays it
+ *     for peers it does not have.
+ *
+ * So each stream reports when it next needs servicing (UdpStream::next_deadline)
+ * and the mux keeps them in a min-heap ordered by that deadline. tick() services
+ * only what has come due — O(due + log n) — and next_timeout_ms() tells the
+ * reactor how long it may sleep, so an idle mux contributes no wake-ups at all.
+ *
+ * Keeping that honest is one rule: a deadline must never move *earlier* without
+ * the mux being told. Every path that can mutate a stream therefore re-arms it —
+ * the datagram path here, and read()/write()/close() through UdpStreamLink, which
+ * call stream_touched(). Moving a deadline *later* needs no notification: the
+ * stream is then visited early, finds nothing to do, and re-arms itself.
+ *
+ * ── Why the socket is worked in batches ─────────────────────────────────────
+ * A datagram transport emits one packet per call, so at a 1200-byte payload a
+ * bulk transfer costs tens of thousands of syscalls per megabyte — far more than
+ * the framing, the congestion control and the encryption above it put together,
+ * and the reason a user-space stream costs measurably more CPU per byte than the
+ * kernel's TCP. So the mux does not hand each datagram to the socket as it is
+ * produced: outgoing datagrams are staged and leave together (kUdpBatchMax per
+ * syscall), and incoming ones are collected the same way.
+ *
+ * Staging is deliberately *not* deferred past the work that produced it. Every
+ * entry point flushes before it returns, and the Reactor flushes once more at the
+ * end of each loop turn to cover datagrams produced by application sends — so a
+ * packet never waits on a timer, and batching costs no latency, only syscalls.
+ *
+ * All of that is conditional on the platform actually having a batched send
+ * (kUdpBatchIsOneSyscall). Where it does not — Windows, macOS — staging would pay
+ * a copy per datagram to save syscalls that cannot be saved, so send_datagram()
+ * hands each datagram to the socket as it is produced and the staging path is
+ * compiled out entirely. The receive side has no such split: its fallback fills
+ * the caller's slots directly, so it costs nothing extra either way.
+ *
+ * Threading follows the rest of the transport: the mux belongs to exactly one
+ * Reactor and is touched only by that reactor's thread.
+ *
+ * Events are never delivered from inside the datagram loop. A stream records what
+ * its connection should see, and the mux dispatches once the batch it is standing
+ * in is finished — so a handler that tears its connection down can never free a
+ * stream the loop is still walking. Per batch, not per drain: what a stream
+ * delivers waits in its in-order buffer until the connection reads it out, so
+ * holding every event to the end of the drain would let that buffer grow to
+ * everything one peer could send in it. Events for the same connection coalesce,
+ * because a bulk sender raises one per packet and only the first has work to do.
+ */
+
+#include "librats/core/address.h"
+#include "librats/core/socket.h"
+#include "librats/core/types.h"
+#include "librats/transport/link.h"
+#include "librats/transport/udp_stream.h"
+
+#include <array>
+#include <chrono>
+#include <cstdint>
+#include <memory>
+#include <random>
+#include <unordered_map>
+#include <vector>
+
+namespace librats {
+
+/// What the mux needs from the reactor above it.
+class UdpMuxDelegate {
+public:
+    virtual ~UdpMuxDelegate() = default;
+
+    /// Adopt a freshly accepted inbound stream as a connection. Returns the new
+    /// ConnId, or kInvalidConnId to refuse it (the mux then resets the peer).
+    virtual ConnId adopt_inbound_link(std::unique_ptr<Link> link) = 0;
+
+    /// Deliver poll-equivalent events (PollIn/PollOut/PollErr) to a connection.
+    virtual void dispatch_link_events(ConnId id, uint32_t events) = 0;
+};
+
+/// What the mux is willing to spend on peers it has not heard a round trip from.
+///
+/// A TCP listener gets this for free: an inbound connection costs a file
+/// descriptor, and an attacker cannot make the kernel allocate one without
+/// completing a three-way handshake — which a forged source address cannot do.
+/// A datagram listener has neither the descriptor nor the handshake, so an
+/// unanswered Syn would otherwise buy an attacker a stream, a connection and a
+/// half-built Noise handshake for the price of sixteen forged bytes. These two
+/// numbers are what puts the datagram side back on the same footing.
+struct UdpMuxLimits {
+    /// Concurrent streams the mux will hold at all. A backstop rather than the
+    /// working limit — with validation on (below), everything counted here has
+    /// proved it can receive at its address, and the node's own peer cap governs
+    /// long before this does. Reaching it answers further dials with a Reset.
+    size_t max_streams = 8192;
+
+    /// Streams above which a Syn must carry a valid address-validation cookie
+    /// before it costs anything. This, not max_streams, is the bound on state a
+    /// forged source address can create: past it a bare Syn is answered with a
+    /// Retry and nothing is kept, so unvalidated state can never exceed roughly
+    /// this many streams (~1.5 MiB at the default).
+    ///
+    /// The cost of validation is one extra round trip on an inbound dial, paid
+    /// only by a node that is already carrying this many streams — so an ordinary
+    /// node never pays it, and a node under a flood pays it instead of dying.
+    /// 0 validates every inbound dial; SIZE_MAX never validates any.
+    size_t validate_above = 1024;
+};
+
+class UdpMux final : public UdpStreamHost {
+public:
+    using Clock = UdpStream::Clock;
+
+    /// How long a stream is kept after its connection is gone, to finish handing
+    /// over what it already accepted from the application. TCP gets this from the
+    /// kernel, which keeps retransmitting after close(); without it, a node that
+    /// sends a last message and disconnects would simply lose it.
+    static constexpr std::chrono::seconds kLingerTimeout{5};
+
+    /// Datagrams drained in one readable event before yielding back to the
+    /// reactor, so a flood cannot monopolise the loop. Hitting it is reported so
+    /// the caller can come straight back (the poller is edge-triggered on kqueue,
+    /// which makes "drain until empty" a correctness requirement, not a nicety).
+    static constexpr size_t kMaxDatagramsPerRead = 4096;
+
+    /// Replies emitted per kUnsolicitedReplyWindow to datagrams that belong to no
+    /// stream — the Reset that tells a peer we have forgotten it, and the Retry
+    /// that asks an unproven one to come back with a cookie. Both are answers to
+    /// unauthenticated traffic from an address we have not verified, so both are
+    /// budgeted together: a hostile sender must not be able to turn this socket
+    /// into a reflector, whichever of the two it provokes.
+    ///
+    /// The budget is anchored to the clock rather than to tick(), because tick()
+    /// no longer runs on a fixed cadence — and the case this defends against is a
+    /// flood of junk at a node with *no* streams, which is precisely when a
+    /// deadline-driven tick would never run at all.
+    static constexpr int                      kMaxUnsolicitedReplies = 64;
+    static constexpr std::chrono::milliseconds kUnsolicitedReplyWindow{20};
+
+    /// How long a cookie secret stays current. Two are kept, so a cookie is good
+    /// for between one and two of these — long enough to survive a slow round trip
+    /// and a retransmitted Syn, short enough that a leaked secret is worthless
+    /// almost at once.
+    static constexpr std::chrono::seconds kCookieSecretLifetime{30};
+
+    /// Socket buffer requested in each direction. One socket carries every peer,
+    /// so the default (tens of kilobytes on most systems) is far too small: a
+    /// burst that overruns it is dropped by the kernel, and each drop costs a
+    /// retransmission timeout. This is the single most effective knob there is on
+    /// datagram throughput.
+    static constexpr int kSocketBufferBytes = 4 * 1024 * 1024;
+
+    UdpMux(socket_t socket, AddressFamily family, UdpMuxDelegate& delegate,
+           UdpMuxLimits limits = {});
+    ~UdpMux() override;
+
+    UdpMux(const UdpMux&) = delete;
+    UdpMux& operator=(const UdpMux&) = delete;
+
+    socket_t socket() const noexcept { return socket_; }
+
+    /// The address family this mux's one socket is bound in. A dial to anything
+    /// outside it cannot be carried at all (see family_can_reach), so the reactor
+    /// asks before opening a stream rather than after the Syn has run out.
+    AddressFamily family() const noexcept { return family_; }
+
+    /// Drain the socket and route what arrives. Returns true if it stopped at
+    /// kMaxDatagramsPerRead with more possibly pending.
+    bool on_readable();
+
+    /// Service the streams whose deadline has passed, and retire finished
+    /// lingering ones. Cheap to call on every turn of the reactor loop — with
+    /// nothing due it is one comparison against the earliest deadline.
+    void tick();
+
+    /// How long the reactor may sleep before tick() has work: milliseconds until
+    /// the earliest scheduled deadline, 0 if one has already passed, and `max_ms`
+    /// when no stream is scheduled at all. Mirrors TimerQueue::next_timeout_ms,
+    /// including the round-up (truncating a sub-millisecond remainder to 0 would
+    /// busy-spin to the deadline instead of sleeping through it).
+    int next_timeout_ms(int max_ms) const noexcept;
+
+    /// Re-read `stream`'s deadline after something outside the datagram path
+    /// changed it. Called by UdpStreamLink for read/write/close — read() can
+    /// re-open a closed window (an ack owed at once) and write() starts the
+    /// retransmission timer, both of which move the deadline *earlier*.
+    void stream_touched(UdpStream& stream);
+
+    /// Open an outbound stream to `remote`, ready to be adopted as a connection.
+    /// Returns nullptr only if no free connection id could be found.
+    /// @param profile how hard the dial's Syn is retried — a hole punch wants a
+    ///        denser burst than an ordinary dial does (see DialProfile).
+    std::unique_ptr<Link> connect(const Address& remote, DialProfile profile = {});
+
+    /// Called when the Link that owned `stream` is destroyed. The stream either
+    /// goes away at once or lingers until it has flushed what it owes.
+    void release(UdpStream& stream);
+
+    /// Reset every stream (the node is going down) and drop them.
+    void shutdown();
+
+    /// Put every staged datagram on the wire. Called by each of the entry points
+    /// above before it returns, and by the Reactor at the end of a loop turn to
+    /// cover the ones an application send produced (Connection::send → the stream's
+    /// write path, which reaches this class from outside any datagram batch).
+    /// Cheap and idempotent when nothing is staged.
+    void flush_output();
+
+    size_t stream_count() const noexcept { return streams_.size(); }
+
+    // — UdpStreamHost —
+    void send_datagram(const Address& to, const uint8_t* data, size_t len) override;
+    void stream_events(UdpStream& stream, uint32_t events) override;
+
+private:
+    struct Entry {
+        std::unique_ptr<UdpStream> stream;
+        /// When a released stream stops being worth keeping. Epoch = still owned
+        /// by a live connection.
+        Clock::time_point linger_until{};
+        /// The deadline this stream currently occupies a slot in `due_` for.
+        /// Meaningful only while `armed`; the pair is what makes lazy deletion
+        /// work — a heap slot whose deadline no longer matches has been
+        /// superseded by an earlier one and is dropped when it surfaces.
+        Clock::time_point scheduled{};
+        bool              armed = false;
+    };
+
+    /// One slot in the deadline heap. Deliberately a plain value (8 + 4 bytes, no
+    /// pointer into the map) so a stream can be erased without hunting down the
+    /// slots that name it.
+    struct Due {
+        Clock::time_point at;
+        uint32_t          id;   ///< the stream's recv id, i.e. its key in streams_
+    };
+    /// Min-heap ordering: std::*_heap build max-heaps, so "later first" puts the
+    /// earliest deadline at front().
+    struct LaterFirst {
+        bool operator()(const Due& a, const Due& b) const noexcept { return a.at > b.at; }
+    };
+
+    void        handle_datagram(const rudp::Packet& p, const Address& from, Clock::time_point now);
+    /// Decide whether a Syn for an unknown stream may become one. Answers the peer
+    /// itself (Reset at the ceiling, Retry when it has yet to prove its address)
+    /// and returns false when nothing should be created.
+    bool        admit_syn(const rudp::Packet& syn, const Address& from, Clock::time_point now);
+    void        accept_inbound(const rudp::Packet& syn, const Address& from, Clock::time_point now);
+    void        send_reset(const Address& to, uint32_t conn_id);
+    void        send_retry(const Address& to, uint32_t conn_id, uint32_t cookie);
+    bool        spend_reply_budget(Clock::time_point now);
+    UdpStream*  find_for_reset(uint32_t conn_id, const Address& from);
+    bool        allocate_ids(uint32_t& recv_id, uint32_t& send_id);
+    void        dispatch_pending();
+
+    // — deadline scheduling —
+    /// Give `entry` a heap slot for its next deadline, unless the one it already
+    /// holds comes first. Idempotent, and cheap in the common case: a deadline
+    /// that moved later costs one comparison and no allocation.
+    void        arm(uint32_t id, Entry& entry);
+    /// Rebuild the heap without the slots lazy deletion left behind, once they
+    /// outnumber the live ones badly enough to be worth the pass.
+    void        compact_due();
+
+    // — address validation —
+    using CookieSecret = std::array<uint8_t, 32>;
+    uint32_t cookie_for(const Address& from, uint32_t conn_id, const CookieSecret& secret) const;
+    bool     cookie_valid(const Address& from, uint32_t conn_id, ByteView payload) const;
+    void     rotate_cookie_secret(Clock::time_point now);
+
+    socket_t        socket_;
+    AddressFamily   family_;
+    UdpMuxDelegate& delegate_;
+    UdpMuxLimits    limits_;
+
+    std::unordered_map<uint32_t, Entry> streams_;  ///< keyed by our recv id
+    std::vector<Due>                    due_;      ///< min-heap of stream deadlines
+    std::vector<std::pair<ConnId, uint32_t>> pending_events_;
+
+    // Batch scratch. Both directions keep kUdpBatchMax datagrams' worth of storage
+    // for the life of the mux — allocated once, never grown, so neither the receive
+    // loop nor the send path allocates. The slots point into the storage and are
+    // set up in the constructor; only their lengths and endpoints move afterwards.
+    std::vector<uint8_t>                      recv_storage_;
+    std::vector<uint8_t>                      send_storage_;
+    std::array<UdpBatchSlot, kUdpBatchMax>    recv_slots_{};
+    std::array<UdpBatchSlot, kUdpBatchMax>    send_slots_{};
+    size_t                                    staged_ = 0;  ///< datagrams awaiting flush_output()
+
+    // Cookie secrets: [0] is current, [1] the one it replaced. A cookie is checked
+    // against both, so one that was handed out just before a rotation still works.
+    std::array<CookieSecret, 2> cookie_secret_{};
+    Clock::time_point           secret_rotated_at_{};
+
+    std::mt19937      rng_;
+    Clock::time_point reply_window_started_{};
+    int               replies_in_window_ = 0;
+};
+
+/// The Link a Connection holds for a UDP stream.
+///
+/// The stream itself belongs to the mux, not to the connection: it has to outlive
+/// the connection briefly so the last bytes still get delivered, and it has to be
+/// reachable by connection id from the datagram path. So this is a handle — the
+/// translation between Link's socket-shaped vocabulary and the stream's.
+class UdpStreamLink final : public Link {
+public:
+    UdpStreamLink(UdpMux& mux, UdpStream& stream) : mux_(mux), stream_(stream) {}
+    ~UdpStreamLink() override { mux_.release(stream_); }
+
+    TransportKind kind() const noexcept override { return TransportKind::Udp; }
+
+    IoResult read(ByteSpan into) override;
+    IoResult write(const ByteView* slices, size_t count) override;
+    bool     connect_completed() override { return !stream_.dead(); }
+    void     want_write(bool on) override { stream_.want_write(on); }
+
+    std::optional<Address> remote_endpoint() const override { return stream_.remote(); }
+
+    void        attach(ConnId id) override { stream_.set_conn_id(id); }
+    CloseReason error_reason() const override { return stream_.close_reason(); }
+    void        close(CloseReason reason) override;
+
+    UdpStream& stream() noexcept { return stream_; }
+
+private:
+    UdpMux&    mux_;
+    UdpStream& stream_;
+};
+
+} // namespace librats

package/native-src/src/librats/transport/udp_packet.cpp

@@ -0,0 +1,121 @@
+#include "librats/transport/udp_packet.h"
+
+#include <cstring>
+
+namespace librats {
+namespace rudp {
+
+namespace {
+
+void put_u16(uint8_t* p, uint16_t v) {
+    p[0] = static_cast<uint8_t>(v >> 8);
+    p[1] = static_cast<uint8_t>(v);
+}
+
+void put_u32(uint8_t* p, uint32_t v) {
+    p[0] = static_cast<uint8_t>(v >> 24);
+    p[1] = static_cast<uint8_t>(v >> 16);
+    p[2] = static_cast<uint8_t>(v >> 8);
+    p[3] = static_cast<uint8_t>(v);
+}
+
+uint16_t get_u16(const uint8_t* p) {
+    return static_cast<uint16_t>((static_cast<uint16_t>(p[0]) << 8) | p[1]);
+}
+
+uint32_t get_u32(const uint8_t* p) {
+    return (static_cast<uint32_t>(p[0]) << 24) | (static_cast<uint32_t>(p[1]) << 16) |
+           (static_cast<uint32_t>(p[2]) << 8)  |  static_cast<uint32_t>(p[3]);
+}
+
+} // namespace
+
+size_t encode_header(const Packet& p, uint8_t* out) {
+    const uint8_t flags = p.has_sack() ? static_cast<uint8_t>(p.flags)
+                                       : static_cast<uint8_t>(p.flags & ~FlagSack);
+
+    out[0] = static_cast<uint8_t>((kVersion << 4) | (static_cast<uint8_t>(p.type) & 0x0F));
+    out[1] = flags;
+    put_u16(out + 2, p.window);
+    put_u32(out + 4,  p.conn_id);
+    put_u32(out + 8,  p.seq);
+    put_u32(out + 12, p.ack);
+
+    size_t n = kHeaderSize;
+    if (flags & FlagSack) {
+        put_u32(out + n, p.sack);
+        n += kSackSize;
+    }
+    return n;
+}
+
+size_t encode(const Packet& p, uint8_t* out) {
+    size_t n = encode_header(p, out);
+    if (!p.payload.empty()) {
+        std::memcpy(out + n, p.payload.data(), p.payload.size());
+        n += p.payload.size();
+    }
+    return n;
+}
+
+bool decode(const uint8_t* data, size_t len, Packet& out) {
+    if (len < kHeaderSize) return false;
+    if ((data[0] >> 4) != kVersion) return false;
+
+    const uint8_t type = data[0] & 0x0F;
+    if (type > static_cast<uint8_t>(PacketType::Retry)) return false;
+
+    out.type    = static_cast<PacketType>(type);
+    out.flags   = data[1];
+    out.window  = get_u16(data + 2);
+    out.conn_id = get_u32(data + 4);
+    out.seq     = get_u32(data + 8);
+    out.ack     = get_u32(data + 12);
+
+    size_t offset = kHeaderSize;
+    if (out.has_sack()) {
+        if (len < offset + kSackSize) return false;
+        out.sack = get_u32(data + offset);
+        offset += kSackSize;
+    } else {
+        out.sack = 0;
+    }
+
+    out.payload = ByteView(data + offset, len - offset);
+
+    // What a type is allowed to carry after the header. Being strict here is what
+    // keeps a padded or spliced datagram from ever reaching a stream as stream
+    // content, and keeps the accounting ("a Data packet is worth payload.size()
+    // bytes") true by construction.
+    switch (out.type) {
+        case PacketType::Data:
+            break;  // stream bytes, any length up to kMaxPayload
+        case PacketType::Syn:
+        case PacketType::Retry:
+            // The address-validation cookie, or nothing at all. Fixed width, so
+            // there is no room to smuggle anything alongside it.
+            if (!out.payload.empty() && out.payload.size() != kCookieSize) return false;
+            break;
+        default:
+            if (!out.payload.empty()) return false;  // Ack/Fin/Reset are header-only
+            break;
+    }
+    if (out.payload.size() > kMaxPayload) return false;
+
+    return true;
+}
+
+const char* to_string(PacketType t) noexcept {
+    switch (t) {
+        case PacketType::Syn:   return "SYN";
+        case PacketType::Data:  return "DATA";
+        case PacketType::Ack:   return "ACK";
+        case PacketType::Fin:   return "FIN";
+        case PacketType::Reset: return "RESET";
+        case PacketType::Retry: return "RETRY";
+    }
+    return "?";
+}
+
+} // namespace rudp
+} // namespace librats

package/native-src/src/librats/transport/udp_packet.h

@@ -0,0 +1,190 @@
+#pragma once
+
+/**
+ * @file udp_packet.h
+ * @brief Wire format of the reliable-UDP transport: one fixed 16-byte header.
+ *
+ * A datagram is a header, an optional 4-byte selective-ack word, and (for Data)
+ * a payload. Everything is big-endian, and every field is fixed-width, so decode
+ * is a handful of loads with a single length check — no allocation, no parsing
+ * state, and nothing a hostile datagram can make us over-reserve.
+ *
+ *      0               1               2               3
+ *      0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1
+ *     +-------+-------+---------------+-------------------------------+
+ *     |  ver  | type  |     flags     |            window             |
+ *     +-------+-------+---------------+-------------------------------+
+ *     |                            conn_id                            |
+ *     +---------------------------------------------------------------+
+ *     |                              seq                              |
+ *     +---------------------------------------------------------------+
+ *     |                              ack                              |
+ *     +---------------------------------------------------------------+
+ *     |                     sack  (only if flag Sack)                 |
+ *     +---------------------------------------------------------------+
+ *
+ *  - conn_id : the id the *receiver* registered this stream under, so a single
+ *              shared socket can demultiplex thousands of streams with one hash
+ *              lookup and no per-peer socket. Each side picks its own; see
+ *              udp_stream.h for how the pair is derived from the Syn.
+ *  - seq     : sequence number of this packet. Syn, Data and Fin each consume
+ *              one (so all three are retransmitted until acknowledged); an Ack
+ *              carries the next sequence number to be used and consumes nothing,
+ *              which is why a pure acknowledgement is never itself acknowledged.
+ *  - ack     : the highest sequence number received *in order* — a cumulative
+ *              acknowledgement, so a lost Ack costs nothing as long as a later
+ *              one arrives. 0 means "nothing received yet" (sequence numbers
+ *              start at 1).
+ *  - sack    : a bitmap acknowledging the 32 packets after the hole at ack+1
+ *              (bit i ⇒ ack+2+i arrived). This is what lets a single loss be
+ *              repaired without stalling everything queued behind it.
+ *  - window  : how many further packets the sender of this datagram can buffer,
+ *              in packets. This is the flow-control signal; 0 stops the peer.
+ *
+ * Only three types carry anything after the header. Data carries stream bytes.
+ * Retry and Syn carry the kCookieSize address-validation cookie, or nothing —
+ * a responder under load answers a Syn with a Retry rather than opening a stream,
+ * and only a Syn that hands the cookie back costs it any memory (see udp_mux.h).
+ * Everything else is header-only, and a datagram that pads one is rejected.
+ *
+ * Sequence numbers are 32-bit and wrap; compare them only with seq_less/seq_diff,
+ * never with < on the raw value.
+ */
+
+#include "librats/core/bytes.h"
+
+#include <cstdint>
+#include <cstddef>
+
+namespace librats {
+namespace rudp {
+
+/// Protocol version carried in the high nibble of byte 0. Bumped only for a
+/// change no existing peer could parse; a peer that sees another version drops
+/// the datagram (silently — an unauthenticated sender gets no reply).
+constexpr uint8_t kVersion = 1;
+
+enum class PacketType : uint8_t {
+    Syn   = 0,  ///< open a stream (initiator → responder); consumes a sequence number
+    Data  = 1,  ///< stream payload; consumes a sequence number
+    Ack   = 2,  ///< pure acknowledgement / window update / keep-alive
+    Fin   = 3,  ///< orderly end of the sender's stream; consumes a sequence number
+    Reset = 4,  ///< abort now: the stream is gone or was never known
+    Retry = 5,  ///< "prove you are at that address first" — carries a cookie, holds no state
+};
+
+enum PacketFlags : uint8_t {
+    FlagNone = 0,
+    FlagSack = 1 << 0,  ///< the 4-byte selective-ack word follows the header
+};
+
+/// Bytes on the wire before the payload, without the selective-ack word.
+constexpr size_t kHeaderSize = 16;
+/// Bytes added by the selective-ack word.
+constexpr size_t kSackSize = 4;
+/// Packets one selective-ack word can name — the 32 that follow the hole at
+/// ack+1. This is a reach as well as a width: a sender learns nothing about a
+/// packet further than this past its oldest unacknowledged one, which is what
+/// bounds how far into the retransmission queue an acknowledgement can ever mark
+/// anything (see UdpStream::repair_sacked_holes).
+constexpr uint32_t kSackBits = 8 * static_cast<uint32_t>(kSackSize);
+/// The largest a header can get. A sender that keeps this much headroom in front
+/// of a payload can write the header directly ahead of the bytes it describes and
+/// hand the socket one contiguous datagram — see encode_header().
+constexpr size_t kMaxHeaderSize = kHeaderSize + kSackSize;
+
+/// Bytes of the address-validation cookie a Retry hands out and a Syn hands back
+/// (see udp_mux.h). Four is the width of the truncated keyed hash it carries: an
+/// attacker who cannot receive at the address it is bound to gets one guess in
+/// 2^32 per Syn, which is the same order of protection a TCP SYN cookie encodes
+/// into a 32-bit sequence number.
+constexpr size_t kCookieSize = 4;
+
+/// Payload carried by one Data packet. 1200 keeps header+payload inside the
+/// smallest MTU worth designing for (IPv6's 1280 floor, minus room for an IPv6
+/// header plus a tunnel), so a stream never depends on IP fragmentation — which
+/// on a datagram path turns one lost fragment into a lost packet.
+constexpr size_t kMaxPayload = 1200;
+
+/// Largest datagram this transport ever sends or expects to receive.
+constexpr size_t kMaxDatagram = kHeaderSize + kSackSize + kMaxPayload;
+
+/// Packets a receiver will hold out of order, and therefore the largest window it
+/// ever advertises. This is the hard ceiling on in-flight data, so it is also the
+/// ceiling on throughput: a window of W packets on a path of RTT R can never
+/// exceed W * kMaxPayload / R, whatever the link underneath can do.
+///
+/// 1024 * 1200 B ≈ 1.2 MiB, i.e. ~96 Mbit/s at 100 ms and ~48 Mbit/s at 200 ms —
+/// enough that an intercontinental path is limited by the path rather than by
+/// this constant. (At the previous 256 it was ~24 Mbit/s at 100 ms, well under
+/// what TCP would have managed on the same path.)
+///
+/// It is also what bounds the memory one peer can make us hold: the reorder
+/// buffer never holds more than this many packets, so ~1.2 MiB per stream in the
+/// worst case. That worst case needs a window's worth of loss to reach, and both
+/// the reorder map and the retransmission queue only ever grow to what is
+/// actually outstanding — an idle or slow stream costs nothing near it.
+constexpr uint16_t kMaxWindowPackets = 1024;
+
+struct Packet {
+    PacketType type   = PacketType::Ack;
+    uint8_t    flags  = FlagNone;
+    uint16_t   window = 0;
+    uint32_t   conn_id = 0;
+    uint32_t   seq     = 0;
+    uint32_t   ack     = 0;
+    uint32_t   sack    = 0;   ///< meaningful only when (flags & FlagSack)
+    ByteView   payload;       ///< points into the caller's receive buffer
+
+    bool has_sack() const noexcept { return (flags & FlagSack) != 0; }
+};
+
+/// Bytes `p`'s header occupies on the wire: the fixed part, plus the selective-ack
+/// word when one is carried.
+inline size_t header_size(const Packet& p) noexcept {
+    return p.has_sack() ? kHeaderSize + kSackSize : kHeaderSize;
+}
+
+/// Serialise only `p`'s header (and its optional sack word) into `out`, which must
+/// have room for kMaxHeaderSize bytes. The payload is NOT copied.
+///
+/// This is the form used on the send path: a packet buffer carries kMaxHeaderSize
+/// bytes of headroom in front of its payload, so the header is written directly
+/// ahead of the bytes it describes and the whole datagram goes to the socket in
+/// one piece — no second copy of the payload just to prefix a header to it.
+/// @return the number of bytes written (kHeaderSize, or kHeaderSize + kSackSize).
+size_t encode_header(const Packet& p, uint8_t* out);
+
+/// Serialise `p` (header, optional sack word, then payload) into `out`, which must
+/// have room for kMaxHeaderSize + p.payload.size() bytes.
+/// @return the number of bytes written.
+size_t encode(const Packet& p, uint8_t* out);
+
+/// Parse one datagram. Returns false for anything malformed: a short buffer, an
+/// unknown version, an unknown type, or a payload on a type that cannot carry one.
+/// `out.payload` points into `data` and is valid only while that buffer is.
+bool decode(const uint8_t* data, size_t len, Packet& out);
+
+// ── Wrapping sequence arithmetic ────────────────────────────────────────────
+//
+// Sequence numbers advance forever in a 32-bit space, so ordering is only ever
+// meaningful over distances far smaller than half that space. Comparing the raw
+// values would invert the moment the counter wraps; comparing the *difference* as
+// a signed number is correct across the wrap and is what every window check here
+// goes through.
+
+/// Signed distance a - b, correct across the 32-bit wrap.
+inline int32_t seq_diff(uint32_t a, uint32_t b) noexcept {
+    return static_cast<int32_t>(a - b);
+}
+
+/// True when a precedes b.
+inline bool seq_less(uint32_t a, uint32_t b) noexcept { return seq_diff(a, b) < 0; }
+
+/// True when a precedes or equals b.
+inline bool seq_le(uint32_t a, uint32_t b) noexcept { return seq_diff(a, b) <= 0; }
+
+const char* to_string(PacketType) noexcept;
+
+} // namespace rudp
+} // namespace librats