Browse the docs

silk.http.message.

HTTP/1.0 and HTTP/1.1 values: versions, methods, statuses, header fields, and message heads.

When to use#

Use these types to make or inspect an HTTP message head. silk.http.head parses and writes them, and the client and server modules take them. Each make and parse function checks the value. The values borrow their text. Call copy on a head to keep it after its input is gone.

Details#

A Method is any valid token, and keeps its spelling, so get and GET are different. A Status is any code from 100 to 599. A Header keeps the exact bytes of its name and value. RequestHead.make checks that the target form fits the method, and that an HTTP/1.1 request has one Host field. This module does not read or write bodies.

Errors#

Gotchas#

Header.make takes the value without the spaces around it on the wire. It rejects CR, LF, NUL, DEL, other control bytes, and leading or trailing spaces or tabs.

Examples#

Make a response head#

silk
import silk.http.message { Header, ResponseHead, Status, StatusClass, ValueError, Version }
import silk.http.headers { 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: 128,
    maxFieldBytes: 65536,
    maxOwnedBytes: 131072,
  }
}

pub fn main() -> i32 {
  let status = match Status.fromCode(404) {
    Result<Status, ValueError>.Success { value } => value
    Result<Status, ValueError>.Failure { error: _ } => {
      return 1
    }
  }
  if Status.class(&status) != StatusClass.ClientError {
    return 1
  }
  let header = match Header.make("Content-Type", b"text/plain", limits()) {
    Result<Header, ValueError>.Success { value } => value
    Result<Header, ValueError>.Failure { error: _ } => {
      return 1
    }
  }
  let entries = [header]
  let headers = match Headers.make(&entries, limits()) {
    Result<Headers, ValueError>.Success { value } => value
    Result<Headers, ValueError>.Failure { error: _ } => {
      return 1
    }
  }
  let reason = b"Not Found"
  let head = match ResponseHead.make(
    Version.Http11,
    status,
    Option<&[u8]>.some(&reason),
    headers,
    limits(),
  ) {
    Result<ResponseHead, ValueError>.Success { value } => move value
    Result<ResponseHead, ValueError>.Failure { error: _ } => {
      return 1
    }
  }
  if Status.code(&ResponseHead.status(&head)) != 404 {
    return 1
  }

  // A value with a line break fails.
  let bad = match Header.make("X-Note", b"a\r\nb", limits()) {
    Result<Header, ValueError>.Success { value: _ } => false
    Result<Header, ValueError>.Failure { error } => error.offset == 1
  }
  if !bad {
    return 1
  }
  return 0
}

Import as Version with import silk.http.message { Version }.

Public declarations: 13.

ValueComponent#

silk
pub enum ValueComponent

The part of an HTTP value that failed a check. See ValueError.component.

Version#

silk
Version

An HTTP version token.

Method#

silk
Method

A request method token.

Status#

silk
Status

A numeric response status.

HeaderName#

silk
HeaderName

A field name.

HeaderValue#

silk
HeaderValue

A field value.

ReasonPhrase#

silk
ReasonPhrase

An optional response reason phrase.

Headers#

silk
Headers

A list of header fields.

Target#

silk
Target

A request target.

Authority#

silk
Authority

An HTTP authority.

Host#

silk
Host

The Host field of a request.

Metadata#

silk
Metadata

A list in a field such as Connection, Content-Encoding, or Transfer-Encoding.

Implementation Debug for ValueComponent#

silk
impl Debug for ValueComponent

Operation debug#

silk
effect fn debug(self: &Self, formatter: &mut Formatter) -> () ! WriterError ? &mut Writer

Writes the name of the variant, such as Version.

LimitKind#

silk
pub enum LimitKind

The limit in Limits that a value exceeded. See ValueReason.LimitExceeded.

MethodBytes#

silk
MethodBytes

maxMethodBytes: the length of a method.

TargetBytes#

silk
TargetBytes

maxTargetBytes: the length of a request target.

NameBytes#

silk
NameBytes

