silk/http_head

Profiles: aarch64-apple-darwin, aarch64-unknown-linux-gnu, aarch64-unknown-linux-gnu-no-libc, wasm32-unknown-unknown, x86_64-unknown-linux-gnu, x86_64-unknown-linux-gnu-no-libc.

Bounded incremental HTTP/1.0 and HTTP/1.1 head parsing and atomic serialization.

When to use

Use RequestParser or ResponseParser at a buffered transport boundary. Each parser owns all byte and field-index storage up front, reports exactly how much of the current input it consumed, and stops after the terminating empty line so body or next-message bytes stay with the caller.

Details

The accepted profile requires CRLF, exact single-SP start-line separators, and field names immediately followed by :. It rejects leading blank lines, bare LF, obs-fold, HTTP/0.9, ICY, and historical whitespace recovery. Completed heads and their field iterators borrow the parser; use RequestHead.copy or ResponseHead.copy for independent ownership.

Construction accounts for the configured head-byte backing plus 32 bytes of portable offset metadata per field against maxOwnedBytes. Parser scalar and allocator bookkeeping are not part of that caller-visible capacity. Feed, head access, reset, and serialization allocate nothing.

Import as RequestParser with import silk.http_head { RequestParser }.

Public declarations: 22.

Limits

pub struct Limits

Explicit finite parser, line, field, value, and owned-storage limits.

Field maxHeadBytes

pub maxHeadBytes: usize

Maximum complete head bytes, including every CRLF and the terminating empty line.

Field maxStartLineBytes

pub maxStartLineBytes: usize

Maximum request/status line bytes, including its CRLF.

Field maxFieldLineBytes

pub maxFieldLineBytes: usize

Maximum field-line bytes, including its CRLF.

Field maxOwnedBytes

pub maxOwnedBytes: usize

Maximum parser byte backing plus field-offset metadata bytes.

Field values

pub values: ValueLimits

Shared method, target, name, value, field-count, and aggregate field limits.

Implementation Copy for Limits

impl Copy for Limits

ProgressState

pub enum ProgressState

The outcome of one successful incremental feed.

NeedInput

NeedInput = 0

More bytes are required to complete the head.

Complete

Complete = 1

The terminating empty line was consumed and the parser now publishes a head.

Progress

pub struct Progress

Exact progress through the current caller input.

Field consumed

pub consumed: usize

Bytes consumed from this call only.

Field state

pub state: ProgressState

Whether one complete head is now available.

Implementation Copy for Progress

impl Copy for Progress

ParserState

pub enum ParserState

The externally visible parser lifecycle.

Active

Active = 0

The parser can accept more input.

Complete

Complete = 1

One complete head is available and the parser cannot be fed again before reset.

Failed

Failed = 2

A syntax, limit, or truncation failure poisoned the parser until reset.

ParseComponent

pub enum ParseComponent

The syntactic or semantic component associated with a parser failure.

Parser

Parser = 0

Parser construction, lifecycle, or complete-head state.

StartLine

StartLine = 1

Request or response start line as a whole.

Version

Version = 2

HTTP version token.

Method

Method = 3

Request method token.

Target

Target = 4

Request target.

Status

Status = 5

Response status digits or range.

ReasonPhrase

ReasonPhrase = 6

Response reason phrase.

HeaderName

HeaderName = 7

Field name.

HeaderValue

HeaderValue = 8

Field value after surrounding OWS removal.

Host

Host = 9

HTTP Host field requirement or authority.

LineEnding

LineEnding = 10

Line delimiter syntax.

ParseLimitKind

pub enum ParseLimitKind

The finite parser budget that was exceeded.

HeadBytes

HeadBytes = 0

Complete stored head bytes.

StartLineBytes

StartLineBytes = 1

Request or response start-line bytes, including CRLF.

FieldLineBytes

FieldLineBytes = 2

One field-line bytes, including CRLF.

Fields

Fields = 3

Number of fields, including duplicates and unknown names.

MethodBytes

MethodBytes = 4

Method bytes from the shared HTTP value contract.

TargetBytes

TargetBytes = 5

Request-target bytes from the shared HTTP value contract.

NameBytes

NameBytes = 6

Field-name bytes from the shared HTTP value contract.

ValueBytes

ValueBytes = 7

Field-value or reason bytes from the shared HTTP value contract.

FieldBytes

FieldBytes = 8

Aggregate field-name plus field-value bytes.

OwnedBytes

OwnedBytes = 9

Parser-owned byte backing and field-offset storage.

