silk/http_content

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 scoped HTTP response content decoding over strict body framing.

When to use

Build a ResponseContext from one validated response head, request method, and trailer policy, consume it into a CodingPlan, then use withReader to stream either the raw representation or a validated reverse content-decoding stack.

Details

Planning parses at most four content codings and performs every configuration and owned-memory check before codec acquisition or body I/O. Readers exclusively borrow an existing BufferedDuplex for one callback. Bytes returned before ContentCompletion are provisional because a later wrapper checksum, trailer, or framed boundary can still fail.

Gotchas

This low-level actor treats the body supplied to each withReader invocation as the encoded representation described by the plan. It does not prove that those bytes came from the retained head and cannot prevent a copied head from being planned over already-decoded bytes. The affine response/body envelope in silk.http_client owns that stronger provenance and decode-once contract. Cleanup is guaranteed for structured Effect exits, including interruption, but not for fatal traps that bypass Effect finalizers and Drop.

Import as ContentReader with import silk.http_content { ContentReader }.

Public declarations: 25.

Mode

pub enum Mode

Whether the representation is preserved or decoded.

Raw

Raw = 0

Preserves encoded representation bytes without interpreting Content-Encoding.

Decode

Decode = 1

Validates Content-Encoding and applies the supported reverse decoding stack.

Coding

pub enum Coding

One recognized response content coding.

Identity

Identity = 0

Leaves representation bytes unchanged and counts toward the coding depth.

Gzip

Gzip = 1

Decodes gzip members, including permitted concatenated members.

XGzip

XGzip = 2

Accepts the legacy response spelling of gzip with the same decoding rules.

Deflate

Deflate = 3

Decodes one zlib-wrapped stream; raw DEFLATE and trailing bytes fail.

Zstd

Zstd = 4

Decodes Zstandard frames under the configured window and workspace limits.

CodingPosition

pub struct CodingPosition

The exact source coordinates of one coding token.

Field wireIndex

pub wireIndex: usize

The zero-based coding position across all Content-Encoding fields.

Field fieldIndex

pub fieldIndex: usize

The zero-based header field position in the original response.

Field elementIndex

pub elementIndex: usize

The zero-based comma element within its Content-Encoding field.

Field offset

pub offset: usize

The byte offset of the coding token or invalid byte within the field value.

Implementation Copy for CodingPosition

impl Copy for CodingPosition

Limits

pub struct Limits

The finite content, composition, and codec allowances copied into a plan.

Field maxEncoded

pub maxEncoded: u64

The maximum representation bytes accepted after HTTP deframing.

Field maxIntermediate

pub maxIntermediate: u64

The maximum combined bytes produced by all nonfinal codec stages.

Field maxDecoded

pub maxDecoded: u64

The maximum final representation bytes returned to the caller.

Field maxOwned

pub maxOwned: usize

The maximum admitted composition and codec storage reservation, excluding body-decoder storage.

Field maxDepth

pub maxDepth: usize

The maximum coding entries, including identity; must be between one and four.

Field intermediateCapacity

pub intermediateCapacity: usize

The capacity of each active stage edge; must be between one and 65,536 bytes.

Field inflate

pub inflate: InflateLimits

The limits applied independently to each gzip or zlib decoder.

Field zstd

pub zstd: ZstdLimits

The limits applied independently to each Zstandard decoder.

ContentLimitKind

pub enum ContentLimitKind

The configuration or byte class rejected by the content layer.

CodingDepth

CodingDepth = 0

The permitted number of content-coding entries.

IntermediateCapacity

IntermediateCapacity = 1

The finite capacity of one stage edge.

OwnedBytes

OwnedBytes = 2

The admitted composition and codec storage reservation.

EncodedBytes

EncodedBytes = 3

The deframed representation input byte allowance.

IntermediateBytes

IntermediateBytes = 4

The combined output allowance for nonfinal decoding stages.

DecodedBytes

DecodedBytes = 5

The final representation output byte allowance.

ContentReason

pub union ContentReason<'head>

A stage-aware content, framing, transport, or codec failure.

InvalidLimit

ContentReason<'head>.InvalidLimit { limit: ContentLimitKind, allowed: u64, attempted: u64 }: ContentReason<'head>

A configuration or byte count exceeds its permitted range.

Field limit

pub limit: ContentLimitKind

The rejected configuration or byte class.

Field allowed

pub allowed: u64

The applicable maximum.

Field attempted

pub attempted: u64

The rejected value or count.

