silk.http.headers.

When to use#

Use Headers.make to put Header values from silk.http.message in a list without a copy. Use Headers.copy when the list must live longer than its fields. Look up fields with Headers.getFirst, Headers.getUnique, or Headers.getAll.

Details#

Names are compared without case. Repeated fields stay separate, in their order, and are never joined into one value. Limits sets the maximum sizes, and every function checks them before it allocates. Headers.formatInto writes name: value\r\n for each field.

Errors#

• ValueError with LimitExceeded if a list exceeds its Limits.

• ValueError with OutputTooSmall if the output buffer is too small. Nothing is written.

Examples#

Look up repeated fields#

import silk.http.message { Header, ValueError }
import silk.http.headers { HeaderIterator, Headers, Limits }
import silk.core.option { Option }
import silk.core.result { Result }

fn limits() -> Limits {
  return Limits {
    maxMethodBytes: 64,
    maxTargetBytes: 8192,
    maxNameBytes: 256,
    maxValueBytes: 8192,
    maxFields: 16,
    maxFieldBytes: 4096,
    maxOwnedBytes: 8192,
  }
}

fn field(name: string<'static>, bytes: &'static [u8]) -> Header<'static> {
  return match Header.make(name, bytes, limits()) {
    Result<Header, ValueError>.Success { value } => value
    Result<Header, ValueError>.Failure { error: _ } => {
      Intrinsic.trap("unexpected failure")
      return field(name, bytes)
    }
  }
}

pub fn main() -> i32 {
  let entries = [field("Accept", b"text/html"), field("Vary", b"Accept"), field("ACCEPT", b"*/*")]
  let headers = match Headers.make(&entries, limits()) {
    Result<Headers, ValueError>.Success { value } => value
    Result<Headers, ValueError>.Failure { error: _ } => {
      return 1
    }
  }

  // Both Accept fields match, in their order.
  let mut accept = Headers.getAll(&headers, "accept")
  let mut count = 0
  while true {
    match HeaderIterator.next(&mut accept) {
      Option<Header>.Some { value: _ } => {
        count = count + 1
      }
      Option<Header>.None => {
        break
      }
    }
  }
  if count != 2 {
    return 1
  }

  // getUnique fails, because Accept occurs two times.
  let unique = match Headers.getUnique(&headers, "Accept") {
    Result<Option<Header>, ValueError>.Success { value: _ } => true
    Result<Option<Header>, ValueError>.Failure { error: _ } => false
  }
  if unique {
    return 1
  }
  let mut output: [u8; 64] = [0; 64]
  let length = match Headers.formatInto(&headers, &mut output) {
    Result<usize, ValueError>.Success { value } => value
    Result<usize, ValueError>.Failure { error: _ } => {
      return 1
    }
  }

  // "Accept: text/html\r\nVary: Accept\r\nACCEPT: */*\r\n"
  if length != 46 {
    return 1
  }
  return 0
}

Import as Headers with import silk.http.headers { Headers }.

Public declarations: 6.

Limits#

pub struct Limits

Maximum sizes for HTTP values, header lists, and copies. Every Headers function checks them before it allocates.

Field maxMethodBytes#

pub maxMethodBytes: usize

The maximum length of a method, in bytes.

Field maxTargetBytes#

pub maxTargetBytes: usize

The maximum length of a request target, in bytes.

Field maxNameBytes#

pub maxNameBytes: usize

The maximum length of a field name, in bytes.

Field maxValueBytes#

pub maxValueBytes: usize

The maximum length of a field value or a reason phrase, in bytes.

Field maxFields#

pub maxFields: usize

The maximum number of fields in a list.

Field maxFieldBytes#

pub maxFieldBytes: usize

The maximum total length of all names and values in a list, in bytes.

Field maxOwnedBytes#

pub maxOwnedBytes: usize

The maximum memory for a copy, in bytes, including its index. See Headers.requiredOwnedBytes.

Implementation Copy for Limits#

impl Copy for Limits

Headers#

pub struct Headers<'value>

An ordered list of header fields that borrows its fields.

When to use#

Use Headers.make to put Header values from silk.http.message in a list without a copy. Use Headers.copy when the list must live longer than its fields. Look up fields with Headers.getFirst, Headers.getUnique, or Headers.getAll.

Details#

Names are compared without case. Repeated fields stay separate, in their order, and are never joined into one value. Every function checks the Limits before it allocates.

Implementation Copy for Headers<'value>#

impl<'value> Copy for Headers<'value>

Implementation Headers<'value>#

impl<'value> Headers<'value>

Associated function make#

pub fn make(
    entries: &'value [Header<'value>],
    limits: Limits,
  ) -> Result<Headers<'value>, ValueError>

Checks entries against limits and returns a list that borrows them. It does not allocate.

Method count#

pub fn count(self: &Self) -> usize

Returns the number of fields, including repeated fields.

Method fieldBytes#