ParseReason

pub union ParseReason

Closed parser and serializer failure reasons.

InvalidStartLine

ParseReason.InvalidStartLine: ParseReason

A start line does not match the selected strict grammar.

UnsupportedVersion

ParseReason.UnsupportedVersion: ParseReason

A version is not exactly HTTP/1.0 or HTTP/1.1.

InvalidMethod

ParseReason.InvalidMethod: ParseReason

A request method is not a nonempty HTTP token.

InvalidTarget

ParseReason.InvalidTarget: ParseReason

A request target is invalid for its method or target form.

InvalidStatus

ParseReason.InvalidStatus: ParseReason

A response status is not exactly three digits in the range 100 through 599.

InvalidReasonPhrase

ParseReason.InvalidReasonPhrase: ParseReason

A reason phrase contains a forbidden control octet or DEL.

InvalidFieldName

ParseReason.InvalidFieldName: ParseReason

A field name is empty or contains a byte outside tchar.

InvalidFieldValue

ParseReason.InvalidFieldValue: ParseReason

A trimmed field value contains a forbidden octet.

BareLf

ParseReason.BareLf: ParseReason

LF appeared without a preceding CR.

InvalidLineEnding

ParseReason.InvalidLineEnding: ParseReason

A CR was not followed by LF.

WhitespaceBeforeColon

ParseReason.WhitespaceBeforeColon: ParseReason

SP or HTAB appeared between a field name and its colon.

ObsFold

ParseReason.ObsFold: ParseReason

A field line began with SP or HTAB, which this profile never unfolds.

MissingHost

ParseReason.MissingHost: ParseReason

HTTP/1.1 had no Host field.

DuplicateHost

ParseReason.DuplicateHost: ParseReason

More than one Host field was present.

InvalidHost

ParseReason.InvalidHost: ParseReason

A supplied Host field was not a valid authority.

LimitExceeded

ParseReason.LimitExceeded { limit: ParseLimitKind, allowed: usize, attempted: usize }: ParseReason

One explicit finite limit was exceeded.

Field limit

pub limit: ParseLimitKind

The rejected budget.

Field allowed

pub allowed: usize

Configured maximum.

Field attempted

pub attempted: usize

Attempted count.

SizeOverflow

ParseReason.SizeOverflow: ParseReason

Checked capacity or serialized-size arithmetic overflowed usize.

Truncated

ParseReason.Truncated: ParseReason

Final input ended before the terminating empty line.

InvalidState

ParseReason.InvalidState: ParseReason

The operation is not valid for the parser's current lifecycle.

Implementation Copy for ParseReason

impl Copy for ParseReason

ParseError

pub struct ParseError

A precise parser failure with per-call progress and absolute head location.

Field reason

pub reason: ParseReason

Recovery-oriented failure category.

Field component

pub component: ParseComponent

Component that failed.

Field consumed

pub consumed: usize

Valid prefix consumed from the call that produced this error.

Field offset

pub offset: usize

Zero-based absolute byte offset in the head.

Field fieldIndex

pub fieldIndex: silk/option.Option<usize>

Field ordinal when the failure belongs to one field.

validateLimits

pub fn validateLimits<'life0>(limits: &'life0 silk/http_head.Limits) -> silk/result.Result<(), silk/http_head.ParseError>

Validates parser storage arithmetic and the owned-storage limit without allocation or input.

Details

The required storage contains maxHeadBytes plus fixed field metadata for maxFields. Arithmetic overflow returns SizeOverflow. Excess storage returns the exact OwnedBytes limit.

RequestParser

pub struct RequestParser

An affine owner of one bounded incremental request-head parse.

Associated function RequestParser.make

pub effect<'static> fn make(limits: Limits) -> silk/result.Result<silk/http_head.RequestParser, silk/http_head.ParseError> ! OutOfMemoryError ? &mut Allocator

Validates capacity arithmetic and acquires all parser storage before publishing the parser.

Method RequestParser.feed

pub fn feed<'life0, 'life1>(self: &'life0 mut RequestParser, input: &'life1 [u8], final: bool) -> silk/result.Result<silk/http_head.Progress, silk/http_head.ParseError>

Consumes an exact prefix, never crossing the terminating empty line.

Method RequestParser.state

pub fn state<'life0>(self: &'life0 RequestParser) -> ParserState

Returns the current parser lifecycle.

Method RequestParser.failure

pub fn failure<'life0>(self: &'life0 RequestParser) -> silk/option.Option<silk/http_head.ParseError>

