🥮 mooncakes.io

    moonbitstack/moonquic/packet does not have a README file

    Refused

    source
    pub(all) suberror Refused {
      Malformed(String)
    } derive(Eq)

    A truncated or unparsable frame in a packet payload.
    impl Show for Refused

    Refused::equal

    source
    fn Refused::equal(Refused, Refused) -> Bool

    Refused::not_equal

    source
    fn Refused::not_equal(x : Refused, y : Refused) -> Bool

    Refused::output

    source
    fn Refused::output(self : Refused, logger : &Logger) -> Unit

    Refused::to_string

    source
    fn Refused::to_string(self : Refused) -> String

    Kind

    source
    pub(all) enum Kind {
      Initial
      ZeroRtt
      Handshake
      Retry
    } derive(Eq, 
    Debug    )

    The four long-header packet types (RFC 9000 §17.2).

    Kind::code

    source
    fn Kind::code(self : Kind, version : UInt) -> Int

    The first byte's 2-bit type code for a packet type under version (RFC 9000 §17.2, RFC 9369 §3.2). Version 1 numbers the four types Initial 0, 0-RTT 1, Handshake 2, Retry 3; version 2 rotates them by one, so a middlebox that learned one version's numbers rejects the other's rather than guessing. A version this library does not know is written with version 1's codes, which is what a version-independent header — a Version Negotiation packet — leaves unread.

    Kind::equal

    source
    fn Kind::equal(Kind, Kind) -> Bool

    Kind::not_equal

    source
    fn Kind::not_equal(x : Kind, y : Kind) -> Bool

    Kind::of

    source
    fn Kind::of(version : UInt, code : Int) -> Kind

    The packet type a 2-bit code names under version, the inverse of Kind::code.

    Kind::to_repr

    source

    Long

    source
    pub(all) struct Long {
      packet_type : Kind
      type_specific : Int
      version : UInt
      dcid : Bytes
      scid : Bytes
    } derive(Eq, 
    Debug    )

    A long packet header's invariant fields: its type, the type-specific low four bits of the first byte (the packet-number length for Initial/Handshake/0-RTT, unused by Retry), the 32-bit version, and the destination and source connection IDs.

    Long::equal

    source
    fn Long::equal(Long, Long) -> Bool

    Long::header

    source
    fn Long::header(self : Long, number : BytesView, payload~ : Int, token? : Bytes) -> Bytes

    The header a protected packet is sealed under: the invariant header, the Initial token, the Length covering the packet number and payload bytes, then number.

    number is the truncated packet number already encoded, so the first byte's low bits follow from its length and the truncation is decided once, where number is built. payload counts the sealed payload, AEAD tag included, because that is what a receiver subtracts from Length to find where the payload ends.

    A token on a type that carries none is written anyway: only Initial has the field, so passing one elsewhere is a caller's error rather than something to paper over.

    Long::not_equal

    source
    fn Long::not_equal(x : Long, y : Long) -> Bool

    Long::to_repr

    source

    Short

    source
    pub(all) struct Short {
      spin : Bool
      key_phase : Bool
      pn_length : Int
      dcid : Bytes
    } derive(Eq, 
    Debug    )

    A short header's fields: the latency spin bit, the key-phase bit, the packet-number length (1–4 bytes, from the low two bits of the first byte plus one), and the destination connection ID.

    Short::equal

    source
    fn Short::equal(Short, Short) -> Bool

    Short::header

    source
    fn Short::header(self : Short, number : BytesView) -> Bytes

    The header a protected 1-RTT packet is sealed under (RFC 9000 §17.3): the first byte, the destination connection ID, and the packet number.

    As on the long side the first byte's low bits come from number, so pn_length on the struct is what a reader found rather than something a writer must agree with. A short header has no length field: the payload runs to the end of the datagram.

    Short::not_equal

    source
    fn Short::not_equal(x : Short, y : Short) -> Bool

    Short::to_repr

    source

    Space

    source
    pub struct Space {
      next_pn : Int64
      received : 
    Seen
      largest_acked : Int64?
      ack_eliciting_pending : Bool
    }

    One packet-number space's send/receive numbering and acknowledgement state.

    Space::ack_pending

    source
    fn Space::ack_pending(self : Space) -> Bool

    Whether an ACK is owed — an ack-eliciting packet has arrived since the last ACK was built.

    Space::advance_past

    source
    fn Space::advance_past(self : Space, pn : Int64) -> Unit

    Skip the send counter past pn, so a packet another sender numbered in this space — the recovery loop's, which keeps its own counter — is not handed out again here. A pn this space is already past leaves it alone.

    Space::build_ack

    source
    fn Space::build_ack(self : Space, ack_delay : UInt64) -> 
    Frame    ?

    Build the ACK frame acknowledging everything received so far with the given ack_delay, and clear the pending flag. None when nothing has been received.

    Space::issued

    source
    fn Space::issued(self : Space) -> Int64

    One past the highest packet number this space has handed out: the first number the peer cannot have seen, so an acknowledgement of it or anything above names a packet that was never sent (RFC 9000 §13.1).

    Space::largest_acked

    source
    fn Space::largest_acked(self : Space) -> Int64?

    The largest packet number the peer has acknowledged, or None.

    Space::largest_received

    source
    fn Space::largest_received(self : Space) -> Int64

    The largest packet number received in this space, or -1 before the first: what the next number on the wire is expanded against (RFC 9000 A.3).

    Space::new

    source
    fn Space::new() -> Space

    A fresh space: next packet number 0, nothing received or acknowledged.

    Space::next_packet_number

    source
    fn Space::next_packet_number(self : Space) -> Int64

    Allocate the next packet number to send, advancing the counter.

    Space::on_ack_received

    source
    fn Space::on_ack_received(self : Space, largest : Int64) -> Unit

    Record that the peer acknowledged up to largest, advancing the high-water mark (an older ACK never lowers it).

    Space::on_packet_received

    source
    fn Space::on_packet_received(self : Space, pn : Int64, ack_eliciting : Bool) -> Unit

    Record that packet number pn arrived. ack_eliciting marks a packet that must be acknowledged (RFC 9000 §13.2.1); a pure-ACK packet is recorded but does not itself oblige a new ACK.

    Space::seen

    source
    fn Space::seen(self : Space, pn : Int64) -> Bool

    Whether packet pn has been processed already, which a receiver must not do twice (RFC 9000 §12.3).

    Tail

    source
    pub(all) struct Tail {
      token : Bytes
      length : UInt64
      at : Int
    } derive(Eq, 
    Debug    )

    What follows a long header's invariant part in an Initial, 0-RTT or Handshake packet: the Initial token (empty for the two types that carry none), the Length field covering the packet number and the payload, and where in the packet the packet number starts.

    Tail::equal

    source
    fn Tail::equal(Tail, Tail) -> Bool

    Tail::not_equal

    source
    fn Tail::not_equal(x : Tail, y : Tail) -> Bool

    Tail::to_repr

    source

    encode_long

    source
    fn encode_long(h : Long) -> Bytes

    Encode a long header: first byte (1 header-form, 1 fixed bit, 2-bit type, 4 type-specific bits), the version big-endian, then each connection ID prefixed by its one-byte length.

    encode_short

    source
    fn encode_short(h : Short) -> Bytes

    Encode a short header: first byte (0 header-form, 1 fixed bit, spin, two reserved zero bits, key phase, and the 2-bit packet-number length minus one), then the destination connection ID with no length prefix. The (protected) packet number follows, encoded separately.

    number

    source
    fn number(full_pn : Int64, largest_acked : Int64?, size? : Int) -> Bytes

    Encode full_pn as its truncated big-endian packet number, using the shortest length that is unambiguous given largest_acked (RFC 9000 A.2).

    size writes that many bytes instead. A sender that has already decided how long its packet numbers are — a handshake that fixes four, a test with a vector to match — says so rather than having the length inferred back.

    number_size

    source
    fn number_size(full_pn : Int64, largest_acked : Int64?) -> Int

    The number of bytes (1–4) needed to encode full_pn given the largest packet number the peer has acknowledged (RFC 9000 §17.1 / A.2): enough bytes to cover twice the number of unacknowledged packets, so wraparound is unambiguous. With no acknowledgement yet, the count is full_pn + 1.

    pad

    source
    fn pad(payload : Bytes, min_size : Int) -> Bytes

    Pad payload out to at least min_size bytes with PADDING frames (zero octets); a payload already that long is returned unchanged (RFC 9000 §14.1 — an Initial packet's payload is padded so the datagram reaches the 1200-byte minimum).

    payload

    source
    fn payload(frames : Array[
    Frame    ]) -> Bytes

    Encode a list of frames into a packet payload — their wire encodings concatenated.

    payload_elicits_ack

    source
    fn payload_elicits_ack(frames : Array[
    Frame    ]) -> Bool

    Whether a payload's frames make the packet ack-eliciting — true if any frame is.

    read_header

    source
    fn read_header(b : BytesView) -> (Long, Tail)?

    A long header and its tail in one read, for the common case of taking a packet apart from the front.

    read_long

    source
    fn read_long(b : BytesView) -> (Long, Int)?

    Parse a long header at the start of b, returning it and the number of bytes it occupied, or None if the first byte is not a long header or b is truncated before the header ends.

    read_number

    source
    fn read_number(largest_pn : Int64, truncated_pn : Int64, pn_nbits : Int) -> Int64

    Recover the full packet number from a truncated_pn of pn_nbits bits, given the largest full packet number already received (RFC 9000 A.3): pick the value congruent to truncated_pn that is closest to the next expected number, resolving wraparound with the half-window rule.

    read_payload

    source
    fn read_payload(payload : Bytes) -> Array[
    Frame    ] raise Refused

    Parse a decrypted packet payload into its frames, consuming the whole payload. A frame that does not parse, or that consumes no bytes, is a payload error.

    read_retry

    source
    fn read_retry(b : BytesView) -> (Long, Bytes, Bytes)?

    A Retry packet's header, token and integrity tag. Everything after the invariant header is the token save the trailing 16 bytes, so a packet shorter than that, or one that is not a Retry, reads as None.

    read_short

    source
    fn read_short(b : BytesView, dcid_len : Int) -> (Short, Int)?

    Parse a short header at the start of b, given the length of the destination connection ID this endpoint issued. Returns the header and the bytes consumed (first byte plus the connection ID), or None if the first byte is a long header or b is shorter than that.

    read_tail

    source
    fn read_tail(h : Long, b : BytesView, at : Int) -> Tail?

    The tail following the invariant header that ended at bytes into b.

    None when the packet is truncated inside the token or the length field, or when h is a Retry — a Retry has no Length and no packet number, so read_retry reads it.

    read_versions

    source
    fn read_versions(b : BytesView) -> (Bytes, Bytes, Array[UInt])?

    The connection IDs and offered versions a Version Negotiation packet carries.

    None unless the version field is zero, which is what marks the packet, and unless the version list is a whole number of four-byte versions.

    retry

    source
    fn retry(h : Long, token~ : Bytes, tag~ : Bytes) -> Bytes

    A Retry packet (RFC 9000 §17.2.5): the invariant header, the retry token, and the 16-byte integrity tag that binds the packet to the original connection ID.

    version1

    source
    let version1 : UInt

    QUIC version 1 (RFC 9000 §15).

    version2

    source
    let version2 : UInt

    QUIC version 2 (RFC 9369 §3): the version number is the first four bytes of the SHA-256 of the string "QUICv2 version number", so no decimal 2 appears on the wire.

    versions

    source
    fn versions(dcid~ : Bytes, scid~ : Bytes, offered : ArrayView[UInt], first? : Int) -> Bytes

    A Version Negotiation packet (RFC 9000 §17.2.1): version zero and the versions the server will speak, with the connection IDs swapped from the packet that provoked it.

    first is the whole first byte. The RFC leaves every bit but the header form arbitrary and asks a server to vary them, so it is the caller's to choose; the default sets the form bit alone.

    Source Files