Starry

Starry is a Ruby library for HTTP Structured Field Values (RFC 8941).

Install

Add the following line to your Gemfile:

gem "starry"

Or just gem install starry.

Basic Usage

Parsing

Use an appropriate one of Starry.parse_list, Starry.parse_dictionary, or Starry.parse_item.

require 'starry'

# Basic case: Proxy-Status field (RFC 9209)
Starry.parse_list('r34.example.net; error=http_request_error, ExampleCDN')
# =>
# [#<Starry::Item:0x0000000105a82658
#   @parameters={"error"=>:http_request_error},
#   @value=:"r34.example.net">,
#  #<Starry::Item:0x0000000105a81cd0 @parameters={}, @value=:ExampleCDN>]

# Retrieving bare value of item
Starry.parse_list('r34.example.net; error=http_request_error, ExampleCDN')[1].value
# => :ExampleCDN

# Retrieving parameters hash of item
Starry.parse_list('r34.example.net; error=http_request_error, ExampleCDN')[0].parameters
# => {"error"=>:http_request_error}

# Using `symbolize_names` option
Starry.parse_list('r34.example.net; error=http_request_error, ExampleCDN', symbolize_names: true)[0].parameters
# => {:error=>:http_request_error}

# More complex case: Signature-Input field (draft-ietf-httpbis-message-signatures)
Starry.parse_dictionary(
  'sig1=("@method" "@authority" "@path" "content-digest" "content-type" ' \
  '"content-length");created=1618884475;keyid="test-key-ecc-p256", ' \
  'proxy_sig=("@method" "@authority" "@path" "content-digest" "content-type" ' \
  '"content-length" "forwarded");created=1618884480;keyid="test-key-rsa";' \
  'alg="rsa-v1_5-sha256";expires=1618884540'
)
# =>
# {"sig1"=>
#   #<Starry::InnerList:0x0000000107dc8c70
#    @parameters={"created"=>1618884475, "keyid"=>"test-key-ecc-p256"},
#    @value=
#     [#<Starry::Item:0x0000000107dcab88 @parameters={}, @value="@method">,
#      ...,
#      #<Starry::Item:0x0000000107dc9648
#       @parameters={},
#       @value="content-length">]>,
#  "proxy_sig"=>
#   #<Starry::InnerList:0x0000000107dc5a98
#    @parameters=
#     {"created"=>1618884480,
#      "keyid"=>"test-key-rsa",
#      "alg"=>"rsa-v1_5-sha256",
#      "expires"=>1618884540},
#    @value=
#     [#<Starry::Item:0x0000000107dc8450 @parameters={}, @value="@method">,
#      ...,
#      #<Starry::Item:0x0000000107dc6b00 @parameters={}, @value="forwarded">]>}

Serializing

Use Starry.serialize. This single method is used for all three types: List, Dictionary, and Item.

If an Item or an Inner List has parameters, create a new Starry::Item or Starry::InnerList class object and use it. Their constructor takes a value as its first argument and a parameters hash as its second argument. Keys of the parameters hash can be either strings or symbols. Note that non-parameterized values can be contained without such a wrapping object.

require 'starry'

Starry.serialize([
  Starry::Item.new(:'r34.example.net', { 'error' => :http_request_error }),
  :ExampleCDN
])
# => "r34.example.net;error=http_request_error, ExampleCDN"

Starry.serialize({
  'sig-b22' => Starry::InnerList.new(
    ['@authority', 'content-digest', Starry::Item.new('@query-param', { name: 'Pet' })],
    { created: 1618884473, keyid: 'test-key-rsa-pss', tag: 'header-example' }
  )
})
# => "sig-b22=(\"@authority\" \"content-digest\" \"@query-param\";name=\"Pet\");created=1618884473;keyid=\"test-key-rsa-pss\";tag=\"header-example\""

Further Topics

Type mappings

The Structured Field Values specification defines several data types. Here we describe which Ruby class is used for each of them in this library.

For Lists, Array is used.
For Inner Lists, Starry::InnerList is used.
- If it is not parameterized, Array may also be used when serializing.
For parameters, Hash is used.
- Keys can be either String or Symbol. When parsing, the symbolize_names option indicates which is to be used.
- When serializing, be aware of the syntax; see the RFC for details.
For Dictionaries, Hash is used.
For Items, Starry::Item is used.
- When serializing, Starry::Item is not necessarily needed if the value is not parameterized. See the description and examples above.
For Integer values, Integer is used.
- Note that its absolute value is limited to less than 10**15.
For Decimal values, Float is used.
- Note that its absolute value is limited to less than 10**12. Also, it is rounded to three decimal places when serialized.
For String values, String with encoding other than ASCII_8BIT is used.
- Note that only ASCII printable characters are allowed.
For Token values, Symbol is used.
- Be aware of the syntax when serializing; see the RFC for details.
For Byte Sequence (binary) values, String with encoding ASCII_8BIT is used.
For Boolean values, true and false are used.

Pattern matching

Starry::Item and Starry::InnerList support pattern matching.

require 'starry'

# `Starry::Item` can be matched with hash pattern using `value` and `parameters` keys.
case Starry.parse_item('r34.example.net; error=http_request_error')
in value:, parameters:
  "v: #{ value }, p: #{ parameters }"
else
  raise "not matched"
end
# => "v: r34.example.net, p: {\"error\"=>:http_request_error}"

# The same applies to `Starry::InnerList`.
inner_list = Starry.parse_dictionary(
  'sig-b25=("date" "@authority" "content-type");created=1618884473;' \
  'keyid="test-shared-secret"'
)['sig-b25']
case inner_list
in value:, parameters:
  "v: #{ value.map(&:value) }, p: #{ parameters }"
else
  raise "not matched"
end
# => "v: [\"date\", \"@authority\", \"content-type\"], p: {\"created\"=>1618884473, \"keyid\"=>\"test-shared-secret\"}"

# `Starry::InnerList` can be also matched with array pattern.
# Note that parameters cannot be available for matching in array pattern.
case inner_list
in first, second, *rest
  "first: #{ first.value }, second: #{ second.value }, rest: #{ rest.map(&:value) }"
else
  raise "not matched"
end
# => "first: date, second: @authority, rest: [\"content-type\"]"

starry

Runtime