Returns the original poisoning failure, if one exists.

Method RequestParser.head

pub fn head<'owner>(self: &'owner RequestParser) -> silk/result.Result<silk/http_head.RequestHead<'owner>, silk/http_head.ParseError>

Borrows the completed request head and its ordered fields.

Method RequestParser.reset

pub fn reset<'life0>(self: &'life0 mut RequestParser) -> silk/result.Result<(), silk/http_head.ParseError>

Restores fresh active state while retaining the original allocations. A live head borrow statically prevents this exclusive operation.

ResponseParser

pub struct ResponseParser

An affine owner of one bounded incremental response-head parse.

Associated function ResponseParser.make

pub effect<'static> fn make(limits: Limits) -> silk/result.Result<silk/http_head.ResponseParser, silk/http_head.ParseError> ! OutOfMemoryError ? &mut Allocator

Validates capacity arithmetic and acquires all parser storage before publishing the parser.

Method ResponseParser.feed

pub fn feed<'life0, 'life1>(self: &'life0 mut ResponseParser, input: &'life1 [u8], final: bool) -> silk/result.Result<silk/http_head.Progress, silk/http_head.ParseError>

Consumes an exact prefix, never crossing the terminating empty line.

Method ResponseParser.state

pub fn state<'life0>(self: &'life0 ResponseParser) -> ParserState

Returns the current parser lifecycle.

Method ResponseParser.failure

pub fn failure<'life0>(self: &'life0 ResponseParser) -> silk/option.Option<silk/http_head.ParseError>

Returns the original poisoning failure, if one exists.

Method ResponseParser.head

pub fn head<'owner>(self: &'owner ResponseParser) -> silk/result.Result<silk/http_head.ResponseHead<'owner>, silk/http_head.ParseError>

Borrows the completed response head and its ordered fields.

Method ResponseParser.reset

pub fn reset<'life0>(self: &'life0 mut ResponseParser) -> silk/result.Result<(), silk/http_head.ParseError>

Restores fresh active state while retaining the original allocations. A live head borrow statically prevents this exclusive operation.

RequestHead

pub struct RequestHead<'owner>

A completed request head whose values and fields borrow its parser.

Method RequestHead.version

pub fn version<'owner, 'life1>(self: &'life1 RequestHead<'owner>) -> Version

Returns the parsed protocol version.

Method RequestHead.method

pub fn method<'owner, 'life1>(self: &'life1 RequestHead<'owner>) -> silk/http.Method<'owner>

Returns the validated case-sensitive method token.

Method RequestHead.target

pub fn target<'owner, 'life1>(self: &'life1 RequestHead<'owner>) -> silk/http_target.RequestTarget<'owner>

Returns the validated request target.

Method RequestHead.fieldCount

pub fn fieldCount<'owner, 'life1>(self: &'life1 RequestHead<'owner>) -> usize

Returns the number of fields, including duplicates.

Method RequestHead.fields

pub fn fields<'owner, 'life1>(self: &'life1 RequestHead<'owner>) -> silk/http_head.HeaderIterator<'owner>

Iterates fields in original order without combining duplicate names.

Method RequestHead.copy

pub effect<'env> fn copy<'owner: 'env, 'life1: 'env, 'env>(self: &'life1 RequestHead<'owner>, limits: ValueLimits) -> silk/result.Result<silk/http.OwnedRequestHead, silk/http.ValueError> ! OutOfMemoryError ? &mut Allocator

Copies this head into the shared independently owned HTTP head representation.

Implementation Copy for silk/http_head.RequestHead<'owner>

impl Copy for silk/http_head.RequestHead<'owner>

ResponseHead

pub struct ResponseHead<'owner>

A completed response head whose values and fields borrow its parser.

Method ResponseHead.version

pub fn version<'owner, 'life1>(self: &'life1 ResponseHead<'owner>) -> Version

Returns the parsed protocol version.

Method ResponseHead.status

pub fn status<'owner, 'life1>(self: &'life1 ResponseHead<'owner>) -> Status

Returns the parsed response status.

Method ResponseHead.reason

pub fn reason<'owner, 'life1>(self: &'life1 ResponseHead<'owner>) -> &'owner [u8]

Borrows the exact reason octets, which may be empty and need not be UTF-8.

Method ResponseHead.fieldCount

pub fn fieldCount<'owner, 'life1>(self: &'life1 ResponseHead<'owner>) -> usize

Returns the number of fields, including duplicates.

Method ResponseHead.fields

