net-wire 0.1.0

Allocation-free no_std wire views and codecs for network protocols.
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117

//! HTTP/3 handoff from typed field-section frames to the QPACK decoder.
//!
//! This module deliberately owns only the typed HTTP/3-to-QPACK boundary. Stream state,
//! blocked-section retention, and QPACK decoder feedback remain caller responsibilities.

use core::fmt;

use crate::qpack::field::section::decode::{
    QpackFieldSectionDecodeError, QpackFieldSectionDecodeOutcome, QpackFieldSectionDecoder,
    QpackFieldSectionOutput,
};
use crate::qpack::table::dynamic::QpackDynamicTable;

use super::frame::{Http3Headers, Http3PushPromise};

/// Failure while decoding a QPACK field section carried by an HTTP/3 frame.
///
/// [`Self::DecompressionFailed`] is a peer-caused HTTP/3 connection error.
/// [`Self::OutputProvisioning`] reports insufficient caller output storage and is local, so it
/// must not be sent as an HTTP/3 peer error.
#[derive(Clone, Copy, Debug, Eq, PartialEq)]
pub enum Http3QpackFieldSectionError {
    /// The peer's field section failed QPACK decompression.
    DecompressionFailed(QpackFieldSectionDecodeError),
    /// Caller-provided decoded-field output was insufficient.
    OutputProvisioning(QpackFieldSectionDecodeError),
}

impl Http3QpackFieldSectionError {
    /// Returns the HTTP/3 connection error code when this failure is peer-caused.
    pub const fn error_code(self) -> Option<super::codepoints::Http3ErrorCode> {
        match self {
            Self::DecompressionFailed(_) => {
                Some(super::codepoints::Http3ErrorCode::QPACK_DECOMPRESSION_FAILED)
            }
            Self::OutputProvisioning(_) => None,
        }
    }
}

impl From<QpackFieldSectionDecodeError> for Http3QpackFieldSectionError {
    fn from(error: QpackFieldSectionDecodeError) -> Self {
        match error.is_decompression_failed() {
            true => Self::DecompressionFailed(error),
            false => Self::OutputProvisioning(error),
        }
    }
}

impl fmt::Display for Http3QpackFieldSectionError {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        match self {
            Self::DecompressionFailed(error) => {
                write!(f, "HTTP/3 QPACK decompression failed: {error}")
            }
            Self::OutputProvisioning(error) => {
                write!(
                    f,
                    "HTTP/3 QPACK output provisioning failed locally: {error}"
                )
            }
        }
    }
}

impl core::error::Error for Http3QpackFieldSectionError {
    fn source(&self) -> Option<&(dyn core::error::Error + 'static)> {
        match self {
            Self::DecompressionFailed(error) | Self::OutputProvisioning(error) => Some(error),
        }
    }
}

impl Http3Headers<'_> {
    /// Decodes this HEADERS frame's exact encoded field section into caller-owned output.
    ///
    /// The QPACK decoder's transactional output and table guarantees are preserved. A
    /// [`QpackFieldSectionDecodeOutcome::Blocked`] result is successful; retry this same field
    /// section after the dynamic table's insert count advances. Output-provisioning failures are
    /// local caller errors, not HTTP/3 peer errors.
    pub fn decode_field_section<'output>(
        &self,
        decoder: &QpackFieldSectionDecoder,
        table: &QpackDynamicTable<'_, '_>,
        output: &'output mut QpackFieldSectionOutput<'_, '_>,
    ) -> Result<QpackFieldSectionDecodeOutcome<'output>, Http3QpackFieldSectionError> {
        decode_field_section(self.encoded_field_section(), decoder, table, output)
    }
}

impl Http3PushPromise<'_> {
    /// Decodes this PUSH_PROMISE frame's exact encoded field section into caller-owned output.
    ///
    /// The QPACK decoder's transactional output and table guarantees are preserved. A
    /// [`QpackFieldSectionDecodeOutcome::Blocked`] result is successful; retry this same field
    /// section after the dynamic table's insert count advances. Output-provisioning failures are
    /// local caller errors, not HTTP/3 peer errors.
    pub fn decode_field_section<'output>(
        &self,
        decoder: &QpackFieldSectionDecoder,
        table: &QpackDynamicTable<'_, '_>,
        output: &'output mut QpackFieldSectionOutput<'_, '_>,
    ) -> Result<QpackFieldSectionDecodeOutcome<'output>, Http3QpackFieldSectionError> {
        decode_field_section(self.encoded_field_section(), decoder, table, output)
    }
}

fn decode_field_section<'output>(
    encoded_field_section: &[u8],
    decoder: &QpackFieldSectionDecoder,
    table: &QpackDynamicTable<'_, '_>,
    output: &'output mut QpackFieldSectionOutput<'_, '_>,
) -> Result<QpackFieldSectionDecodeOutcome<'output>, Http3QpackFieldSectionError> {
    decoder
        .decode(encoded_field_section, table, output)
        .map_err(Http3QpackFieldSectionError::from)
}