README
¶
github.com/lestrrat-go/sfv 
Go module implementing RFC 9651 Structured Field Values for HTTP.
Features
- Complete implementation of RFC 9651 Structured Field Values specification
- Parse and serialize Items, Lists, and Dictionaries
- Support for all SFV data types: Integers, Decimals, Strings, Tokens, Byte Sequences, Booleans, and Dates
- Full parameter support for Items and Inner Lists
- Clean, type-safe API
SYNOPSIS
package examples_test
import (
"fmt"
"log"
"github.com/lestrrat-go/sfv"
)
func Example() {
// Parse various SFV types
// Parse a simple string item
item, err := sfv.ParseItem([]byte(`"hello world"`))
if err != nil {
log.Fatal(err)
}
itemSerialized, _ := sfv.Marshal(item)
fmt.Printf("Parsed string item: %s\n", string(itemSerialized))
// Parse a list with mixed types
list, err := sfv.Parse([]byte(`"text", 42, ?1, @1659578233`))
if err != nil {
log.Fatal(err)
}
listSerialized, _ := sfv.Marshal(list)
fmt.Printf("Parsed list: %s\n", string(listSerialized))
// Parse a dictionary
dict, err := sfv.ParseDictionary([]byte(`key1="value1", key2=42, flag`))
if err != nil {
log.Fatal(err)
}
dictSerialized, _ := sfv.Marshal(dict)
fmt.Printf("Parsed dictionary: %s\n", string(dictSerialized))
// Create and serialize SFV values programmatically
// Create a dictionary with various data types
newDict := sfv.NewDictionary()
newDict.Set("name", sfv.String("John Doe"))
newDict.Set("age", sfv.Integer(30))
newDict.Set("active", sfv.Boolean(true))
newDict.Set("score", sfv.Decimal(98.5))
newDict.Set("data", sfv.ByteSequence([]byte("hello")))
// Serialize the dictionary
serialized, err := sfv.Marshal(newDict)
if err != nil {
log.Fatal(err)
}
fmt.Printf("Serialized dictionary: %s\n", string(serialized))
// Work with parameters on items
itemWithParams := sfv.String("cached-resource")
itemWithParams.Parameter("max-age", 3600)
itemWithParams.Parameter("public", true)
paramSerialized, err := sfv.Marshal(itemWithParams)
if err != nil {
log.Fatal(err)
}
fmt.Printf("Item with parameters: %s\n", string(paramSerialized))
// Create a list with inner lists
mainList := &sfv.List{}
// Add simple items
mainList.Add(sfv.String("item1"))
mainList.Add(sfv.Integer(42))
// Add an inner list with parameters
innerList := &sfv.InnerList{}
innerList.Add(sfv.String("inner1"))
innerList.Add(sfv.String("inner2"))
// Inner lists can have parameters too
mainList.Add(innerList)
complexSerialized, err := sfv.Marshal(mainList)
if err != nil {
log.Fatal(err)
}
fmt.Printf("Complex list: %s\n", string(complexSerialized))
// OUTPUT:
// Parsed string item: "hello world"
// Parsed list: "text", 42, ?1, @1659578233
// Parsed dictionary: key1="value1", key2=42, flag
// Serialized dictionary: name="John Doe", age=30, active, score=98.5, data=:aGVsbG8=:
// Item with parameters: "cached-resource"; max-age=3600; public
// Complex list: "item1", 42, ("inner1" "inner2")
}
source: examples/sfv_readme_example_test.go
How-to Documentation
Description
This Go module implements RFC 9651 Structured Field Values, a specification for parsing and serializing structured data in HTTP header fields and other contexts.
Example Use Cases
HTTP Cache-Control Header
// Parse: "max-age=3600, must-revalidate, private"
dict, _ := sfv.ParseDictionary([]byte(`max-age=3600, must-revalidate, private`))
var maxAge int64
dict.GetValue("max-age", &maxAge) // maxAge = 3600
HTTP Message Signatures
// Create signature parameters for HTTP Message Signatures
params := sfv.NewDictionary()
params.Set("created", sfv.Date(time.Now().Unix()))
params.Set("keyid", sfv.String("key-123"))
// Serialize for Signature-Input header
sigInput, _ := sfv.Marshal(params)
Contributions
Issues
For bug reports and feature requests, please try to follow the issue templates as much as possible. For either bug reports or feature requests, failing tests are even better.
Pull Requests
Please make sure to include tests that exercise the changes you made.
Discussions / Usage
Please try discussions first.
License
MIT License. See LICENSE file for details.
Documentation
¶
Index ¶
- Constants
- func Marshal(v any) ([]byte, error)
- func Parse(data []byte) (any, error)
- type BareItem
- type BooleanBareItem
- type BooleanItem
- type ByteSequenceBareItem
- type ByteSequenceItem
- type CoreItem
- type DateBareItem
- type DateItem
- type DecimalBareItem
- type DecimalItem
- type Dictionary
- type DisplayStringBareItem
- func (iv DisplayStringBareItem) GetValue(dst any) error
- func (d DisplayStringBareItem) MarshalSFV() ([]byte, error)
- func (iv *DisplayStringBareItem) SetValue(value T) error
- func (d *DisplayStringBareItem) ToItem() Item
- func (d DisplayStringBareItem) Type() int
- func (iv *DisplayStringBareItem) Value() T
- type DisplayStringItem
- type Encoder
- type FullItem
- func (fi *FullItem[BT, UT]) GetValue(dst any) error
- func (fi *FullItem[BT, UT]) MarshalSFV() ([]byte, error)
- func (fi *FullItem[BT, UT]) Parameter(name string, value any) error
- func (fi *FullItem[BT, UT]) Parameters() *Parameters
- func (fi *FullItem[BT, UT]) Type() int
- func (fi *FullItem[BT, UT]) Value() UT
- func (fi *FullItem[BT, UT]) With(params *Parameters) Item
- type InnerList
- type IntegerBareItem
- type IntegerItem
- type Item
- type List
- type Marshaler
- type Parameters
- type StringBareItem
- type StringItem
- type TokenBareItem
- type TokenItem
- type Value
Constants ¶
const ( InvalidType = iota IntegerType DecimalType StringType TokenType ByteSequenceType BooleanType DateType DisplayStringType )
Variables ¶
This section is empty.
Functions ¶
Types ¶
type BareItem ¶
A BareItem represents a bare item, which is the itemValue plus the item type. A bare item cannot carry parameters. However, it _can_ be upgraded to a full Item by calling ToItem().
func BareItemFrom ¶
BareItemFrom creates a BareItem from the given Go value. This function converts common Go types (string, bool, int, int64, float64, float32) to their corresponding SFV bare item types. For strings, it creates a StringBareItem by default.
type BooleanBareItem ¶
type BooleanBareItem bool
BooleanBareItem is a bare item that represents a boolean value. Bare items cannot have parameters. Some constructs may require a bare item instead of a full boolean item (e.g. dictionary values).
BooleanBareItem uses immutable static objects - use True() and False() to get the singleton instances.
func BareBoolean ¶
func BareBoolean(b bool) BooleanBareItem
BareBoolean creates a BooleanBareItem with the given bool value. This function returns the appropriate static singleton object (True() or False()).
If you need a full boolean item (with parameters), use Boolean() instead.
func False ¶
func False() BooleanBareItem
False returns the static singleton BooleanBareItem representing false.
func True ¶
func True() BooleanBareItem
True returns the static singleton BooleanBareItem representing true.
func (BooleanBareItem) GetValue ¶
func (b BooleanBareItem) GetValue(dst any) error
GetValue retrieves the bool value from the BooleanBareItem.
func (BooleanBareItem) MarshalSFV ¶
func (b BooleanBareItem) MarshalSFV() ([]byte, error)
func (BooleanBareItem) SetValue ¶
func (b BooleanBareItem) SetValue(value bool) BooleanBareItem
SetValue returns the appropriate static singleton object for the given bool value.
func (BooleanBareItem) ToItem ¶
func (b BooleanBareItem) ToItem() Item
ToItem converts the BooleanBareItem to a full Item.
func (BooleanBareItem) Type ¶
func (b BooleanBareItem) Type() int
Type returns the type of the BooleanBareItem, useful when you have a list of BareItems and need to know the type of each item.
type BooleanItem ¶
type BooleanItem = FullItem[BooleanBareItem, bool]
BooleanItem represents a boolean value, with optional parameters.
BooleanItem implements the Item interface.
func Boolean ¶
func Boolean(b bool) *BooleanItem
Boolean creates a new Boolean (BooleanItem) with the given bool value. This function uses the static True()/False() singleton objects internally.
If you need a bare boolean item, use BareBoolean() instead.
type ByteSequenceBareItem ¶
type ByteSequenceBareItem struct {
// contains filtered or unexported fields
}
ByteSequenceBareItem is a bare item that represents a base64-encoded byte sequence. Bare items cannot have parameters. Some constructs may require a bare item instead of a full byte sequence item (e.g. dictionary values).
func BareByteSequence ¶
func BareByteSequence(b []byte) *ByteSequenceBareItem
BareByteSequence creates a new ByteSequenceBareItem with the given byte slice. This function does NOT validate the bytes to ensure they form a valid byte sequence (Validation only happens when the item is marshaled/parsed).
If you need a full byte sequence item (with parameters), use ByteSequence() instead.
func (ByteSequenceBareItem) MarshalSFV ¶
func (b ByteSequenceBareItem) MarshalSFV() ([]byte, error)
MarshalSFV implements the Marshaler interface for ByteSequenceBareItem.
func (*ByteSequenceBareItem) ToItem ¶
func (b *ByteSequenceBareItem) ToItem() Item
ToItem converts the ByteSequenceBareItem to a full Item.
func (ByteSequenceBareItem) Type ¶
func (b ByteSequenceBareItem) Type() int
Type returns the type of the ByteSequenceBareItem, useful when you have a list of BareItems and need to know the type of each item.
type ByteSequenceItem ¶
type ByteSequenceItem = FullItem[*ByteSequenceBareItem, []byte]
ByteSequenceItem represents a base64-encoded byte sequence value, with optional parameters.
ByteSequenceItem implements the Item interface.
func ByteSequence ¶
func ByteSequence(b []byte) *ByteSequenceItem
ByteSequence creates a new ByteSequence (ByteSequenceItem) with the given byte slice. This function does NOT validate the bytes to ensure they form a valid byte sequence (Validation only happens when the item is marshaled/parsed).
If you need a bare byte sequence item, use BareByteSequence() instead.
type CoreItem ¶
type CoreItem interface {
Marshaler
Type() int
// GetValue is a method that assigns the underlying value of the item to dst.
// It is used to retrieve the value without needing to know the type, or
// without having to go through type conversion.
//
// If you already know the type of the value, you could use the Value() method
// instead, which returns the value directly.
GetValue(dst any) error
}
CoreItem represents the core API that is shared by both Item and BareItem.
type DateBareItem ¶
type DateBareItem struct {
// contains filtered or unexported fields
}
DateBareItem is a bare item that represents a Unix timestamp date. Bare items cannot have parameters. Some constructs may require a bare item instead of a full date item (e.g. dictionary values).
func BareDate ¶
func BareDate(timestamp int64) *DateBareItem
BareDate creates a new DateBareItem with the given Unix timestamp. This function does NOT validate the timestamp to ensure it is a valid date (Validation only happens when the item is marshaled/parsed).
If you need a full date item (with parameters), use Date() instead.
func (DateBareItem) MarshalSFV ¶
func (d DateBareItem) MarshalSFV() ([]byte, error)
MarshalSFV implements the Marshaler interface for DateBareItem.
func (*DateBareItem) ToItem ¶
func (d *DateBareItem) ToItem() Item
ToItem converts the DateBareItem to a full Item.
func (DateBareItem) Type ¶
func (d DateBareItem) Type() int
Type returns the type of the DateBareItem, useful when you have a list of BareItems and need to know the type of each item.
type DateItem ¶
type DateItem = FullItem[*DateBareItem, int64]
DateItem represents a Unix timestamp date value, with optional parameters.
DateItem implements the Item interface.
type DecimalBareItem ¶
type DecimalBareItem struct {
// contains filtered or unexported fields
}
DecimalBareItem is a bare item that represents a decimal value. Bare items cannot have parameters. Some constructs may require a bare item instead of a full decimal item (e.g. dictionary values).
func BareDecimal ¶
func BareDecimal(f float64) *DecimalBareItem
BareDecimal creates a new DecimalBareItem with the given float64 value. This function does NOT validate the value to ensure it is a valid decimal (Validation only happens when the item is marshaled/parsed).
If you need a full decimal item (with parameters), use Decimal() instead.
func (DecimalBareItem) MarshalSFV ¶
func (d DecimalBareItem) MarshalSFV() ([]byte, error)
MarshalSFV implements the Marshaler interface for DecimalBareItem.
func (*DecimalBareItem) ToItem ¶
func (d *DecimalBareItem) ToItem() Item
ToItem converts the DecimalBareItem to a full Item.
func (DecimalBareItem) Type ¶
func (d DecimalBareItem) Type() int
Type returns the type of the DecimalBareItem, useful when you have a list of BareItems and need to know the type of each item.
type DecimalItem ¶
type DecimalItem = FullItem[*DecimalBareItem, float64]
DecimalItem represents a decimal value, with optional parameters.
DecimalItem implements the Item interface.
func Decimal ¶
func Decimal(f float64) *DecimalItem
Decimal creates a new Decimal (DecimalItem) with the given float64 value. This function does NOT validate the value to ensure it is a valid decimal (Validation only happens when the item is marshaled/parsed).
If you need a bare decimal item, use BareDecimal() instead.
type Dictionary ¶
type Dictionary struct {
// contains filtered or unexported fields
}
Dictionary represents an ordered map of string keys to values in the SFV format. Values can be Items, BareItems, or InnerLists. Dictionary maintains insertion order and serializes as semicolon-separated key=value pairs according to RFC 9651.
func NewDictionary ¶
func NewDictionary() *Dictionary
NewDictionary creates a new empty Dictionary. A Dictionary represents a Structured Field Dictionary, which is an ordered map of string keys to values (Items, BareItems, or InnerLists).
func ParseDictionary ¶
func ParseDictionary(data []byte) (*Dictionary, error)
func (*Dictionary) GetValue ¶
func (d *Dictionary) GetValue(key string, dst any) error
GetValue retrieves the value associated with the given key and assigns it to dst. Returns an error if the key is not found or if assignment fails.
func (*Dictionary) Keys ¶
func (d *Dictionary) Keys() []string
Keys returns the ordered list of keys in the dictionary
func (*Dictionary) MarshalSFV ¶
func (d *Dictionary) MarshalSFV() ([]byte, error)
MarshalSFV implements the Marshaler interface for Dictionary
type DisplayStringBareItem ¶
type DisplayStringBareItem struct {
// contains filtered or unexported fields
}
DisplayStringBareItem is a bare item that represents a percent-encoded display string. Bare items cannot have parameters. Some constructs may require a bare item instead of a full display string item (e.g. dictionary values).
func BareDisplayString ¶
func BareDisplayString(s string) *DisplayStringBareItem
BareDisplayString creates a new DisplayStringBareItem with the given string. This function does NOT validate the string to ensure it is a valid display string (Validation only happens when the item is marshaled/parsed).
If you need a full display string item (with parameters), use DisplayString() instead.
func (DisplayStringBareItem) MarshalSFV ¶
func (d DisplayStringBareItem) MarshalSFV() ([]byte, error)
MarshalSFV implements the Marshaler interface for DisplayStringBareItem.
func (*DisplayStringBareItem) ToItem ¶
func (d *DisplayStringBareItem) ToItem() Item
ToItem converts the DisplayStringBareItem to a full Item.
func (DisplayStringBareItem) Type ¶
func (d DisplayStringBareItem) Type() int
Type returns the type of the DisplayStringBareItem, useful when you have a list of BareItems and need to know the type of each item.
type DisplayStringItem ¶
type DisplayStringItem = FullItem[*DisplayStringBareItem, string]
DisplayStringItem represents a percent-encoded display string value, with optional parameters.
DisplayStringItem implements the Item interface.
func DisplayString ¶
func DisplayString(s string) *DisplayStringItem
DisplayString creates a new DisplayString (DisplayStringItem) with the given string. This function does NOT validate the string to ensure it is a valid display string (Validation only happens when the item is marshaled/parsed).
If you need a bare display string item, use BareDisplayString() instead.
type Encoder ¶
type Encoder struct {
// contains filtered or unexported fields
}
Encoder provides configurable encoding of SFV (Structured Field Value) data. It allows customization of formatting options like parameter spacing to support different specifications (standard SFV vs HTTP Message Signature format).
func NewEncoder ¶
NewEncoder creates a new Encoder with default settings for encoding Structured Field Values. The default format uses standard SFV spacing with spaces after semicolons in parameters.
func (*Encoder) SetParameterSpacing ¶
SetParameterSpacing sets the spacing used after semicolons in parameters. Use " " for standard SFV formatting, "" for HTTP Message Signature formatting.
type FullItem ¶
FullItem is a generic container that combines a BareItem with Parameters to create a complete SFV Item. It serves as the base implementation for all typed item aliases (StringItem, IntegerItem, etc.) in the SFV format.
func (*FullItem[BT, UT]) MarshalSFV ¶
func (*FullItem[BT, UT]) Parameters ¶
func (fi *FullItem[BT, UT]) Parameters() *Parameters
func (*FullItem[BT, UT]) With ¶
func (fi *FullItem[BT, UT]) With(params *Parameters) Item
type InnerList ¶
type InnerList struct {
// contains filtered or unexported fields
}
InnerList represents a grouped sequence of Items with optional parameters in the SFV format. InnerLists are used within Lists and Dictionaries to group related items together as a single value.
func NewInnerList ¶
func NewInnerList() *InnerList
NewInnerList creates a new empty InnerList with properly initialized parameters. An InnerList represents a grouped sequence of Items with optional parameters in the SFV format.
func (*InnerList) Add ¶
Add adds an item to the inner list. The item must be an Item or BareItem. BareItems are automatically converted to Items. Returns an error if the item type is not supported.
func (*InnerList) MarshalSFV ¶
MarshalSFV implements the Marshaler interface for InnerList
func (*InnerList) Parameters ¶
func (il *InnerList) Parameters() *Parameters
Parameters returns the parameters associated with this InnerList
type IntegerBareItem ¶
type IntegerBareItem struct {
// contains filtered or unexported fields
}
IntegerBareItem is a bare item that represents an integer value. Bare items cannot have parameters. Some constructs may require a bare item instead of a full integer item (e.g. dictionary values).
func BareInteger ¶
func BareInteger(i int64) *IntegerBareItem
BareInteger creates a new IntegerBareItem with the given int64 value. This function does NOT validate the value to ensure it is a valid integer (Validation only happens when the item is marshaled/parsed).
If you need a full integer item (with parameters), use Integer() instead.
func (IntegerBareItem) MarshalSFV ¶
func (i IntegerBareItem) MarshalSFV() ([]byte, error)
MarshalSFV implements the Marshaler interface for IntegerBareItem.
func (*IntegerBareItem) ToItem ¶
func (i *IntegerBareItem) ToItem() Item
ToItem converts the IntegerBareItem to a full Item.
func (IntegerBareItem) Type ¶
func (i IntegerBareItem) Type() int
Type returns the type of the IntegerBareItem, useful when you have a list of BareItems and need to know the type of each item.
type IntegerItem ¶
type IntegerItem = FullItem[*IntegerBareItem, int64]
IntegerItem represents an integer value, with optional parameters.
IntegerItem implements the Item interface.
func Integer ¶
func Integer(i int64) *IntegerItem
Integer creates a new Integer (IntegerItem) with the given int64 value. This function does NOT validate the value to ensure it is a valid integer (Validation only happens when the item is marshaled/parsed).
If you need a bare integer item, use BareInteger() instead.
type Item ¶
type Item interface {
CoreItem
With(*Parameters) Item
Parameters() *Parameters
}
Item represents a single item in the SFV (Structured Field Value) format. It is essentially a bare item with parameters
type List ¶
type List struct {
// contains filtered or unexported fields
}
List represents an ordered sequence of Items and InnerLists in the SFV format. Lists can contain Items (with optional parameters) and InnerLists as comma-separated values according to RFC 9651.
func (*List) Add ¶
Add adds an item to the list. The item must be an Item, BareItem, or *InnerList. BareItems are automatically converted to Items. Returns an error if the item type is not supported.
func (List) MarshalSFV ¶
MarshalSFV implements the Marshaler interface for List
type Marshaler ¶
Marshaler is the interface implemented by types that can marshal themselves into valid SFV (Structured Field Value) format. Types implementing this interface can be directly encoded using Marshal() or Encoder.Encode().
type Parameters ¶
type Parameters struct {
// Values are a map of parameters to their values, where values are
// bare items
Values map[string]BareItem
// contains filtered or unexported fields
}
func NewParameters ¶
func NewParameters() *Parameters
NewParameters creates a new empty Parameters object. Parameters represent the optional parameters that can be attached to Items and InnerLists in Structured Field Values.
func (*Parameters) Get ¶
func (p *Parameters) Get(key string, dst any) error
Get retrieves the value of a parameter by key and assigns it to dst. Returns an error if the parameter is not found or if assignment fails.
func (*Parameters) Keys ¶
func (p *Parameters) Keys() []string
Keys returns a copy of the parameter keys in the order they were added. The returned slice is safe to modify without affecting the original Parameters.
func (*Parameters) Len ¶
func (p *Parameters) Len() int
Len returns the number of parameters in the Parameters object. Returns 0 if the Parameters object is nil.
func (*Parameters) MarshalSFV ¶
func (p *Parameters) MarshalSFV() ([]byte, error)
MarshalSFV implements the Marshaler interface for Parameters. It encodes the parameters in the SFV format as semicolon-separated key-value pairs with proper spacing.
type StringBareItem ¶
type StringBareItem struct {
// contains filtered or unexported fields
}
StringBareItem is a bare item that represents a quoted string. Bare items cannot have parameters. Some constructs may require a bare item instead of a full string item (e.g. dictionary values).
func BareString ¶
func BareString(s string) *StringBareItem
BareString creates a new StringBareItem with the given string. This function does NOT validate the string to ensure it is a valid quoted string (Validation only happens when the item is marshaled/parsed).
If you need a full string item (with parameters), use String() instead.
func (StringBareItem) MarshalSFV ¶
func (s StringBareItem) MarshalSFV() ([]byte, error)
MarshalSFV implements the Marshaler interface for StringBareItem.
func (*StringBareItem) ToItem ¶
func (s *StringBareItem) ToItem() Item
ToItem converts the StringBareItem to a full Item.
func (StringBareItem) Type ¶
func (s StringBareItem) Type() int
Type returns the type of the StringBareItem, useful when you have a list of BareItems and need to know the type of each item.
type StringItem ¶
type StringItem = FullItem[*StringBareItem, string]
StringItem represents a quoted string value, with optional parameters.
StringItem implements the Item interface.
func String ¶
func String(s string) *StringItem
String creates a new String (StringItem) with the given string. This function does NOT validate the string to ensure it is a valid quoted string (Validation only happens when the item is marshaled/parsed).
If you need a bare string item, use BareString() instead.
type TokenBareItem ¶
type TokenBareItem struct {
// contains filtered or unexported fields
}
TokenBareItem is a bare item that represents a token. Bare items cannot have parameters. Some constructs may require a bare item instead of a full token item (e.g. dictionary values).
func BareToken ¶
func BareToken(s string) *TokenBareItem
BareToken creates a new TokenBareItem with the given string. This function does NOT validate the string to ensure it is a valid token (Validation only happens when the item is marshaled/parsed).
If you need a full token item (with parameters), use Token() instead.
func (TokenBareItem) MarshalSFV ¶
func (t TokenBareItem) MarshalSFV() ([]byte, error)
MarshalSFV implements the Marshaler interface for TokenBareItem.
func (*TokenBareItem) ToItem ¶
func (t *TokenBareItem) ToItem() Item
ToItem converts the TokenBareItem to a full Item.
func (TokenBareItem) Type ¶
func (t TokenBareItem) Type() int
Type returns the type of the TokenBareItem, useful when you have a list of BareItems and need to know the type of each item.
type TokenItem ¶
type TokenItem = FullItem[*TokenBareItem, string]
TokenItem represents a token, an unquoted string value, with optional parameters.
TokenItem implements the Item interface.
type Value ¶
type Value interface {
Marshaler
}
Value is the top-level interface for all SFV (Structured Field Value) types. It represents any value that can be marshaled according to the SFV specification. This includes Items, Lists, Dictionaries, and any custom types that implement the Marshaler interface.
Source Files
Directories