pub fn fieldBytes(self: &Self) -> usize

Returns the total length of all names and values, in bytes.

Method iter#

pub fn iter(self: &Self) -> HeaderIterator<'value>

Returns an iterator over all fields, in order.

Method getAll#

pub fn getAll(self: &Self, name: string<'value>) -> HeaderIterator<'value>

Returns an iterator over the fields named name, compared without case, in order.

Method getFirst#

pub fn getFirst(self: &Self, name: string) -> Option<Header<'value>>

Returns the first field named name, compared without case, or None.

Method getUnique#

pub fn getUnique(self: &Self, name: string) -> Result<Option<Header<'value>>, ValueError>

Returns the field named name, or None if there is no such field.

Errors#

• LimitExceeded with UniqueField if there is more than one such field.

Method copy#

pub effect fn copy(
    self: &Self,
    limits: Limits,
  ) -> Result<OwnedHeaders, ValueError> ! OutOfMemoryError ? &mut Allocator

Copies all fields into new memory, so that the copy does not borrow them.

Errors#

• LimitExceeded if the list exceeds limits. Nothing is allocated.

• OutOfMemoryError if the Allocator fails.

Method copyMatching#

pub effect fn copyMatching(
    self: &Self,
    name: string<'value>,
    limits: Limits,
  ) -> Result<OwnedHeaders, ValueError> ! OutOfMemoryError ? &mut Allocator

Copies only the fields named name, compared without case, into new memory.

Details#

Repeated fields stay separate, in their order. limits applies to the copied fields only, and is checked before allocation.

Method requiredOwnedBytes#

pub fn requiredOwnedBytes(self: &Self) -> Result<usize, ValueError>

Returns the memory that Headers.copy needs, to compare with maxOwnedBytes. It does not allocate.

Method formatInto#

pub fn formatInto(self: &Self, output: &mut [u8]) -> Result<usize, ValueError>

Writes name: value\r\n for each field to the start of output, and returns the length. It writes no start line and no empty line at the end.

Method connectionTokens#

pub fn connectionTokens(self: &Self) -> MetadataIterator<'value>

Returns an iterator over the options in all Connection fields, such as close or keep-alive.

Method contentCodings#

pub fn contentCodings(self: &Self) -> MetadataIterator<'value>

Returns an iterator over the codings in all Content-Encoding fields, such as gzip.

Method transferCodings#

pub fn transferCodings(self: &Self) -> MetadataIterator<'value>

Returns an iterator over the codings in all Transfer-Encoding fields, such as chunked. It also checks the parameters of each coding.

OwnedHeaders#

pub struct OwnedHeaders

A header list that owns its memory. Get a Headers from it with OwnedHeaders.view.

Implementation OwnedHeaders#

impl OwnedHeaders

Method view#

pub fn view<'value>(self: &'value Self) -> Headers<'value>

Returns the fields as a Headers that borrows this value.

Method ownedBytes#

pub fn ownedBytes(self: &Self) -> usize

Returns the memory that this copy uses, in bytes, as counted against maxOwnedBytes.

HeaderIterator#

pub struct HeaderIterator<'value>

An iterator over header fields, in order. Get it from Headers.iter or Headers.getAll.

Implementation HeaderIterator<'value>#

impl<'value> HeaderIterator<'value>

Method next#

pub fn next(self: &mut Self) -> Option<Header<'value>>

Returns the next field, or None at the end.

Method fieldIndex#

pub fn fieldIndex(self: &Self) -> usize

Returns the position in the list of the last field from HeaderIterator.next, from 0.

MetadataToken#

pub struct MetadataToken<'value>

One item of a list field, such as gzip in Content-Encoding: gzip, br.

Implementation Copy for MetadataToken<'value>#

impl<'value> Copy for MetadataToken<'value>

Implementation MetadataToken<'value>#

impl<'value> MetadataToken<'value>

Method token#

pub fn token(self: &Self) -> &'value [u8]

Returns the name of the item, without parameters.

Method raw#

pub fn raw(self: &Self) -> &'value [u8]

Returns the whole item, with its parameters.

Method fieldIndex#

pub fn fieldIndex(self: &Self) -> usize

Returns the position in the list of the field that holds this item, from 0.

Method offset#

pub fn offset(self: &Self) -> usize

Returns the byte offset of the item in the field value.

Method matches#

pub fn matches(self: &Self, known: string) -> bool

Returns true if the name of the item equals known, compared without case.

MetadataIterator#

pub struct MetadataIterator<'value>

An iterator over the items of list fields, such as Connection or Content-Encoding.

Implementation MetadataIterator<'value>#

impl<'value> MetadataIterator<'value>

Method next#

pub fn next(self: &mut Self) -> Result<Option<MetadataToken<'value>>, ValueError>

Returns the next item, or None at the end.

Errors#

• ValueError with the location of the problem, if the field value is not a valid list.

Category: HTTP.

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