Structured Field Values for HTTP

sfv is an implementation of Structured Field Values for HTTP as specified in RFC 9651 for parsing and serializing HTTP field values (also known as "structured headers" or "structured trailers").

It also exposes a set of types that might be useful for defining new structured fields.

License

lib.rs:

sfv is an implementation of Structured Field Values for HTTP, as specified in RFC 9651 for parsing and serializing HTTP field values. It also exposes a set of types that might be useful for defining new structured fields.

Data Structures

There are three types of structured fields:

• Item -- an Integer, Decimal, String, Token, Byte Sequence, Boolean, Date, or Display String. It can have associated Parameters.
• List -- an array of zero or more members, each of which can be an Item or an InnerList, both of which can have Parameters.
• Dictionary -- an ordered map of name-value pairs, where the names are short textual strings and the values are Items or arrays of Items (represented with InnerList), both of which can have associated parameters. There can be zero or more members, and their names are unique in the scope of the Dictionary they occur within.

There are also a few lower-level types used to construct structured field values:

• BareItem is used as Item's value or as a parameter value in Parameters.
• Parameters are an ordered map of key-value pairs that are associated with an Item or InnerList. The keys are unique within the scope the Parameters they occur within, and the values are BareItem.
• InnerList is an array of zero or more Items. Can have associated Parameters.
• ListEntry represents either Item or InnerList as a member of List or as member-value in Dictionary.

Examples

Serialization

Serializes an Item:

use sfv::{Decimal, ItemSerializer, KeyRef, StringRef};

let serialized_item = ItemSerializer::new()
.bare_item(StringRef::from_str("foo")?)
.parameter(KeyRef::from_str("key")?, Decimal::try_from(13.45655)?)
.finish();

assert_eq!(serialized_item, r#""foo";key=13.457"#);

Serializes a List:

use sfv::{KeyRef, ListSerializer, StringRef, TokenRef};

let mut ser = ListSerializer::new();

ser.bare_item(TokenRef::from_str("tok")?);

{
let mut ser = ser.inner_list();

ser.bare_item(99).parameter(KeyRef::from_str("key")?, false);

ser.bare_item(StringRef::from_str("foo")?);

ser.finish().parameter(KeyRef::from_str("bar")?, true);
}

let serialized_list = ser.finish()?;

assert_eq!(
serialized_list,
r#"tok, (99;key=?0 "foo");bar"#
);

Serializes a Dictionary:

use sfv::{DictSerializer, KeyRef, StringRef};

let mut ser = DictSerializer::new();

ser.bare_item(KeyRef::from_str("key1")?, StringRef::from_str("apple")?);

ser.bare_item(KeyRef::from_str("key2")?, true);

ser.bare_item(KeyRef::from_str("key3")?, false);

let serialized_dict = ser.finish()?;

assert_eq!(
serialized_dict,
r#"key1="apple", key2, key3=?0"#
);

Crate features

• parsed-types (enabled by default) -- When enabled, exposes fully owned types Item, Dictionary, List, and their components, which can be obtained from Parser::parse_item, etc. These types are implemented using the indexmap crate, so disabling this feature can avoid that dependency if parsing using a visitor (Parser::parse_item_with_visitor, etc.) is sufficient.

• arbitrary -- Implements the Arbitrary trait for this crate's types, making them easier to use with fuzzing.