CodingSyntax

ContentReason<'head>.CodingSyntax { position: CodingPosition }: ContentReason<'head>

A Content-Encoding element is empty or contains invalid syntax.

Field position

pub position: CodingPosition

The exact location of the invalid token or byte.

UnsupportedCoding

ContentReason<'head>.UnsupportedCoding { position: CodingPosition, token: &'head [u8] }: ContentReason<'head>

A valid coding token names an unsupported decoder.

Field position

pub position: CodingPosition

The token position in the original response.

Field token

pub token: &'head [u8]

The untouched unsupported token borrowed from the response.

PartialResponse

ContentReason<'head>.PartialResponse { position: CodingPosition }: ContentReason<'head>

A 206 response selects a nonidentity coding in Decode mode.

Field position

pub position: CodingPosition

The first nonidentity coding in wire order.

Tunnel

ContentReason<'head>.Tunnel: ContentReason<'head>

The selected body is a protocol tunnel rather than an HTTP representation.

Body

ContentReason<'head>.Body { error: BodyError }: ContentReason<'head>

HTTP body framing failed before content completion.

Field error

pub error: BodyError

The original body error, including committed wire progress.

Buffer

ContentReason<'head>.Buffer { error: BufferError }: ContentReason<'head>

The buffered transport failed.

Field error

pub error: BufferError

The original buffer error and its transport cause.

Inflate

ContentReason<'head>.Inflate { stage: usize, wireIndex: usize, error: DecodeError }: ContentReason<'head>

A gzip or zlib decoder rejected configuration or input.

Field stage

pub stage: usize

The zero-based reverse application stage.

Field wireIndex

pub wireIndex: usize

The original coding position in wire order.

Field error

pub error: DecodeError

The exact inflate failure and decoder-call progress.

Zstandard

ContentReason<'head>.Zstandard { stage: usize, wireIndex: usize, error: ZstdError }: ContentReason<'head>

A Zstandard decoder rejected configuration or input.

Field stage

pub stage: usize

The zero-based reverse application stage.

Field wireIndex

pub wireIndex: usize

The original coding position in wire order.

Field error

pub error: ZstdError

The exact Zstandard failure and decoder-call progress.

TrailingEncodedData

ContentReason<'head>.TrailingEncodedData { stage: usize, wireIndex: usize }: ContentReason<'head>

A finished coding stream has additional encoded bytes.

Field stage

pub stage: usize

The zero-based reverse application stage.

Field wireIndex

pub wireIndex: usize

The original coding position in wire order.

ArithmeticOverflow

ContentReason<'head>.ArithmeticOverflow: ContentReason<'head>

A checked byte or reservation calculation cannot represent its result.

InvalidState

ContentReason<'head>.InvalidState: ContentReason<'head>

The reader previously failed or was abandoned.

ContentError

pub struct ContentError<'head>

Exact per-call and cumulative coordinates for a content failure.

Field reason

pub reason: silk/http_content.ContentReason<'head>

The exact failure category and its lower-level cause when available.

Field written

pub written: usize

The representation bytes written to the caller destination during this read.

Field totalEncoded

pub totalEncoded: u64

The cumulative representation bytes accepted after HTTP deframing.

Field totalIntermediate

pub totalIntermediate: u64

The cumulative output bytes accepted from all nonfinal codec stages.

Field totalDecoded

pub totalDecoded: u64

The cumulative representation bytes written to caller destinations.

ContentProgressState

pub enum ContentProgressState

Whether one successful read returned data or established terminal completion.

Data

Data = 0

Reports provisional output or internal progress before complete validation.

End

End = 1

Reports successful completion of the framed body and all content stages.

ContentProgress

pub struct ContentProgress

Exact per-call and cumulative committed content progress.

Field written

pub written: usize

The representation bytes written to the caller destination during this read.

Field totalEncoded

pub totalEncoded: u64

The cumulative representation bytes accepted after HTTP deframing.

Field totalIntermediate

pub totalIntermediate: u64

The cumulative output bytes accepted from all nonfinal codec stages.

Field totalDecoded

pub totalDecoded: u64

The cumulative representation bytes written to caller destinations.

Field state

pub state: ContentProgressState

Whether content remains provisional or has completed validation.

ReuseDisposition

pub enum ReuseDisposition

Connection reuse policy before and after positive completion evidence.

EligibleAfterCompletion

EligibleAfterCompletion = 0

Allows reuse only after successful content completion supplies positive evidence.

Reusable

Reusable = 1