maxNameBytes: the length of a field name.

ValueBytes#

silk
ValueBytes

maxValueBytes: the length of a field value or a reason phrase.

Fields#

silk
Fields

maxFields: the number of fields.

FieldBytes#

silk
FieldBytes

maxFieldBytes: the total length of all names and values.

OwnedBytes#

silk
OwnedBytes

maxOwnedBytes: the memory for a copy.

UniqueField#

silk
UniqueField

A field must occur at most one time, but it occurred more times.

Implementation Debug for LimitKind#

silk
impl Debug for LimitKind

Operation debug#

silk
effect fn debug(self: &Self, formatter: &mut Formatter) -> () ! WriterError ? &mut Writer

Writes the name of the variant, such as MethodBytes.

ValueReason#

silk
pub union ValueReason

The rule that failed. See ValueError.reason.

InvalidToken#

silk
InvalidToken

A token, such as a method or a field name, is empty or has a byte that is not allowed in a token.

InvalidValueByte#

silk
InvalidValueByte

A value has a byte that is not allowed, such as CR, LF, or NUL.

UnsupportedVersion#

silk
UnsupportedVersion

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

InvalidStatus#

silk
InvalidStatus

A response code is outside 100 through 599.

InvalidTarget#

silk
InvalidTarget

A request target has invalid syntax.

InvalidAuthority#

silk
InvalidAuthority

An HTTP authority has invalid syntax.

InvalidPort#

silk
InvalidPort

A port is absent, empty, nonnumeric, or outside its accepted range.

MethodTargetMismatch#

silk
MethodTargetMismatch

The target form does not fit the method. For example, CONNECT needs host:port, and only OPTIONS can use *.

MissingHost#

silk
MissingHost

HTTP/1.1 has no Host field.

DuplicateHost#

silk
DuplicateHost

More than one Host field is present.

LimitExceeded#

silk
LimitExceeded

A value exceeded a limit in Limits.

Field limit#

silk
pub limit: LimitKind

The limit that was exceeded.

Field allowed#

silk
pub allowed: usize

The value of the limit.

Field attempted#

silk
pub attempted: usize

The size that was found.

SizeOverflow#

silk
SizeOverflow

A size calculation overflowed usize.

OutputTooSmall#

silk
OutputTooSmall

The output buffer is too small. Nothing was written.

Field required#

silk
pub required: usize

The number of bytes that the output needs.

Field available#

silk
pub available: usize

The length of the buffer that you gave.

Implementation Copy for ValueReason#

silk
impl Copy for ValueReason

Implementation Debug for ValueReason#

silk
impl Debug for ValueReason

Operation debug#

silk
effect fn debug(self: &Self, formatter: &mut Formatter) -> () ! WriterError ? &mut Writer

Writes the name of the variant and its fields, such as InvalidToken.

ValueError#

silk
pub struct ValueError

The error from checking an HTTP value. It tells which rule failed, and where.

Details#

reason gives the rule, component the part of the value, and fieldIndex and offset the position.

Field reason#

silk
pub reason: ValueReason

The rule that failed.

Field component#

silk
pub component: ValueComponent

The part that failed.

Field fieldIndex#

silk
pub fieldIndex: Option<usize>

The position of the field in its list, from 0, when the error is in a field.

Field offset#

silk
pub offset: usize

The byte offset in the part where the rule failed.

Implementation Debug for ValueError#

silk
impl Debug for ValueError

Operation debug#

silk
effect fn debug(self: &Self, formatter: &mut Formatter) -> () ! WriterError ? &mut Writer

Writes the fields, as ValueError { reason: ..., component: ..., ... }.

Version#

silk
pub enum Version

An HTTP version that this module supports.

Http10#

silk
Http10

HTTP/1.0.

Http11#

silk
Http11

HTTP/1.1.

Implementation Debug for Version#

silk
impl Debug for Version

Operation debug#

silk
effect fn debug(self: &Self, formatter: &mut Formatter) -> () ! WriterError ? &mut Writer

