use bytes::{Buf, BytesMut};
use super::frame::{
parse_headers, parse_settings, Frame, FrameType, Http3FrameError, OpaqueFrame, StreamType,
StreamTypeName,
};
use crate::{quic::varint, tls::HexBytes};
const DEFAULT_BUFFER_CAPACITY: usize = 2048;
const DEFAULT_MAX_FRAME_SIZE: usize = 1024 * 1024;
const DEFAULT_MAX_FIELD_SECTION_SIZE: u64 = 1024 * 1024;
#[derive(Debug, PartialEq, Eq, thiserror::Error)]
#[non_exhaustive]
pub enum Http3ParseError {
#[error("incomplete HTTP/3 stream input")]
IncompleteInput {
buffered_bytes: usize,
waiting_for_stream_type: bool,
},
#[error("HTTP/3 frame length {length} exceeds the configured limit {limit}")]
FrameTooLarge {
length: u64,
limit: usize,
},
#[error("HTTP/3 frame length exceeds the platform limit")]
LengthOverflow,
#[error("the HTTP/3 control stream must begin with SETTINGS")]
ExpectedSettings,
#[error("the HTTP/3 control stream contains a second SETTINGS frame")]
DuplicateSettingsFrame,
#[error("an HTTP/3 request stream must begin with HEADERS")]
ExpectedHeaders,
#[error("HTTP/3 stream type {type_id} is not valid for a client-initiated stream")]
UnexpectedStreamType {
type_id: u64,
},
#[error("HTTP/3 frame type {type_id} is not valid on this stream")]
UnexpectedFrame {
type_id: u64,
},
#[error(transparent)]
Frame(#[from] Http3FrameError),
}
#[derive(Debug, thiserror::Error)]
#[error("{error}")]
pub struct Http3PushError {
completed_frames: Vec<Frame>,
#[source]
error: Http3ParseError,
}
impl Http3PushError {
pub fn completed_frames(&self) -> &[Frame] {
&self.completed_frames
}
pub const fn error(&self) -> &Http3ParseError {
&self.error
}
pub fn into_parts(self) -> (Vec<Frame>, Http3ParseError) {
(self.completed_frames, self.error)
}
fn into_error(self) -> Http3ParseError {
self.error
}
}
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
enum StreamKind {
Request,
Unidirectional,
}
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
enum RequestState {
Initial,
Body,
Trailers,
}
#[derive(Debug)]
pub struct Http3Parser {
buffer: BytesMut,
kind: StreamKind,
stream_type: Option<StreamType>,
ignored: bool,
frame_count: usize,
request_state: RequestState,
max_frame_size: usize,
max_field_section_size: u64,
}
impl Http3Parser {
pub fn request() -> Self {
Self::request_with_capacity(DEFAULT_BUFFER_CAPACITY)
}
pub fn request_with_capacity(capacity: usize) -> Self {
Self::request_with_capacity_and_limits(
capacity,
DEFAULT_MAX_FRAME_SIZE,
DEFAULT_MAX_FIELD_SECTION_SIZE,
)
}
pub fn request_with_limits(max_frame_size: usize, max_field_section_size: u64) -> Self {
Self::request_with_capacity_and_limits(
DEFAULT_BUFFER_CAPACITY.min(max_frame_size),
max_frame_size,
max_field_section_size,
)
}
pub fn request_with_capacity_and_limits(
capacity: usize,
max_frame_size: usize,
max_field_section_size: u64,
) -> Self {
Self::with_capacity_and_limits(
StreamKind::Request,
capacity,
max_frame_size,
max_field_section_size,
)
}
pub fn unidirectional() -> Self {
Self::unidirectional_with_capacity(DEFAULT_BUFFER_CAPACITY)
}
pub fn unidirectional_with_capacity(capacity: usize) -> Self {
Self::unidirectional_with_capacity_and_limits(
capacity,
DEFAULT_MAX_FRAME_SIZE,
DEFAULT_MAX_FIELD_SECTION_SIZE,
)
}
pub fn unidirectional_with_limits(max_frame_size: usize, max_field_section_size: u64) -> Self {
Self::unidirectional_with_capacity_and_limits(
DEFAULT_BUFFER_CAPACITY.min(max_frame_size),
max_frame_size,
max_field_section_size,
)
}
pub fn unidirectional_with_capacity_and_limits(
capacity: usize,
max_frame_size: usize,
max_field_section_size: u64,
) -> Self {
Self::with_capacity_and_limits(
StreamKind::Unidirectional,
capacity,
max_frame_size,
max_field_section_size,
)
}
fn with_capacity_and_limits(
kind: StreamKind,
capacity: usize,
max_frame_size: usize,
max_field_section_size: u64,
) -> Self {
Self {
buffer: BytesMut::with_capacity(capacity),
kind,
stream_type: None,
ignored: false,
frame_count: 0,
request_state: RequestState::Initial,
max_frame_size,
max_field_section_size,
}
}
pub fn capacity(&self) -> usize {
self.buffer.capacity()
}
pub const fn max_frame_size(&self) -> usize {
self.max_frame_size
}
pub const fn max_field_section_size(&self) -> u64 {
self.max_field_section_size
}
pub fn push(&mut self, data: &[u8]) -> Result<Vec<Frame>, Http3PushError> {
let mut frames = Vec::new();
if let Err(error) = self.push_into(data, &mut frames) {
return Err(Http3PushError {
completed_frames: frames,
error,
});
}
Ok(frames)
}
pub fn push_into(
&mut self,
data: &[u8],
output: &mut Vec<Frame>,
) -> Result<usize, Http3ParseError> {
let initial_len = output.len();
if self.ignored {
return Ok(0);
}
self.buffer.extend_from_slice(data);
if self.kind == StreamKind::Unidirectional && self.stream_type.is_none() {
let Some((type_id, consumed)) = varint::decode(&self.buffer) else {
return Ok(0);
};
self.buffer.advance(consumed);
let stream_type = StreamType::from_id(type_id);
self.stream_type = Some(stream_type);
if stream_type.name == StreamTypeName::Push {
self.buffer.clear();
return Err(Http3ParseError::UnexpectedStreamType { type_id });
}
self.ignored = stream_type.name != StreamTypeName::Control;
if self.ignored {
self.buffer.clear();
return Ok(0);
}
}
while let Some((type_id, type_len)) = varint::decode(&self.buffer) {
let Some((length, length_len)) = varint::decode(&self.buffer[type_len..]) else {
break;
};
if length > self.max_frame_size as u64 {
self.buffer.clear();
return Err(Http3ParseError::FrameTooLarge {
length,
limit: self.max_frame_size,
});
}
let length = usize::try_from(length).map_err(|_| Http3ParseError::LengthOverflow)?;
let header_len = type_len
.checked_add(length_len)
.ok_or(Http3ParseError::LengthOverflow)?;
let frame_len = header_len
.checked_add(length)
.ok_or(Http3ParseError::LengthOverflow)?;
let Some(payload) = self.buffer.get(header_len..frame_len) else {
break;
};
let frame = match self.parse_frame(type_id, payload) {
Ok(frame) => frame,
Err(error) => {
self.buffer.advance(frame_len);
return Err(error);
}
};
self.buffer.advance(frame_len);
self.record_frame(type_id);
self.frame_count = self.frame_count.saturating_add(1);
output.push(frame);
}
Ok(output.len() - initial_len)
}
pub const fn stream_type(&self) -> Option<StreamType> {
self.stream_type
}
pub const fn is_ignored(&self) -> bool {
self.ignored
}
pub fn buffered_len(&self) -> usize {
self.buffer.len()
}
pub fn is_idle(&self) -> bool {
if self.ignored {
return true;
}
let stream_type_complete = self.kind == StreamKind::Request || self.stream_type.is_some();
stream_type_complete && self.buffer.is_empty()
}
pub fn finish(&self) -> Result<(), Http3ParseError> {
if !self.is_idle() {
return Err(Http3ParseError::IncompleteInput {
buffered_bytes: self.buffer.len(),
waiting_for_stream_type: self.kind == StreamKind::Unidirectional
&& self.stream_type.is_none(),
});
}
if self.ignored {
return Ok(());
}
match self.kind {
StreamKind::Request if self.request_state == RequestState::Initial => {
Err(Http3ParseError::ExpectedHeaders)
}
StreamKind::Unidirectional => match self.stream_type {
Some(stream_type) if stream_type.name == StreamTypeName::Push => {
Err(Http3ParseError::UnexpectedStreamType {
type_id: stream_type.id,
})
}
Some(stream_type)
if stream_type.name == StreamTypeName::Control && self.frame_count == 0 =>
{
Err(Http3ParseError::ExpectedSettings)
}
_ => Ok(()),
},
StreamKind::Request => Ok(()),
}
}
pub fn clear(&mut self) {
self.buffer.clear();
self.stream_type = None;
self.ignored = false;
self.frame_count = 0;
self.request_state = RequestState::Initial;
}
fn parse_frame(&self, type_id: u64, payload: &[u8]) -> Result<Frame, Http3ParseError> {
let frame_type = FrameType::from_id(type_id);
if frame_type.is_http2_reserved() {
return Err(Http3ParseError::UnexpectedFrame { type_id });
}
match self.kind {
StreamKind::Unidirectional => {
if self.frame_count == 0 && type_id != 0x04 {
return Err(Http3ParseError::ExpectedSettings);
}
if type_id == 0x04 && self.frame_count > 0 {
return Err(Http3ParseError::DuplicateSettingsFrame);
}
if matches!(type_id, 0x00 | 0x01 | 0x05) {
return Err(Http3ParseError::UnexpectedFrame { type_id });
}
}
StreamKind::Request => {
if matches!(
type_id,
0x03 | 0x04 | 0x05 | 0x07 | 0x0c | 0x0d | 0x0f_0700 | 0x0f_0701
) {
return Err(Http3ParseError::UnexpectedFrame { type_id });
}
if self.request_state == RequestState::Initial && type_id == 0x00 {
return Err(Http3ParseError::ExpectedHeaders);
}
if self.request_state == RequestState::Trailers && matches!(type_id, 0x00 | 0x01) {
return Err(Http3ParseError::UnexpectedFrame { type_id });
}
}
}
match type_id {
0x01 => parse_headers(payload, self.max_field_section_size)
.map(Frame::Headers)
.map_err(Into::into),
0x04 => parse_settings(payload)
.map(Frame::Settings)
.map_err(Into::into),
_ => Ok(Frame::Opaque(OpaqueFrame {
frame_type,
type_id,
length: payload.len(),
payload: HexBytes::from(payload),
})),
}
}
fn record_frame(&mut self, type_id: u64) {
if self.kind != StreamKind::Request || type_id != 0x01 {
return;
}
self.request_state = match self.request_state {
RequestState::Initial => RequestState::Body,
RequestState::Body | RequestState::Trailers => RequestState::Trailers,
};
}
}
impl Default for Http3Parser {
fn default() -> Self {
Self::request()
}
}
pub fn parse_request_stream(data: &[u8]) -> Result<Vec<Frame>, Http3ParseError> {
parse_complete(Http3Parser::request(), data)
}
pub fn parse_unidirectional_stream(data: &[u8]) -> Result<Vec<Frame>, Http3ParseError> {
parse_complete(Http3Parser::unidirectional(), data)
}
fn parse_complete(mut parser: Http3Parser, data: &[u8]) -> Result<Vec<Frame>, Http3ParseError> {
let frames = parser.push(data).map_err(Http3PushError::into_error)?;
parser.finish()?;
Ok(frames)
}
#[cfg(test)]
mod tests {
use bytes::BytesMut;
use super::{parse_request_stream, parse_unidirectional_stream, Http3ParseError, Http3Parser};
use crate::{
h3::{Frame, FrameType, Http3FrameError, SettingValue},
quic::varint,
};
#[test]
fn configured_constructors_apply_limits_before_input() {
let mut frame_limited = Http3Parser::request_with_limits(2, 64);
assert!(frame_limited.capacity() >= 2);
assert_eq!(frame_limited.max_frame_size(), 2);
assert_eq!(frame_limited.max_field_section_size(), 64);
let error = frame_limited.push(&[0x01, 0x03]).unwrap_err();
assert_eq!(
error.error(),
&Http3ParseError::FrameTooLarge {
length: 3,
limit: 2,
}
);
let parser = Http3Parser::unidirectional_with_capacity_and_limits(4096, 32, 16);
assert!(parser.capacity() >= 4096);
assert_eq!(parser.max_frame_size(), 32);
assert_eq!(parser.max_field_section_size(), 16);
}
#[test]
fn configured_field_section_limit_reaches_qpack_decoder() {
let headers = [0x01, 0x03, 0x00, 0x00, 0xd1];
let mut parser = Http3Parser::request_with_limits(64, 1);
let error = parser.push(&headers).unwrap_err();
assert_eq!(
error.error(),
&Http3ParseError::Frame(Http3FrameError::QpackDecompression)
);
let mut parser = Http3Parser::request_with_limits(64, 64);
assert!(matches!(
parser.push(&headers).unwrap().as_slice(),
[Frame::Headers(_)]
));
}
#[test]
fn control_stream_settings_accept_arbitrary_chunks() {
let mut input = vec![0x00, 0x04, 0x05, 0x01];
input.extend_from_slice(&[0x80, 0x01, 0x00, 0x00]);
let mut parser = Http3Parser::unidirectional();
let mut frames = Vec::new();
for chunk in input.chunks(2) {
parser.push_into(chunk, &mut frames).unwrap();
}
parser.finish().unwrap();
let Frame::Settings(frame) = &frames[0] else {
panic!("expected SETTINGS");
};
assert_eq!(frame.settings[0].value, SettingValue::Number(65_536));
}
#[test]
fn request_headers_are_qpack_decoded_in_wire_order() {
let mut block = BytesMut::from(&[0x00, 0x00, 0xd1, 0x51, 0x0a][..]);
block.extend_from_slice(b"/api/http3");
block.extend_from_slice(&[0x5f, 0x50, 0x0b]);
block.extend_from_slice(b"pingly-test");
let mut input = Vec::new();
varint::encode(1, &mut input).unwrap();
varint::encode(block.len() as u64, &mut input).unwrap();
input.extend_from_slice(&block);
let frames = parse_request_stream(&input).unwrap();
let Frame::Headers(frame) = &frames[0] else {
panic!("expected HEADERS");
};
assert_eq!(&*frame.headers[0].name, b":method");
assert_eq!(&*frame.headers[1].name, b":path");
assert_eq!(&*frame.headers[2].value, b"pingly-test");
}
#[test]
fn request_stream_allows_extension_frames_before_headers() {
let input = [0x21, 0x00, 0x01, 0x03, 0x00, 0x00, 0xd1];
let frames = parse_request_stream(&input).unwrap();
assert!(matches!(
&frames[0],
Frame::Opaque(frame) if frame.type_id == 0x21 && frame.frame_type == FrameType::Grease
));
assert!(matches!(&frames[1], Frame::Headers(_)));
}
#[test]
fn registered_frames_obey_client_stream_locations() {
let control_with_data = [0x00, 0x04, 0x00, 0x00, 0x00];
assert_eq!(
parse_unidirectional_stream(&control_with_data).unwrap_err(),
Http3ParseError::UnexpectedFrame { type_id: 0 }
);
for type_id in [0x03, 0x04, 0x05, 0x07, 0x0c, 0x0d, 0x0f_0700, 0x0f_0701] {
let mut input = Vec::new();
varint::encode(type_id, &mut input).unwrap();
input.push(0x00);
assert_eq!(
parse_request_stream(&input).unwrap_err(),
Http3ParseError::UnexpectedFrame { type_id }
);
}
for type_id in [0x02, 0x06, 0x08, 0x09] {
let input = [type_id as u8, 0x00];
assert_eq!(
parse_request_stream(&input).unwrap_err(),
Http3ParseError::UnexpectedFrame { type_id }
);
}
let data_after_trailers = [
0x01, 0x03, 0x00, 0x00, 0xd1, 0x01, 0x03, 0x00, 0x00, 0xd1, 0x00, 0x00,
];
assert_eq!(
parse_request_stream(&data_after_trailers).unwrap_err(),
Http3ParseError::UnexpectedFrame { type_id: 0 }
);
}
#[test]
fn non_control_unidirectional_streams_are_identified_and_ignored() {
let frames = parse_unidirectional_stream(&[0x02, 0xff, 0xff]).unwrap();
assert!(frames.is_empty());
let frames = parse_unidirectional_stream(&[0x04, 0xff, 0xff]).unwrap();
assert!(frames.is_empty());
let mut parser = Http3Parser::unidirectional();
parser.push(&[0x02]).unwrap();
assert!(parser.is_ignored());
assert_eq!(parser.stream_type().unwrap().id, 2);
}
#[test]
fn client_push_streams_are_rejected_explicitly() {
assert_eq!(
parse_unidirectional_stream(&[0x01, 0x00]).unwrap_err(),
Http3ParseError::UnexpectedStreamType { type_id: 0x01 }
);
}
#[test]
fn complete_streams_require_their_mandatory_initial_frame() {
assert_eq!(
parse_request_stream(&[]).unwrap_err(),
Http3ParseError::ExpectedHeaders
);
assert_eq!(
parse_request_stream(&[0x21, 0x00]).unwrap_err(),
Http3ParseError::ExpectedHeaders
);
assert_eq!(
parse_unidirectional_stream(&[0x00]).unwrap_err(),
Http3ParseError::ExpectedSettings
);
}
#[test]
fn stream_sequence_and_partial_input_are_rejected() {
assert_eq!(
parse_unidirectional_stream(&[0x00, 0x00, 0x00]).unwrap_err(),
Http3ParseError::ExpectedSettings
);
assert!(matches!(
parse_request_stream(&[0x01, 0x04, 0x00]),
Err(Http3ParseError::IncompleteInput { .. })
));
}
}