Confirms delimited framing, no framing anomaly, and successful content completion.

NonReusable

NonReusable = 2

Forbids reuse because framing closes the connection or carries an anomaly.

AppliedPlan

pub struct AppliedPlan

Public applied-plan metadata without exposing the affine plan itself.

Field mode

pub mode: Mode

Whether the plan preserves or decodes the representation.

Field codingCount

pub codingCount: usize

The number of parsed coding entries, including identity.

Field decoderCount

pub decoderCount: usize

The number of active nonidentity codec stages.

Field reuse

pub reuse: ReuseDisposition

The reuse disposition established by the plan or completion.

Implementation Copy for AppliedPlan

impl Copy for AppliedPlan

RepresentationView

pub struct RepresentationView<'owner, 'head>

Borrowed effective representation metadata that never rewrites wire headers.

Method RepresentationView.originalHead

pub fn originalHead<'owner, 'head, 'life2>(self: &'life2 RepresentationView<'owner, 'head>) -> silk/http_head.ResponseHead<'head>

Returns the untouched response head with its original coding and length headers.

Method RepresentationView.appliedPlan

pub fn appliedPlan<'owner, 'head, 'life2>(self: &'life2 RepresentationView<'owner, 'head>) -> AppliedPlan

Returns the effective coding counts, mode, and reuse disposition.

Method RepresentationView.anomaly

pub fn anomaly<'owner, 'head, 'life2>(self: &'life2 RepresentationView<'owner, 'head>) -> Anomaly

Returns the exact framing anomaly selected from the original response.

Method RepresentationView.decodingApplied

pub fn decodingApplied<'owner, 'head, 'life2>(self: &'life2 RepresentationView<'owner, 'head>) -> bool

Returns whether at least one nonidentity content decoder was selected.

Method RepresentationView.decodedLength

pub fn decodedLength<'owner, 'head, 'life2>(self: &'life2 RepresentationView<'owner, 'head>) -> silk/option.Option<u64>

Returns the final decoded length only after completion, or zero for semantic no-body responses.

ContentCompletion

pub struct ContentCompletion<'owner>

Opaque positive evidence that framing and every selected codec completed.

Method ContentCompletion.bodyKind

pub fn bodyKind<'owner, 'life1>(self: &'life1 ContentCompletion<'owner>) -> BodyCompletionKind

Returns whether the completed body was delimited or ended at transport closure.

Method ContentCompletion.decodedBytes

pub fn decodedBytes<'owner, 'life1>(self: &'life1 ContentCompletion<'owner>) -> u64

Returns the final validated representation byte count.

Method ContentCompletion.anomaly

pub fn anomaly<'owner, 'life1>(self: &'life1 ContentCompletion<'owner>) -> Anomaly

Returns the exact framing anomaly selected from the original response.

Method ContentCompletion.reuse

pub fn reuse<'owner, 'life1>(self: &'life1 ContentCompletion<'owner>) -> ReuseDisposition

Returns the reuse disposition supported by this completed representation.

ResponseContext

pub struct ResponseContext<'head, 'method, 'names>

Atomic response-selection provenance. Its fields are intentionally private.

Associated function ResponseContext.make

pub fn make<'head, 'method, 'names>(head: silk/http_head.ResponseHead<'head>, requestMethod: silk/http.Method<'method>, trailerPolicy: silk/http_body.TrailerPolicy<'names>) -> silk/result.Result<silk/http_content.ResponseContext<'head, 'method, 'names>, silk/http_body.BodyError>

Selects response framing and constructs no context when selection fails.

CodingPlan

pub struct CodingPlan<'head, 'method, 'names>

A validated single-use response plan. Construction consumes its complete context.

Associated function CodingPlan.make

pub fn make<'head, 'method, 'names>(context: silk/http_content.ResponseContext<'head, 'method, 'names>, mode: Mode, bodyLimits: BodyLimits, limits: Limits) -> silk/result.Result<silk/http_content.CodingPlan<'head, 'method, 'names>, silk/http_content.ContentError<'head>>

Validates all policy and storage requirements without allocation or body I/O.

Method CodingPlan.originalHead

pub fn originalHead<'head, 'method, 'names, 'life3>(self: &'life3 CodingPlan<'head, 'method, 'names>) -> silk/http_head.ResponseHead<'head>

Returns the untouched response head with its original coding and length headers.

Method CodingPlan.selectionAnomaly

