bookclerk_workerd::granted_http
Sans-IO HTTP/1.1 parsing for the granted reverse channel.
Every byte on the granted channel comes from a plugin isolate, so the
request head, the chunked body framing and the query string are parsed
here over plain byte slices, with no socket in sight. crate::granted
feeds these from its reader; unit tests and the granted_http fuzz
target feed them directly, so all three drive the same code
(docs/adr/untrusted-input-fuzzing.md).
Limits enforced here are structural (head size, chunk-size digits,
trailer count). Body byte caps belong to the route and stay in
crate::granted.
Parsing is strict rather than lenient: the only client is the plugin
runtime's own fetch, so anything RFC 9112 does not require accepting
(bare LF, whitespace before a chunk size, a second transfer coding) is
rejected and answered with 400 Bad Request instead of being guessed at.
| Item | Kind | Summary |
|---|---|---|
RequestHead |
struct | Parsed request line and headers. |
ChunkedProgress |
struct | Progress made by one ChunkedDecoder::decode call. |
ChunkedDecoder |
struct | Incremental Transfer-Encoding: chunked decoder. |
BodyReader |
struct | Sans-IO reader for one request body under its declared framing. |
HeadError |
enum | Why a request head was rejected. |
HeadParse |
enum | Outcome of parse_request_head on the bytes buffered so far. |
BodyFraming |
enum | How the request frames its body. |
FramingError |
enum | Why the body framing headers were rejected. |
ChunkedError |
enum | Why a chunked body was rejected. |
BodyError |
enum | Why a request body was rejected or cut short. |
parse_request_head |
function | Parses an HTTP/1.1 request head from the start of buf. |
header |
function | The first header named name (ASCII case-insensitive). |
transfer_encodings |
function | Every transfer coding named by the Transfer-Encoding headers, in wire order, lowercased and trimmed, with empty list elements dropped. |
transfer_encoding_is_chunked |
function | True when a Transfer-Encoding header lists the chunked coding as a token (so chunkedx or notchunked do not count). |
body_framing |
function | Decides the body framing from the headers. |
declared_content_length_over_cap |
function | True when a well-formed Content-Length declares more than cap bytes. A malformed one is left for body_framing to reject. |
declared_content_length_past_cap |
function | The declared Content-Length when it is past cap, in bytes. |
query_param |
function | The percent-decoded value of the first name= pair in query. |
percent_decode |
function | Decodes %HH escapes and + (as space); malformed escapes are kept as written, and the result is UTF-8 with replacement characters. |
MAX_HEAD_BYTES |
constant | Largest request head (request line plus headers plus the blank line) accepted before the connection is dropped. |
MAX_CHUNK_SIZE_DIGITS |
constant | Most hex digits a chunk-size field may carry. Sixteen digits already overflow u64; real clients send far fewer. |
MAX_CHUNK_LINE_BYTES |
constant | Longest chunk-size line (digits, extensions and CRLF) before the body is rejected as malformed. |
MAX_TRAILER_LINES |
constant | Most trailer lines accepted after the terminating chunk. |
pub struct RequestHead {
pub method: String,
pub path: String,
pub headers: Vec<(String, String)>,
}
Parsed request line and headers.
Fields
method: HTTP method token as sent (case preserved).path: Request target as sent, including any query string.headers: Header fields in wire order, names and values trimmed, names with their original case.
pub fn split_query(&self) -> (&str, &str)
The path without its query string, and the query string (empty when absent).
Implements: Clone, Debug, Eq, PartialEq
pub struct ChunkedProgress {
pub consumed: usize,
pub done: bool,
}
Progress made by one ChunkedDecoder::decode call.
Fields
consumed: Input bytes consumed; the caller drops them from its buffer.done: True once the terminating chunk and its trailers are consumed.
Implements: Clone, Copy, Debug, Eq, PartialEq
pub struct ChunkedDecoder {
/* private fields */
}
Incremental Transfer-Encoding: chunked decoder.
Decoding is incremental so a chunk of any declared size streams through without being buffered whole: the caller's buffer only ever holds what the peer has sent, never what it promised. The decoder itself keeps a few bytes of state.
pub fn new() -> Self
A decoder positioned before the first chunk-size line.
pub fn is_done(&self) -> bool
True once the terminating chunk has been consumed.
pub fn decode(
&mut self,
input: &[u8],
out: &mut Vec<u8>,
) -> Result<ChunkedProgress, ChunkedError>
Decodes as much of input as is complete, appending chunk data to
out.
Stops at the first incomplete element (a size line without its CRLF, data the peer has not sent yet) and reports how many bytes were consumed; the caller keeps the rest and calls again with more input.
Returns ChunkedError on malformed framing; the decoder is then
unusable and the connection should be dropped.
Implements: Clone, Debug, Default, Eq, PartialEq
pub struct BodyReader {
/* private fields */
}
Sans-IO reader for one request body under its declared framing.
crate::granted feeds it whatever bytes arrive on the socket and sends
or collects what it yields; the granted_http fuzz target and the corpus
replay feed it the same bytes in arbitrary splits. Framing dispatch, the
route's byte cap and end-of-stream handling therefore run through one
code path for all three (docs/adr/untrusted-input-fuzzing.md).
A Content-Length body yields its first len bytes and ignores anything
after them (the connection closes after one request). A chunked body is
decoded incrementally; a read-until-EOF body yields every byte and is
done only at Self::finish.
pub fn new(headers: &[(String, String)]) -> Result<Self, BodyError>
Starts a reader for the body headers describe.
Returns BodyError::Framing when the framing headers are malformed
or ambiguous.
pub fn for_framing(framing: BodyFraming) -> Self
Starts a reader for an already decided framing.
pub fn with_cap(self, cap: usize) -> Self
Caps the decoded body at cap bytes; a body that declares or
delivers more fails with BodyError::TooLarge.
pub fn framing(&self) -> BodyFraming
The framing this reader follows.
pub fn is_done(&self) -> bool
True once the body is complete (a read-until-EOF body only after
Self::finish).
pub fn push(&mut self, input: &[u8], out: &mut Vec<u8>) -> Result<bool, BodyError>
Feeds the next bytes from the stream, appending decoded body bytes to
out.
true once the body is complete; later input is ignored.
BodyError::TooLarge when the declared or received body passes the
cap, or BodyError::Chunked on malformed chunked framing. Either
error is final.
pub fn finish(&mut self) -> Result<(), BodyError>
Reports end of stream.
BodyError::Truncated when a Content-Length or chunked body is
incomplete. A read-until-EOF body completes here.
Implements: Clone, Debug, Eq, PartialEq
pub enum HeadError {
TooLarge,
NotUtf8,
BadRequestLine,
BadHeaderLine,
}
Why a request head was rejected.
Variants
TooLarge: The head grew pastMAX_HEAD_BYTESwithout a blank line.NotUtf8: The head is not UTF-8.BadRequestLine: The request line is missing its method or target.BadHeaderLine: A header line has no:.
Implements: Clone, Copy, Debug, Display, Eq, Error, PartialEq
pub enum HeadParse {
Incomplete,
Complete { head: RequestHead, consumed: usize },
}
Outcome of parse_request_head on the bytes buffered so far.
Variants
Incomplete: No blank line yet; read more.Complete: A complete head;consumedbytes belong to it and the rest of the buffer is the start of the body.head: The parsed head.consumed: Bytes ofbufthe head occupied, including the blank line.
Implements: Clone, Debug, Eq, PartialEq
pub enum BodyFraming {
UntilEof,
Length(usize),
Chunked,
}
How the request frames its body.
Variants
UntilEof: NoContent-Lengthand no chunked encoding: the body runs to EOF.Length:Content-Lengthin bytes.Chunked:Transfer-Encoding: chunked.
Implements: Clone, Copy, Debug, Eq, PartialEq
pub enum FramingError {
BadContentLength,
Ambiguous,
UnsupportedTransferEncoding,
}
Why the body framing headers were rejected.
Variants
BadContentLength:Content-Lengthis not a decimalusize, or two differ.Ambiguous: BothContent-Lengthand chunked encoding are present.UnsupportedTransferEncoding:Transfer-Encodingnames a coding other than a singlechunked(gzip, chunked,identity,chunked, chunked); the channel does not decode those, so the body length would be unknown.
Implements: Clone, Copy, Debug, Display, Eq, Error, From<FramingError>, PartialEq
pub enum ChunkedError {
BadChunkSize,
ChunkLineTooLong,
MissingChunkTerminator,
BadTrailer,
}
Why a chunked body was rejected.
Variants
BadChunkSize: A chunk-size field is empty, not hex, or longer thanMAX_CHUNK_SIZE_DIGITS.ChunkLineTooLong: A chunk-size line ran pastMAX_CHUNK_LINE_BYTESwithout CRLF.MissingChunkTerminator: Chunk data was not followed by CRLF.BadTrailer: More thanMAX_TRAILER_LINEStrailer lines, or a trailer line longer thanMAX_CHUNK_LINE_BYTES.
Implements: Clone, Copy, Debug, Display, Eq, Error, From<ChunkedError>, PartialEq
pub enum BodyError {
Framing(FramingError),
Chunked(ChunkedError),
TooLarge { cap: usize, used: usize },
Truncated,
}
Why a request body was rejected or cut short.
Variants
Framing: The framing headers were malformed or ambiguous.Chunked: The chunked framing was malformed.TooLarge: The body (declared or received) exceeds the route's byte cap.cap: The cap the body ran past, in bytes.used: The declared or received size that ran past it, in bytes.
Truncated: The stream ended before the declaredContent-Lengthor the terminating chunk.
Implements: Clone, Copy, Debug, Display, Eq, Error, From<ChunkedError>, From<FramingError>, PartialEq
pub fn parse_request_head(buf: &[u8]) -> Result<HeadParse, HeadError>
Parses an HTTP/1.1 request head from the start of buf.
Returns HeadError when the head is oversized, not UTF-8, or has a
malformed request or header line. An incomplete head is not an error
until it exceeds MAX_HEAD_BYTES.
pub fn header<'a>(headers: &'a [(String, String)], name: &str) -> Option<&'a str>
The first header named name (ASCII case-insensitive).
pub fn transfer_encodings(headers: &[(String, String)]) -> Vec<String>
Every transfer coding named by the Transfer-Encoding headers, in wire
order, lowercased and trimmed, with empty list elements dropped.
pub fn transfer_encoding_is_chunked(headers: &[(String, String)]) -> bool
True when a Transfer-Encoding header lists the chunked coding as a
token (so chunkedx or notchunked do not count).
pub fn body_framing(headers: &[(String, String)]) -> Result<BodyFraming, FramingError>
Decides the body framing from the headers.
A Content-Length that is not a decimal number, or that disagrees with a
second Content-Length, is rejected rather than ignored, so a malformed
header can never turn a bounded body into a read-until-EOF one. A
Transfer-Encoding is accepted only when it names exactly one coding and
that coding is chunked; any other coding list is rejected because the
channel cannot know where such a body ends.
Returns FramingError on a malformed or ambiguous framing.
pub fn declared_content_length_over_cap(headers: &[(String, String)], cap: u32) -> bool
True when a well-formed Content-Length declares more than cap bytes.
A malformed one is left for body_framing to reject.
pub fn declared_content_length_past_cap(
headers: &[(String, String)],
cap: u32,
) -> Option<usize>
The declared Content-Length when it is past cap, in bytes.
pub fn query_param(query: &str, name: &str) -> Option<String>
The percent-decoded value of the first name= pair in query.
pub fn percent_decode(s: &str) -> String
Decodes %HH escapes and + (as space); malformed escapes are kept as
written, and the result is UTF-8 with replacement characters.
Works on bytes throughout: a % escape may end inside a multi-byte
character, so slicing the str would panic.
pub const MAX_HEAD_BYTES: usize = _;
Largest request head (request line plus headers plus the blank line) accepted before the connection is dropped.
pub const MAX_CHUNK_SIZE_DIGITS: usize = 16;
Most hex digits a chunk-size field may carry. Sixteen digits already
overflow u64; real clients send far fewer.
pub const MAX_CHUNK_LINE_BYTES: usize = 1024;
Longest chunk-size line (digits, extensions and CRLF) before the body is rejected as malformed.
pub const MAX_TRAILER_LINES: usize = 16;
Most trailer lines accepted after the terminating chunk.
Generated from crates/bookclerk-workerd at main · View as Markdown