httpsfv

README

httpsfv: Structured Field Values for HTTP in Go

This Go (golang) library implements parsing and serialization for Structured Field Values for HTTP (RFC 8941).

Features

• Fully implementing the RFC
• Compliant with the official test suite
• Unit and fuzz tested
• Strongly-typed
• Fast (see the benchmark)
• No dependencies

Docs

Browse the documentation on Go.dev.

Credits

Created by Kévin Dunglas. Sponsored by Les-Tilleuls.coop.

Documentation

Overview

Package httpsfv implements serializing and parsing of Structured Field Values for HTTP as defined in RFC 8941.

Structured Field Values are either lists, dictionaries or items. Dedicated types are provided for all of them. Dedicated types are also used for tokens, parameters and inner lists. Other values are stored in native types:

int64, for integers
float64, for decimals
string, for strings
byte[], for byte sequences
bool, for booleans

The specification is available at https://httpwg.org/specs/rfc8941.html.

Index

• Variables
• func Marshal(v StructuredFieldValue) (string, error)
• type Dictionary
  • func NewDictionary() *Dictionary
  • func UnmarshalDictionary(v []string) (*Dictionary, error)
  • func (d *Dictionary) Add(k string, v Member)
  • func (d *Dictionary) Del(key string) bool
  • func (d *Dictionary) Get(k string) (Member, bool)
  • func (d *Dictionary) Names() []string
• type InnerList
• type Item
  • func NewItem(v interface{}) Item
  • func UnmarshalItem(v []string) (Item, error)
• type List
  • func UnmarshalList(v []string) (List, error)
• type Member
• type Params
  • func NewParams() *Params
  • func (p *Params) Add(k string, v interface{})
  • func (p *Params) Del(key string) bool
  • func (p *Params) Get(k string) (interface{}, bool)
  • func (p *Params) Names() []string
• type StructuredFieldValue
• type Token
• type UnmarshalError
  • func (e *UnmarshalError) Error() string
  • func (e *UnmarshalError) Unwrap() error

Examples

• Marshal
• UnmarshalList

Variables

var ErrInvalidBareItem = errors.New(
	"invalid bare item type (allowed types are bool, string, int64, float64, []byte and Token)",
)

ErrInvalidBareItem is returned when a bare item is invalid.

var ErrInvalidBinaryFormat = errors.New("invalid binary format")

ErrInvalidBinaryFormat is returned when the binary format is invalid.

var ErrInvalidBooleanFormat = errors.New("invalid boolean format")

ErrInvalidBooleanFormat is returned when a boolean format is invalid.

var ErrInvalidDecimal = errors.New("the integer portion is larger than 12 digits: invalid decimal")

ErrInvalidDecimal is returned when a decimal is invalid.

var ErrInvalidDecimalFormat = errors.New("invalid decimal format")

ErrInvalidDecimalFormat is returned when the decimal format is invalid.

var ErrInvalidDictionaryFormat = errors.New("invalid dictionary format")

ErrInvalidDictionaryFormat is returned when a dictionary value is invalid.

var ErrInvalidInnerListFormat = errors.New("invalid inner list format")

ErrInvalidInnerListFormat is returned when an inner list format is invalid.

var ErrInvalidKeyFormat = errors.New("invalid key format")

ErrInvalidKeyFormat is returned when the format of a parameter or dictionary key is invalid.

var ErrInvalidListFormat = errors.New("invalid list format")

ErrInvalidListFormat is returned when the format of a list is invalid.

var ErrInvalidParameterFormat = errors.New("invalid parameter format")

ErrInvalidParameterFormat is returned when the format of a parameter is invalid.

var ErrInvalidParameterValue = errors.New("invalid parameter value")

ErrInvalidParameterValue is returned when a parameter key is invalid.

var ErrInvalidStringFormat = errors.New("invalid string format")

ErrInvalidStringFormat is returned when a string format is invalid.

var ErrInvalidTokenFormat = errors.New("invalid token format")

ErrInvalidTokenFormat is returned when a token format is invalid.

var ErrMissingParameters = errors.New("missing parameters")

ErrMissingParameters is returned when the Params structure is missing from the element.

var ErrNotDigit = errors.New("character is not a digit")

ErrNotDigit is returned when a character should be a digit but isn't.

var ErrNumberOutOfRange = errors.New("integer or decimal out of range")

ErrNumberOutOfRange is returned when the number is too large according to the specification.

var ErrUnexpectedEndOfString = errors.New("unexpected end of string")

ErrUnexpectedEndOfString is returned when the end of string is unexpected.

var ErrUnrecognizedCharacter = errors.New("unrecognized character")

ErrUnrecognizedCharacter is returned when an unrecognized character in encountered.