pub fn fields<'owner, 'life1>(self: &'life1 ResponseHead<'owner>) -> silk/http_head.HeaderIterator<'owner>

Iterates fields in original order without combining duplicate names.

Method ResponseHead.copy

pub effect<'env> fn copy<'owner: 'env, 'life1: 'env, 'env>(self: &'life1 ResponseHead<'owner>, limits: ValueLimits) -> silk/result.Result<silk/http.OwnedResponseHead, silk/http.ValueError> ! OutOfMemoryError ? &mut Allocator

Copies this head into the shared independently owned HTTP head representation.

Method ResponseHead.copyMatchingHeaders

pub effect<'env> fn copyMatchingHeaders<'owner: 'env, 'name: 'env, 'life2: 'env, 'env>(self: &'life2 ResponseHead<'owner>, name: string<'name>, limits: ValueLimits) -> silk/result.Result<silk/http.OwnedResponseHead, silk/http.ValueError> ! OutOfMemoryError ? &mut Allocator

Copies the status, reason, and only matching fields into independent storage.

Details

Matching is ASCII case-insensitive. Duplicate matches remain distinct and preserve wire order. The supplied limits apply to the selected fields and complete owned result, not unrelated fields retained by the parser.

Implementation Copy for silk/http_head.ResponseHead<'owner>

impl Copy for silk/http_head.ResponseHead<'owner>

HeaderIterator

pub struct HeaderIterator<'owner>

An insertion-order iterator over validated fields borrowed from a completed parser.

Method HeaderIterator.next

pub fn next<'owner, 'life1>(self: &'life1 mut HeaderIterator<'owner>) -> silk/option.Option<silk/http.Header<'owner>>

Returns the next validated field, or None after the final field.

Method HeaderIterator.fieldIndex

pub fn fieldIndex<'owner, 'life1>(self: &'life1 HeaderIterator<'owner>) -> usize

Returns the source field ordinal yielded by the most recent successful call.

ParsedRequest

pub struct ParsedRequest

Whole-slice request parsing result, retaining both the parser and exact suffix boundary.

Field parser

pub parser: RequestParser

Completed parser. Borrow it with RequestParser.head.

Field progress

pub progress: Progress

Exact progress through the supplied whole slice.

ParsedResponse

pub struct ParsedResponse

Whole-slice response parsing result, retaining both the parser and exact suffix boundary.

Field parser

pub parser: ResponseParser

Completed parser. Borrow it with ResponseParser.head.

Field progress

pub progress: Progress

Exact progress through the supplied whole slice.

parseRequest

pub effect<'life0> fn parseRequest<'life0>(input: &'life0 [u8], limits: Limits) -> silk/result.Result<silk/http_head.ParsedRequest, silk/http_head.ParseError> ! OutOfMemoryError ? &mut Allocator

Parses one request head from a whole slice through the same incremental core. The returned progress retains the exact suffix boundary when additional bytes follow the head.

parseResponse

pub effect<'life0> fn parseResponse<'life0>(input: &'life0 [u8], limits: Limits) -> silk/result.Result<silk/http_head.ParsedResponse, silk/http_head.ParseError> ! OutOfMemoryError ? &mut Allocator

Parses one response head from a whole slice through the same incremental core. The returned progress retains the exact suffix boundary when additional bytes follow the head.

requestSerializedSize

pub fn requestSerializedSize<'value, 'life1>(head: &'life1 silk/http.RequestHead<'value>, limits: ValueLimits) -> silk/result.Result<usize, silk/http.ValueError>

Computes the exact canonical request-head size without mutating output.

responseSerializedSize

pub fn responseSerializedSize<'value, 'life1>(head: &'life1 silk/http.ResponseHead<'value>, limits: ValueLimits) -> silk/result.Result<usize, silk/http.ValueError>

Computes the exact canonical response-head size without mutating output.

writeRequestInto

pub fn writeRequestInto<'value, 'life1, 'life2>(head: &'life1 silk/http.RequestHead<'value>, output: &'life2 mut [u8], limits: ValueLimits) -> silk/result.Result<usize, silk/http.ValueError>

Writes one validated request head atomically with canonical SP and CRLF separators.

writeResponseInto

pub fn writeResponseInto<'value, 'life1, 'life2>(head: &'life1 silk/http.ResponseHead<'value>, output: &'life2 mut [u8], limits: ValueLimits) -> silk/result.Result<usize, silk/http.ValueError>

Writes one validated response head atomically with canonical SP and CRLF separators.