DamianH.Http.StructuredFieldValues 0.1.0

DamianH.Http.StructuredFieldValues

RFC 8941/9651 parser, serializer, and POCO mapper for HTTP Structured Field Values.

Table of Contents

• Installation
• Quick Start
  • Parsing
  • Serializing
  • POCO Mapping
• API Reference
  • StructuredFieldParser
  • StructuredFieldSerializer
  • StructuredFieldMapper<T>
  • Item Types
  • Collection Types
  • DictionaryBuilder<T>
  • ListBuilder<T>
  • ItemBuilder<T>
• Type Mapping
• Samples

Installation

dotnet add package DamianH.Http.StructuredFieldValues

Quick Start

Parsing

using DamianH.Http.StructuredFieldValues;

// Parse a structured dictionary (e.g. Cache-Control, Priority)
StructuredFieldDictionary dict = StructuredFieldParser.ParseDictionary("u=3, i");
// dict["u"] → IntegerItem(3)
// dict["i"] → BooleanItem(true)  (bare key = ?1)

// Parse a structured list
StructuredFieldList list = StructuredFieldParser.ParseList("a, b, c");

// Parse a single item
StructuredFieldItem item = StructuredFieldParser.ParseItem("42");

Serializing

var dict = new StructuredFieldDictionary
{
    ["max-age"] = DictionaryMember.FromItem(new IntegerItem(3600)),
    ["no-cache"] = DictionaryMember.FromItem(BooleanItem.True)
};

string header = StructuredFieldSerializer.SerializeDictionary(dict);
// "max-age=3600, no-cache"

POCO Mapping

The mapper converts RFC 8941 structured values to and from plain C# objects. Mappers are thread-safe and should be stored in static readonly fields.

// Define a POCO
public class PriorityHeader
{
    public int? Urgency { get; init; }
    public bool? Incremental { get; init; }

    // Define the mapper once, store statically
    public static readonly StructuredFieldMapper<PriorityHeader> Mapper =
        StructuredFieldMapper<PriorityHeader>.Dictionary(b => b
            .Member("u", x => x.Urgency)
            .Member("i", x => x.Incremental));
}

// Parse
var priority = PriorityHeader.Mapper.Parse("u=3, i");
// priority.Urgency == 3, priority.Incremental == true

// Serialize
string header = PriorityHeader.Mapper.Serialize(new PriorityHeader { Urgency = 3, Incremental = true });
// "u=3, i"

// Try-parse (returns false for malformed input instead of throwing)
if (PriorityHeader.Mapper.TryParse(request.Headers["Priority"], out var p))
{
    // use p
}

API Reference

StructuredFieldParser

Static class for parsing RFC 8941 structured field values.

All methods throw ArgumentNullException for null input and StructuredFieldParseException for malformed input.

StructuredFieldSerializer

Static class for serializing RFC 8941 structured field values to their canonical string form.

StructuredFieldMapper<T>

A cached, reusable mapper that converts an RFC 8941 structured field value to and from a POCO of type T. T must have a public parameterless constructor.

Factory methods (choose based on the RFC 8941 field type):

Instance methods:

Item Types

All item types extend StructuredFieldItem and carry a Parameters collection.

Collection Types

DictionaryBuilder<T>

Configures mappings from an RFC 8941 Dictionary to POCO properties.

ListBuilder<T>

Configures mappings from an RFC 8941 List to a POCO.

ItemBuilder<T>

Configures mappings from an RFC 8941 Item to a POCO.

Type Mapping

The mapper infers RFC 8941 types from CLR property types:

Samples

• samples/HttpClientSample — HttpClient integration showing mapper definitions for Priority (RFC 9218) and Cache-Control headers, with helpers for reading and writing structured headers on HttpRequestMessage and HttpResponseMessage.

• samples/AspNetCoreSample — ASP.NET Core integration showing the same mapper pattern applied to HttpRequest and HttpResponse extension methods.

Note: The sample projects target .NET 10 with LangVersion=preview and use C# 14 extension declaration syntax.