Functions

func Marshal

func Marshal(v StructuredFieldValue) (string, error)

Marshal returns the HTTP Structured Value serialization of v as defined in https://httpwg.org/specs/rfc8941.html#text-serialize.

v must be a List, a Dictionary, an Item or an InnerList.

Example

p := List{NewItem("/member/*/author"), NewItem("/member/*/comments")}

v, err := Marshal(p)
if err != nil {
	log.Fatalln("error: ", err)
}

h := http.Header{}
h.Set("Preload", v)

b := new(bytes.Buffer)
_ = h.Write(b)

fmt.Println(b.String())

Output:

Preload: "/member/*/author", "/member/*/comments"

Types

type Dictionary

type Dictionary struct {
	// contains filtered or unexported fields
}

Dictionary is an ordered map of name-value pairs. See https://httpwg.org/specs/rfc8941.html#dictionary Values can be:

• Item (Section 3.3.)
• Inner List (Section 3.1.1.)

func NewDictionary

func NewDictionary() *Dictionary

NewDictionary creates a new ordered map.

func UnmarshalDictionary

func UnmarshalDictionary(v []string) (*Dictionary, error)

UnmarshalDictionary parses a dictionary as defined in https://httpwg.org/specs/rfc8941.html#parse-dictionary.

func (*Dictionary) Add

func (d *Dictionary) Add(k string, v Member)

Add appends a new member to the ordered list.

func (*Dictionary) Del

func (d *Dictionary) Del(key string) bool

Del removes a member from the ordered list.

func (*Dictionary) Get

func (d *Dictionary) Get(k string) (Member, bool)

Get retrieves a member.

func (*Dictionary) Names

func (d *Dictionary) Names() []string

Names retrieves the list of member names in the appropriate order.

type InnerList

type InnerList struct {
	Items  []Item
	Params *Params
}

InnerList represents an inner list as defined in https://httpwg.org/specs/rfc8941.html#inner-list.

type Item

type Item struct {
	Value  interface{}
	Params *Params
}

Item is a bare value and associated parameters. See https://httpwg.org/specs/rfc8941.html#item.

func NewItem

func NewItem(v interface{}) Item

NewItem returns a new Item.

func UnmarshalItem

func UnmarshalItem(v []string) (Item, error)

UnmarshalItem parses an item as defined in https://httpwg.org/specs/rfc8941.html#parse-item.

type List

type List []Member

List contains items an inner lists.

See https://httpwg.org/specs/rfc8941.html#list

func UnmarshalList

func UnmarshalList(v []string) (List, error)

UnmarshalList parses a list as defined in https://httpwg.org/specs/rfc8941.html#parse-list.

Example

h := http.Header{}
h.Add("Preload", `"/member/*/author", "/member/*/comments"`)

v, err := UnmarshalList(h["Preload"])
if err != nil {
	log.Fatalln("error: ", err)
}

fmt.Println("authors selector: ", v[0].(Item).Value)
fmt.Println("comments selector: ", v[1].(Item).Value)

Output:

authors selector:  /member/*/author
comments selector:  /member/*/comments

type Member

type Member interface {
	// contains filtered or unexported methods
}

Member is a marker interface for members of dictionaries and lists.

See https://httpwg.org/specs/rfc8941.html#list.

type Params

type Params struct {
	// contains filtered or unexported fields
}

Params are an ordered map of key-value pairs that are associated with an item or an inner list.

See https://httpwg.org/specs/rfc8941.html#param.

func NewParams

func NewParams() *Params

NewParams creates a new ordered map.

func (*Params) Add

func (p *Params) Add(k string, v interface{})

Add appends a new parameter to the ordered list. If the key already exists, overwrite its value.

func (*Params) Del

func (p *Params) Del(key string) bool

Del removes a parameter from the ordered list.

func (*Params) Get

func (p *Params) Get(k string) (interface{}, bool)

Get retrieves a parameter.

func (*Params) Names

func (p *Params) Names() []string

Names retrieves the list of parameter names in the appropriate order.

type StructuredFieldValue

type StructuredFieldValue interface {
	// contains filtered or unexported methods
}

StructuredFieldValue represents a List, a Dictionary or an Item.

type Token

type Token string

Token represents a token as defined in https://httpwg.org/specs/rfc8941.html#token. A specific type is used to distinguish tokens from strings.

type UnmarshalError

type UnmarshalError struct {
	// contains filtered or unexported fields
}

UnmarshalError contains the underlying parsing error and the position at which it occurred.

func (*UnmarshalError) Error

func (e *UnmarshalError) Error() string

func (*UnmarshalError) Unwrap

func (e *UnmarshalError) Unwrap() error