pub fn selectionAnomaly<'head, 'method, 'names, 'life3>(self: &'life3 CodingPlan<'head, 'method, 'names>) -> Anomaly

Returns the selected framing anomaly exactly.

Method CodingPlan.selectedFraming

pub fn selectedFraming<'head, 'method, 'names, 'life3>(self: &'life3 CodingPlan<'head, 'method, 'names>) -> Framing

Returns the framing retained by atomic selection.

Method CodingPlan.applied

pub fn applied<'head, 'method, 'names, 'life3>(self: &'life3 CodingPlan<'head, 'method, 'names>) -> AppliedPlan

Returns the effective plan metadata.

Method CodingPlan.ownedBytes

pub fn ownedBytes<'head, 'method, 'names, 'life3>(self: &'life3 CodingPlan<'head, 'method, 'names>) -> usize

Returns the deterministic owned reservation admitted by the plan.

EnabledCodings

pub struct EnabledCodings

Enabled automatic request codings. x-gzip is deliberately absent.

Field gzip

pub gzip: bool

Enables gzip in automatic Accept-Encoding output.

Field deflate

pub deflate: bool

Enables zlib-wrapped deflate in automatic Accept-Encoding output.

Field zstd

pub zstd: bool

Enables zstd in automatic Accept-Encoding output.

Implementation Copy for EnabledCodings

impl Copy for EnabledCodings

EmptyEncodingPolicy

pub enum EmptyEncodingPolicy

The explicit automatic behavior when no decoder is enabled.

Identity

Identity = 0

Advertises identity when automatic negotiation enables no codec.

Omit

Omit = 1

Omits Accept-Encoding when automatic negotiation enables no codec.

AcceptEncoding

pub union AcceptEncoding<'value>

Automatic, exact borrowed override, or omitted Accept-Encoding policy.

Automatic

AcceptEncoding<'value>.Automatic { enabled: EnabledCodings, empty: EmptyEncodingPolicy }: AcceptEncoding<'value>

Advertises enabled codecs in stable gzip, deflate, zstd order for Decode mode.

Field enabled

pub enabled: EnabledCodings

The supported codecs to advertise.

Field empty

pub empty: EmptyEncodingPolicy

The policy when no codec is enabled.

Override

AcceptEncoding<'value>.Override { value: &'value [u8] }: AcceptEncoding<'value>

Uses the caller value exactly after shared HTTP header validation.

Field value

pub value: &'value [u8]

The borrowed field value; this value does not weaken response decoding validation.

Omit

AcceptEncoding<'value>.Omit: AcceptEncoding<'value>

Omits Accept-Encoding without constructing a header.

acceptEncoding

pub fn acceptEncoding<'value>(mode: Mode, policy: silk/http_content.AcceptEncoding<'value>, limits: HeaderLimits) -> silk/result.Result<silk/option.Option<silk/http.Header<'value>>, silk/http.ValueError>

Builds at most one validated Accept-Encoding field without mutating a request.

validateLimits

pub fn validateLimits<'head, 'life1>(limits: &'life1 silk/http_content.Limits) -> silk/result.Result<(), silk/http_content.ContentError<'head>>

Validates source-independent content limits without allocation or body I/O.

Details

maxDepth must be from one through four. intermediateCapacity must be from one through 65,536 bytes. Other byte limits can be zero and are enforced by planning or content I/O. Codec-specific storage validation occurs when a plan selects that codec.

Decoder

pub struct Decoder

Owned framing and content state for a caller-owned wire transport.

Details

Planning consumes borrowed metadata, but the resulting decoder owns all runtime state. The caller retains input bytes not consumed by step, including the next HTTP message suffix. A higher-level response owner must bind the plan and those wire bytes to the same response.

Associated function Decoder.make

pub effect<'env> fn make<'head: 'env, 'method: 'env, 'names: 'env, 'env>(plan: silk/http_content.CodingPlan<'head, 'method, 'names>) -> Decoder ! silk/http_content.ContentError<'head> | OutOfMemoryError ? &mut Allocator

Acquires the existing bounded framing and codec stack from one validated plan.

Method Decoder.step

pub fn step<'life0, 'life1, 'life2>(self: &'life0 mut Decoder, input: &'life1 [u8], output: &'life2 mut [u8], endOfInput: bool) -> silk/result.Result<silk/http_content.DecodeProgress, silk/http_content.DecodeFailure>

Advances without I/O, retaining exact consumed and written prefixes on failure.

Details

endOfInput promises no bytes follow the supplied input. Returned representation bytes remain provisional until completion confirms framing, checksums and pending output. Empty output completes locally without consuming input or changing a live decoder.

Method Decoder.progress

pub fn progress<'life0>(self: &'life0 Decoder) -> ContentProgress

