mod error;
mod headers;
mod priority;
mod settings;
mod window_update;
pub use error::FrameError;
use headers::PendingHeaders;
pub use headers::{
ContinuationFlag, ContinuationFlagName, ContinuationFlags, ContinuationFrame, HeaderField,
HeadersFlag, HeadersFlagName, HeadersFlags, HeadersFrame,
};
use httlib_hpack::Decoder;
pub use priority::{PriorityFrame, StreamDependency};
use serde::{de, Deserialize, Deserializer, Serialize};
pub use settings::{Setting, SettingValue, SettingsFrame};
pub use window_update::WindowUpdateFrame;
const FRAME_HEADER_LEN: usize = 9;
#[derive(Debug, Default)]
pub struct FrameParser {
pending_headers: Option<PendingHeaders>,
hpack_decoder: Decoder<'static>,
}
#[derive(Debug)]
#[must_use]
pub enum FrameParseOutcome {
Incomplete,
Consumed {
bytes: usize,
frame: Option<Frame>,
},
}
impl FrameParseOutcome {
#[inline]
pub const fn consumed(&self) -> usize {
match self {
Self::Incomplete => 0,
Self::Consumed { bytes, .. } => *bytes,
}
}
#[inline]
pub fn into_frame(self) -> Option<Frame> {
match self {
Self::Incomplete => None,
Self::Consumed { frame, .. } => frame,
}
}
}
#[derive(Debug, thiserror::Error)]
#[error("failed to parse the HTTP/2 frame after {consumed} bytes: {source}")]
pub struct FrameParseError {
pub consumed: usize,
#[source]
pub source: FrameError,
}
impl FrameParser {
pub fn parse(&mut self, data: &[u8]) -> Result<FrameParseOutcome, FrameParseError> {
if data.len() < FRAME_HEADER_LEN {
return Ok(FrameParseOutcome::Incomplete);
}
let header = &data[..FRAME_HEADER_LEN];
let length = u32::from_be_bytes([0, header[0], header[1], header[2]]) as usize;
let ty = header[3];
let flags = header[4];
let stream_id = u32::from_be_bytes([header[5] & 0x7f, header[6], header[7], header[8]]);
let Some(frame_len) = FRAME_HEADER_LEN.checked_add(length) else {
return Err(FrameParseError {
consumed: data.len(),
source: FrameError::BadFrameSize,
});
};
if data.len() < frame_len {
return Ok(FrameParseOutcome::Incomplete);
}
let payload = &data[FRAME_HEADER_LEN..frame_len];
match self.parse_payload(ty, flags, stream_id, payload) {
Ok(frame) => Ok(FrameParseOutcome::Consumed {
bytes: frame_len,
frame,
}),
Err(source) => {
self.pending_headers = None;
if matches!(&source, FrameError::CompressionError) {
self.hpack_decoder = Decoder::default();
}
Err(FrameParseError {
consumed: frame_len,
source,
})
}
}
}
#[inline]
pub fn reset(&mut self) {
self.pending_headers = None;
self.hpack_decoder = Decoder::default();
}
#[inline]
pub const fn is_waiting_for_continuation(&self) -> bool {
self.pending_headers.is_some()
}
fn parse_payload(
&mut self,
ty: u8,
flags: u8,
stream_id: u32,
payload: &[u8],
) -> Result<Option<Frame>, FrameError> {
if let Some(pending) = self.pending_headers.as_mut() {
if ty != 0x9 {
return Err(FrameError::ExpectedContinuation);
}
if !pending.push_continuation(flags, stream_id, payload)? {
return Ok(None);
}
let Some(pending) = self.pending_headers.take() else {
return Err(FrameError::MalformedMessage);
};
return pending
.finish(&mut self.hpack_decoder)
.map(Frame::Headers)
.map(Some);
}
match ty {
0x1 => {
let pending = PendingHeaders::try_from((flags, stream_id, payload))?;
if pending.is_complete() {
pending
.finish(&mut self.hpack_decoder)
.map(Frame::Headers)
.map(Some)
} else {
self.pending_headers = Some(pending);
Ok(None)
}
}
0x9 => Err(FrameError::UnexpectedContinuation),
_ => Frame::try_from((ty, flags, stream_id, payload)).map(Some),
}
}
}
#[derive(Debug, PartialEq, Eq, Serialize)]
#[serde(untagged)]
pub enum Frame {
Settings(SettingsFrame),
WindowUpdate(WindowUpdateFrame),
Priority(PriorityFrame),
Headers(HeadersFrame),
Unknown(UnknownFrame),
}
#[derive(Deserialize)]
#[serde(untagged)]
enum FrameRepr {
Settings(SettingsFrame),
WindowUpdate(WindowUpdateFrame),
Headers(HeadersFrame),
Priority(PriorityFrame),
Unknown(UnknownFrame),
}
impl<'de> Deserialize<'de> for Frame {
fn deserialize<D>(deserializer: D) -> Result<Self, D::Error>
where
D: Deserializer<'de>,
{
let frame = match FrameRepr::deserialize(deserializer)? {
FrameRepr::Settings(frame) if frame.frame_type == FrameType::Settings => {
Self::Settings(frame)
}
FrameRepr::WindowUpdate(frame) if frame.frame_type == FrameType::WindowUpdate => {
Self::WindowUpdate(frame)
}
FrameRepr::Headers(frame) if frame.frame_type == FrameType::Headers => {
Self::Headers(frame)
}
FrameRepr::Priority(frame) if frame.frame_type == FrameType::Priority => {
Self::Priority(frame)
}
FrameRepr::Unknown(frame) if frame.frame_type == FrameType::Unknown => {
Self::Unknown(frame)
}
_ => {
return Err(de::Error::custom(
"frame_type does not match HTTP/2 frame payload",
));
}
};
Ok(frame)
}
}
impl Frame {
#[inline]
pub const fn frame_type(&self) -> FrameType {
match self {
Self::Settings(_) => FrameType::Settings,
Self::WindowUpdate(_) => FrameType::WindowUpdate,
Self::Priority(_) => FrameType::Priority,
Self::Headers(_) => FrameType::Headers,
Self::Unknown(_) => FrameType::Unknown,
}
}
#[inline]
pub const fn stream_id(&self) -> u32 {
match self {
Self::Settings(frame) => frame.stream_id,
Self::WindowUpdate(frame) => frame.stream_id,
Self::Priority(frame) => frame.stream_id,
Self::Headers(frame) => frame.stream_id,
Self::Unknown(frame) => frame.stream_id,
}
}
#[inline]
pub const fn payload_len(&self) -> usize {
match self {
Self::Settings(frame) => frame.length,
Self::WindowUpdate(frame) => frame.length,
Self::Priority(frame) => frame.length,
Self::Headers(frame) => frame.length,
Self::Unknown(frame) => frame.length,
}
}
}
#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
pub enum FrameType {
Settings,
WindowUpdate,
Headers,
Continuation,
Priority,
Unknown,
}
#[derive(Debug, PartialEq, Eq, Serialize, Deserialize)]
#[serde(try_from = "UnknownFrameRepr")]
pub struct UnknownFrame {
pub frame_type: FrameType,
pub type_id: u8,
pub stream_id: u32,
pub length: usize,
pub flags: u8,
pub payload: Vec<u8>,
}
#[derive(Deserialize)]
struct UnknownFrameRepr {
frame_type: FrameType,
type_id: u8,
stream_id: u32,
length: usize,
flags: u8,
payload: Vec<u8>,
}
impl TryFrom<UnknownFrameRepr> for UnknownFrame {
type Error = &'static str;
fn try_from(repr: UnknownFrameRepr) -> Result<Self, Self::Error> {
if repr.frame_type != FrameType::Unknown {
return Err("unknown frame_type must be Unknown");
}
if matches!(repr.type_id, 0x1 | 0x2 | 0x4 | 0x8 | 0x9) {
return Err("a supported HTTP/2 frame type cannot use UnknownFrame");
}
if repr.stream_id > 0x7fff_ffff {
return Err("unknown frame stream_id must be a 31-bit value");
}
if repr.length > 0x00ff_ffff {
return Err("unknown frame payload length exceeds the HTTP/2 frame limit");
}
if repr.length != repr.payload.len() {
return Err("unknown frame length does not match its payload");
}
Ok(Self {
frame_type: repr.frame_type,
type_id: repr.type_id,
stream_id: repr.stream_id,
length: repr.length,
flags: repr.flags,
payload: repr.payload,
})
}
}
impl TryFrom<(u8, u8, u32, &[u8])> for Frame {
type Error = FrameError;
fn try_from(
(ty, flags, stream_id, payload): (u8, u8, u32, &[u8]),
) -> Result<Self, Self::Error> {
match ty {
0x1 => HeadersFrame::try_from((flags, stream_id, payload)).map(Frame::Headers),
0x2 => PriorityFrame::try_from((stream_id, payload)).map(Frame::Priority),
0x4 => SettingsFrame::try_from((flags, stream_id, payload)).map(Frame::Settings),
0x8 => WindowUpdateFrame::try_from((stream_id, payload)).map(Frame::WindowUpdate),
0x9 => Err(FrameError::UnexpectedContinuation),
_ => {
let frame = UnknownFrame {
frame_type: FrameType::Unknown,
type_id: ty,
stream_id,
length: payload.len(),
flags,
payload: payload.to_vec(),
};
Ok(Frame::Unknown(frame))
}
}
}
}
#[cfg(test)]
mod tests {
use super::{Frame, FrameError, FrameParseOutcome, FrameParser, HeadersFrame, UnknownFrame};
#[test]
fn headers_are_decoded_after_continuation_completes_the_block() {
let mut parser = FrameParser::default();
let headers = [0, 0, 1, 0x1, 0x1, 0, 0, 0, 1, 0x82];
let continuation = [0, 0, 1, 0x9, 0x4, 0, 0, 0, 1, 0x84];
let parsed = parser.parse(&headers).unwrap();
assert_eq!(parsed.consumed(), headers.len());
assert!(parsed.into_frame().is_none());
let parsed = parser.parse(&continuation).unwrap();
assert_eq!(parsed.consumed(), continuation.len());
let Some(Frame::Headers(frame)) = parsed.into_frame() else {
panic!("expected the completed HEADERS frame");
};
assert_eq!(&*frame.headers[0].name, b":method");
assert_eq!(&*frame.headers[0].value, b"GET");
assert_eq!(&*frame.headers[1].name, b":path");
assert_eq!(&*frame.headers[1].value, b"/");
assert_eq!(frame.continuations.len(), 1);
let json = serde_json::to_vec(&frame).unwrap();
let restored: HeadersFrame = serde_json::from_slice(&json).unwrap();
assert_eq!(restored, frame);
}
#[test]
fn incomplete_frame_is_not_an_error() {
let parsed = FrameParser::default().parse(&[0, 0, 1]).unwrap();
assert!(matches!(parsed, FrameParseOutcome::Incomplete));
assert_eq!(parsed.consumed(), 0);
}
#[test]
fn continuation_must_use_the_open_field_block_stream() {
let mut parser = FrameParser::default();
let headers = [0, 0, 1, 0x1, 0, 0, 0, 0, 1, 0x82];
let wrong_stream = [0, 0, 1, 0x9, 0x4, 0, 0, 0, 3, 0x84];
assert_eq!(parser.parse(&headers).unwrap().consumed(), headers.len());
let error = parser.parse(&wrong_stream).unwrap_err();
assert_eq!(error.consumed, wrong_stream.len());
assert_eq!(error.source, FrameError::UnexpectedContinuation);
assert!(parser.pending_headers.is_none());
}
#[test]
fn unknown_frames_retain_wire_metadata() {
let bytes = [0, 0, 2, 0x0a, 0xa5, 0, 0, 0, 7, 1, 2];
let parsed = FrameParser::default().parse(&bytes).unwrap();
let Some(Frame::Unknown(frame)) = parsed.into_frame() else {
panic!("expected an unknown frame");
};
assert_eq!(frame.type_id, 0x0a);
assert_eq!(frame.flags, 0xa5);
assert_eq!(frame.stream_id, 7);
assert_eq!(frame.payload, [1, 2]);
let json = serde_json::to_vec(&frame).unwrap();
let restored: UnknownFrame = serde_json::from_slice(&json).unwrap();
assert_eq!(restored, frame);
}
#[test]
fn hpack_dynamic_table_is_shared_across_field_sections() {
let mut parser = FrameParser::default();
let first = [
0, 0, 9, 0x1, 0x4, 0, 0, 0, 1, 0x40, 3, b'f', b'o', b'o', 3, b'b', b'a', b'r',
];
let second = [0, 0, 1, 0x1, 0x4, 0, 0, 0, 3, 0xbe];
let Some(Frame::Headers(first)) = parser.parse(&first).unwrap().into_frame() else {
panic!("expected the first HEADERS frame");
};
let Some(Frame::Headers(second)) = parser.parse(&second).unwrap().into_frame() else {
panic!("expected the second HEADERS frame");
};
assert_eq!(first.headers, second.headers);
assert_eq!(&*second.headers[0].name, b"foo");
assert_eq!(&*second.headers[0].value, b"bar");
}
#[test]
fn hpack_decode_error_discards_partial_dynamic_table_updates() {
let mut parser = FrameParser::default();
let malformed = [0, 0, 6, 0x1, 0x4, 0, 0, 0, 1, 0x40, 1, b'x', 1, b'y', 0x80];
let dynamic_reference = [0, 0, 1, 0x1, 0x4, 0, 0, 0, 3, 0xbe];
let error = parser.parse(&malformed).unwrap_err();
assert_eq!(error.source, FrameError::CompressionError);
let error = parser.parse(&dynamic_reference).unwrap_err();
assert_eq!(error.source, FrameError::CompressionError);
}
#[test]
fn unknown_frame_deserialization_rejects_supported_types_and_bad_lengths() {
let supported_type = r#"{
"frame_type":"Unknown",
"type_id":1,
"stream_id":1,
"length":1,
"flags":0,
"payload":[0]
}"#;
let bad_length = r#"{
"frame_type":"Unknown",
"type_id":10,
"stream_id":1,
"length":2,
"flags":0,
"payload":[0]
}"#;
assert!(serde_json::from_str::<UnknownFrame>(supported_type).is_err());
assert!(serde_json::from_str::<UnknownFrame>(bad_length).is_err());
}
}