Writes the name of the variant, such as Http10.

Implementation Version#

silk
impl Version

Associated function parse#

silk
pub fn parse(text: string) -> Result<Version, ValueError>

Parses exactly HTTP/1.0 or HTTP/1.1.

Method format#

silk
pub fn format(self: &Self) -> string<'static>

Returns HTTP/1.0 or HTTP/1.1.

Method#

silk
pub struct Method<'text>

An HTTP method, such as GET. It keeps its exact spelling, and is compared with case.

Details#

Any valid token is a method, so get and GET are different methods. It borrows its text. The make and parse functions check the token.

Implementation Copy for Method<'text>#

silk
impl<'text> Copy for Method<'text>

Implementation Method<'text>#

silk
impl<'text> Method<'text>

Associated function parse#

silk
pub fn parse(text: string<'text>, maxBytes: usize) -> Result<Method<'text>, ValueError>

Checks that text is a token of at most maxBytes bytes, and returns it as a method.

Method format#

silk
pub fn format(self: &Self) -> string<'text>

Returns the method text, spelled as given.

Method equals#

silk
pub fn equals(self: &Self, other: &Method) -> bool

Returns true if the two methods have the same spelling. Case matters.

Associated function get#

silk
pub fn get() -> Method<'static>

Returns the standard GET method value.

Associated function head#

silk
pub fn head() -> Method<'static>

Returns the standard HEAD method value.

Associated function post#

silk
pub fn post() -> Method<'static>

Returns the standard POST method value.

Associated function put#

silk
pub fn put() -> Method<'static>

Returns the standard PUT method value.

Associated function delete#

silk
pub fn delete() -> Method<'static>

Returns the standard DELETE method value.

Associated function connect#

silk
pub fn connect() -> Method<'static>

Returns the standard CONNECT method value.

Associated function options#

silk
pub fn options() -> Method<'static>

Returns the standard OPTIONS method value.

Associated function trace#

silk
pub fn trace() -> Method<'static>

Returns the standard TRACE method value.

Associated function patch#

silk
pub fn patch() -> Method<'static>

Returns the standard PATCH method value.

StatusClass#

silk
pub enum StatusClass

The class of a status code, from its first digit.

Informational#

silk
Informational

1xx informational.

Successful#

silk
Successful

2xx successful.

Redirection#

silk
Redirection

3xx redirection.

ClientError#

silk
ClientError

4xx client error.

ServerError#

silk
ServerError

5xx server error.

Status#

silk
pub struct Status

An HTTP status code from 100 to 599. Codes without a name, such as 299, are kept.

Implementation Copy for Status#

silk
impl Copy for Status

Implementation Debug for Status#

silk
impl Debug for Status

Operation debug#

silk
effect fn debug(self: &Self, formatter: &mut Formatter) -> () ! WriterError ? &mut Writer

Writes the code, as Status { code: 404 }.

Implementation Status#

silk
impl Status

Associated function fromCode#

silk
pub fn fromCode(code: u16) -> Result<Status, ValueError>

Returns the status for code, or InvalidStatus if code is not from 100 to 599.

Method code#

silk
pub fn code(self: &Self) -> u16

Returns the code, such as 404.

Method class#

silk
pub fn class(self: &Self) -> StatusClass

Returns the class, from the first digit of the code.

Header#

silk
pub struct Header<'value>

An HTTP header field. It borrows its name and value, and keeps their exact bytes.

Gotchas#

Header.make takes the value without the spaces around it on the wire. It rejects CR, LF, NUL, DEL, other control bytes, and leading or trailing spaces or tabs.

Implementation Copy for Header<'value>#

silk
impl<'value> Copy for Header<'value>

Implementation Header<'value>#

silk
impl<'value> Header<'value>

Associated function make#

silk
pub fn make(
    name: string<'value>,
    value: &'value [u8],
    limits: Limits,
  ) -> Result<Header<'value>, ValueError>

Checks a field and returns it.

name must be a token. value is the value without the spaces around it on the wire.

Errors#

  • InvalidToken if name is not valid.

  • InvalidValueByte if value has a control byte, or starts or ends with a space or a tab.

  • LimitExceeded if name or value is too long for limits.

Method name#

silk
pub fn name(self: &Self) -> string<'value>

Returns the field name, spelled as given.

Method value#

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

Returns the field value bytes.

RequestHead#

silk
pub struct RequestHead<'value>

A checked request line and header fields, without a body. It borrows its parts.

Implementation Copy for RequestHead<'value>#

silk
impl<'value> Copy for RequestHead<'value>

Implementation RequestHead<'value>#

silk
impl<'value> RequestHead<'value>

Associated function make#

silk
pub fn make(
    version: Version,
    method: Method<'value>,
    target: RequestTarget<'value>,
    headers: Headers<'value>,
  ) -> Result<RequestHead<'value>, ValueError>

Checks the parts of a request head and returns it.

Errors#

  • MethodTargetMismatch if the target form does not fit the method.

  • MissingHost or DuplicateHost if an HTTP/1.1 request has no Host field, or more than one.

Method version#

silk
pub fn version(self: &Self) -> Version

Returns the request version.

Method method#

silk
pub fn method(self: &Self) -> Method<'value>

Returns the method.

Method target#

silk
pub fn target(self: &Self) -> RequestTarget<'value>

Returns the request target.

Method headers#

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

Returns the header fields, in order.

Method copy#

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

Copies the head into new memory, so that it does not borrow its input.

Errors#

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

  • OutOfMemoryError if the Allocator fails.

OwnedRequestHead#

silk
pub struct OwnedRequestHead

A request head that owns its memory. Get a RequestHead from it with OwnedRequestHead.view.

Implementation OwnedRequestHead#

silk
impl OwnedRequestHead

Method view#

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

Returns the head as a RequestHead that borrows this value.

ResponseHead#

silk
pub struct ResponseHead<'value>

A checked status line and header fields, without a body. It borrows its parts.

Implementation ResponseHead<'value>#

silk
impl<'value> ResponseHead<'value>

Associated function make#

silk
pub fn make(
    version: Version,
    status: Status,
    reason: Option<&'value [u8]>,
    headers: Headers<'value>,
    limits: Limits,
  ) -> Result<ResponseHead<'value>, ValueError>

Checks the parts of a response head and returns it.

reason is the optional text after the status code, such as Not Found.

Errors#

  • InvalidValueByte if reason has a control byte.

  • LimitExceeded if reason is longer than maxValueBytes.

Method version#

silk
pub fn version(self: &Self) -> Version

Returns the response version.

Method status#

silk
pub fn status(self: &Self) -> Status

Returns the status.

Method reason#

silk
pub fn reason(self: &Self) -> Option<&'value [u8]>

Returns the reason phrase, if there is one.

Method headers#

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

Returns the header fields, in order.

Method copy#

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

Copies the head into new memory, so that it does not borrow its input.

Errors#

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

  • OutOfMemoryError if the Allocator fails.

Method copyMatchingHeaders#

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

Copies the status, the reason, and only the fields named name, into new memory.

Details#

Names are compared without case. Repeated fields stay separate, in their order. limits applies to the copied parts only.

OwnedResponseHead#

silk
pub struct OwnedResponseHead

A response head that owns its memory. Get a ResponseHead from it with OwnedResponseHead.view.

Implementation Debug for OwnedResponseHead#

silk
impl Debug for OwnedResponseHead

Operation debug#

silk
effect fn debug(self: &Self, formatter: &mut Formatter) -> () ! WriterError ? &mut Writer

Writes the version and the status, as OwnedResponseHead { version: Http11, status: Status { code: 407 } }. It leaves out the reason phrase and the headers.

Implementation OwnedResponseHead#

silk
impl OwnedResponseHead

Method view#

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

Returns the head as a ResponseHead that borrows this value.

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.

View the source of this page