Reports the current cumulative representation coordinates without advancing input.

Method Decoder.completion

pub fn completion<'owner>(self: &'owner Decoder) -> silk/result.Result<silk/option.Option<silk/http_content.ContentCompletion<'owner>>, silk/http_content.ContentError<'static>>

Borrows successful framing and content completion from this owner.

Method Decoder.trailers

pub fn trailers<'owner>(self: &'owner Decoder) -> silk/result.Result<silk/option.Option<silk/http_body.Trailers<'owner>>, silk/http_content.ContentError<'static>>

Borrows trailers only after successful content and body completion.

Method Decoder.abandon

pub fn abandon<'life0>(self: &'life0 mut Decoder) -> ()

Permanently abandons unfinished decoding without reading or draining the transport.

DecodeProgress

pub struct DecodeProgress

One incremental wire-to-representation transition.

Field consumed

pub consumed: usize

The exact wire prefix consumed from the supplied input.

Field progress

pub progress: ContentProgress

Provisional output and cumulative representation coordinates.

Field needsInput

pub needsInput: bool

Whether another wire prefix is needed before the decoder can advance.

DecodeFailure

pub struct DecodeFailure

A content failure with its committed input prefix and owned runtime cause.

Field consumed

pub consumed: usize

The exact wire prefix consumed before the failure.

Field error

pub error: silk/http_content.ContentError<'static>

The original content, framing, or codec failure and output coordinates.

ContentReader

pub struct ContentReader<'reader, 'transport, 'head, P>

One callback-scoped exclusive content reader.

Method ContentReader.representation

pub fn representation<'reader, 'transport, 'head, P, 'owner>(self: &'owner ContentReader<'reader, 'transport, 'head, P>) -> silk/result.Result<silk/http_content.RepresentationView<'owner, 'head>, silk/http_content.ContentError<'head>>

Borrows untouched wire metadata and the effective applied plan.

Method ContentReader.completion

pub fn completion<'reader, 'transport, 'head, P, 'owner>(self: &'owner ContentReader<'reader, 'transport, 'head, P>) -> silk/result.Result<silk/option.Option<silk/http_content.ContentCompletion<'owner>>, silk/http_content.ContentError<'head>>

Returns positive completion only after framing, codecs, and pending output finish.

Method ContentReader.trailers

pub fn trailers<'reader, 'transport, 'head, P, 'owner>(self: &'owner ContentReader<'reader, 'transport, 'head, P>) -> silk/result.Result<silk/option.Option<silk/http_body.Trailers<'owner>>, silk/http_content.ContentError<'head>>

Borrows trailers only through successful content and body completion.

Method ContentReader.readSome

pub effect<'env> fn readSome<'reader: 'env, 'transport: 'env, 'head: 'env, P: 'env, 'life4: 'env, 'life5: 'env, 'env>(self: &'life4 mut ContentReader<'reader, 'transport, 'head, P>, output: &'life5 mut [u8], deadline: silk/option.Option<silk/system_clock.Instant>) -> ContentProgress ! silk/http_content.ContentError<'head> ? &mut MonotonicClock where &mut P provides &ByteDuplex from &mut ByteDuplex | &mut MonotonicClock

Streams one provisional prefix with one unchanged absolute deadline.

withReader

pub effect<'env> fn withReader<'reader: 'env, 'transport: 'reader + 'env, 'head: 'reader + 'env, 'method: 'reader + 'env, 'names: 'reader + 'env, 'callback: 'env, A, E, ?CallbackRequirements, P: 'env, 'env>(plan: silk/http_content.CodingPlan<'head, 'method, 'names>, body: &'reader mut silk/buffered_duplex.BufferedDuplex<'transport, P>, callback: for<'call, 'readerView: 'call, 'transportView: 'readerView, 'headView: 'readerView> once fn<'callback>(&'call mut silk/http_content.ContentReader<'readerView, 'transportView, 'headView, P>) -> once Effect<'call; A ! E ? CallbackRequirements>) -> A ! E | silk/http_content.ContentError<'head> | OutOfMemoryError ? CallbackRequirements | &mut Allocator where &mut P provides &ByteDuplex from &mut ByteDuplex | &mut MonotonicClock

Runs one higher-ranked callback while exclusively borrowing the encoded body.