Project: Pipy (Orchestration & Management / Service Proxy)
File: rx-depacketizer.md

RX depacketizer =============== This component takes a QUIC packet and parses the frames contained therein, to be forwarded to appropriate other components for further processing. In the [overview], this is called the "RX Frame Handler". The name "RX depacketizer" was chosen to reflect the kinship with the [TX packetizer]. Main structures Represented by an `QUIC_CONNECTION` object, defined in . Represented by an `QUIC_STREAM` object (yet to be defined). Represented by the `OSSLQRXPKT` structure, defined in `include/internal/quicrecordrx.h` in [QUIC Demuxer and Record Layer (RX+TX)]. Interactions The RX depacketizer receives a packet from the QUIC Read Record Layer, and then processes frames in two phases: There are a number of other components that the RX depacketizer wants to interact with: [ACK manager] Handshake manager, which is currently unspecified. It's assumed that this will wrap around what is called the "TLS Handshake Record Layer", in the [overview] Session manager, which is currently unspecified for QUIC, but may very well be the existing `SSL_SESSION` functionality, extended to fit QUIC purposes. Flow control, which is currently unspecified. In the [overview], it's called the "Flow Controller And Statistics Collector" Connection manager, which is currently unspecified. In the [overview], there's a "Connection State Machine" that the "RX Frame Handler" isn't talking directly with, so it's possible that the Connection manager will turn out to be the Handshake manager. Stream SSL objects, to pass the stream data to. Following how things are designed elsewhere, the depacketizer is assumed to be called "from above" using the following function: ``` C owur int osslquicdepacketize(QUIC_CONNECTION *connection); ``` This function would create an `OSSLQRXPKT` and call the QUIC Read Record Layer with a pointer to it, leaving it to the QUIC Read Record Layer to fill in the data. This uses the `osslqrxread_pkt()` packet reading function from [QUIC Demuxer and Record Layer (RX+TX)]. (the `OSSLQRXPKT` structure / sub-structure needs to be extended to take an `OSSL_TIME`, possibly by reference, which should be filled in with the packet reception time) This collects appropriate data into a `QUICACKMRX_PKT` structure: The packet number (`packet->packet_number`) The packet receive time (`received`) The packet space, which is always: `QUICPNSPACEINITIAL` when `packet->packettype == pkt_initial` `QUICPNSPACEHANDSHAKE` when `packet->packettype == pkt_handshake` `QUICPNSPACE_APP` for all other packet types The ACK eliciting flag. This is calculated by looping through all frames and noting those that are ACK eliciting, as determined from below) This loops through all the frames, extracts data where there is any and calls diverse other components as shown in the Passed to column in below. Taken from [RFC 9000 12.4 Frames and Frame Types] | Type | Name | Passed to | ACK eliciting | I | H | 0 | 1 | ||-|--||-|-|-|-| | 0x00 | [padding] | - | | &#10004; | &#10004; | &#10004; | &#10004; | | 0x01 | [ping] | - | &#10004; | &#10004; | &#10004; | &#10004; | &#10004; | | 0x02 | [ack 0x02] | [ACK manager] [^1] | | &#10004; | &#10004; | | &#10004; | | 0x03 | [ack 0x03] | [ACK manager] [^1] | | &#10004; | &#10004; | | &#10004; | | 0x04 | [reset_stream] | - [^2] | &#10004; | | | &#10004; | &#10004; | | 0x05 | [stop_sending] | - [^3] | &#10004; | | | &#10004; | &#10004; | | 0x06 | [crypto] | Handshake manager | &#10004; | &#10004; | &#10004; | | &#10004; | | 0x07 | [new_token] | Session manager

&#10004; | | | | &#10004; | | 0x08 | [stream 0x08] | Apprioriate stream [^4] | &#10004; | | | &#10004; | &#10004; | | 0x09 | [stream 0x09] | Apprioriate stream [^4] | &#10004; | | | &#10004; | &#10004; | | 0x0A | [stream 0x0A] | Apprioriate stream [^4] | &#10004; | | | &#10004; | &#10004; | | 0x0B | [stream 0x0B] | Apprioriate stream [^4] | &#10004; | | | &#10004; | &#10004; | | 0x0C | [stream 0x0C] | Apprioriate stream [^4] | &#10004; | | | &#10004; | &#10004; | | 0x0D | [stream 0x0D] | Apprioriate stream [^4] | &#10004; | | | &#10004; | &#10004; | | 0x0E | [stream 0x0E] | Apprioriate stream [^4] | &#10004; | | | &#10004; | &#10004; | | 0x0F | [stream 0x0F] | Apprioriate stream [^4] | &#10004; | | | &#10004; | &#10004; | | 0x10 | [max_data] | Flow control [^5] | &#10004; | | | &#10004; | &#10004; | | 0x11 | [maxstreamdata] | Flow control [^5] | &#10004; | | | &#10004; | &#10004; | | 0x12 | [max_streams 0x12] | Connection manager? [^6] | &#10004; | | | &#10004; | &#10004; | | 0x13 | [max_streams 0x13] | Connection manager? [^6] | &#10004; | | | &#10004; | &#10004; | | 0x14 | [data_blocked] | Flow control [^5] | &#10004; | | | &#10004; | &#10004; | | 0x15 | [streamdatablocked] | Flow control [^5] | &#10004; | | | &#10004; | &#10004; | | 0x16 | [streams_blocked 0x16] | Connection manager? [^6] | &#10004; | | | &#10004; | &#10004; | | 0x17 | [streams_blocked 0x17] | Connection manager? [^6] | &#10004; | | | &#10004; | &#10004; | | 0x18 | [newconnectionid] | Connection manager | &#10004; | | | &#10004; | &#10004; | | 0x19 | [retireconnectionid] | Connection manager | &#10004; | | | &#10004; | &#10004; | | 0x1A | [path_challenge] | Connection manager? [^7] | &#10004; | | | &#10004; | &#10004; | | 0x1B | [path_response] | Connection manager? [^7] | &#10004; | | | | &#10004; | | 0x1C | [connection_close 0x1C] | Connection manager | | &#10004; | &#10004; | &#10004; | &#10004; | | 0x1D | [connection_close 0x1D] | Connection manager | | | | &#10004; | &#10004; | | 0x1E | [handshake_done] | Handshake manager | &#10004; | | | | &#10004; | | ???? | [Extension Frames] | - [^8] | &#10004; | | | | | The I, H, 0, and 1 columns are validity in different packet types, with this meaning: | Pkts | Description | |:-:|-| | I | Valid in Initial packets | | H | Valid in Handshake packets | | 0 | Valid in 0-RTT packets | | 1 | Valid in 1-RTT packets | Notes: `QUICACKMonrxack_frame()`, with the appropriate context (`QUICACKM`, the created `QUICACKMACK`, `pktspace` and `rx_time`) object. This includes discarding any buffered application data. For a stream that's send-only, the error `STREAMSTATEERROR` is raised, and the `QUIC_CONNECTION` object is terminated. object. For a stream that's receive-only, the error `STREAMSTATEERROR` is raised, and the `QUIC_CONNECTION` object is terminated. object, along with available metadata (offset and length, as determined to be available from the lower 3 bits of the frame type). manager before anything else. before anything else. must at least acknowledge their presence, so much is clear from the RFC.