Oakrey.Capsule.Metadata 2.0.2

Oakrey.Capsule.Metadata

Project overview

Oakrey.Capsule.Metadata is a .NET 10 class library that encodes structured key-value metadata into the Oakrey Capsule binary framing protocol (capsule ID 0xFFFF). Each record carries a string key, a typed value, a DataType discriminator, and an optional Unit. Up to 255 records can be batched in a single MetaCapsule. The library targets IoT, telemetry, and data-logging scenarios where device or session metadata must be transmitted compactly alongside measurement data.

Main features

• MetaCapsule (capsule ID 0xFFFF) � batches up to 255 IMetaData records into a single serializable capsule. Supports full serialize / deserialize round-trip via CapsuleBase.
• MetaData<T> � abstract generic base that stores a Key, a Value, a DataType, and a Unit. Handles common binary header writing shared by all concrete types.
• StringMetaData � concrete implementation for UTF-8 string values. String value is limited to 255 characters.
• IMetaData � extension point for adding custom record types; only WriteTo(BinaryWriter) must be implemented.
• MetaDataFactory � deserializes binary payloads back into IMetaData instances based on the DataType discriminator.
• DataType / Unit enumerations � typed discriminators for record values and units of measurement.
• Static GetRequestPayload() helper for generating empty-capsule query frames.

Architecture

classDiagram
    class CapsuleBase {
        +Serialize() byte[]
        +Head : CapsuleHead
    }

    class MetaCapsule {
        +Id : ushort = 0xFFFF
        +Records : IList~IMetaData~
        +GetRequestPayload() byte[]$
    }

    class IMetaData {
        <<interface>>
        +Key : string
        +WriteTo(BinaryWriter)
    }

    class MetaDataT {
        <<abstract>>
        +Key : string
        +Value : T
        +Unit : Unit
        +MetaType : DataType
    }

    class StringMetaData {
        +MetaType = DataType.String
        +Value : string
    }

    class MetaDataFactory {
        +FromPayload(payload, out totalSize) IMetaData$
    }

    CapsuleBase <|-- MetaCapsule
    MetaCapsule "1" --> "*" IMetaData
    IMetaData <|.. MetaDataT
    MetaDataT <|-- StringMetaData
    StringMetaData ..|> IMetaData
    MetaDataFactory ..> IMetaData : creates

Record binary layout

Each record in the capsule payload has this header, followed by the UTF-8 key bytes and then the value bytes:

Enumerations

Requirements

• .NET 10 or higher
• Oakrey.Collections 2.0.0
• Oakrey.Guards 3.0.0
• Oakrey.Capsule 2.x

Build instructions

dotnet build Capsule.Metadata/Capsule.Metadata.csproj

To produce a NuGet package:

dotnet pack Capsule.Metadata/Capsule.Metadata.csproj -c Release

Installation

.NET CLI

dotnet add package Oakrey.Capsule.Metadata

Package Manager Console

Install-Package Oakrey.Capsule.Metadata

NuGet Package Manager

Search for Oakrey.Capsule.Metadata in Tools > NuGet Package Manager > Manage NuGet Packages for Solution.

Example usage

Serialize a single string metadata record

using Oakrey.Capsule.Metadata;

StringMetaData record = new("device.firmware", "2.0.0", Unit.None);
MetaCapsule capsule = new(record, hwId: 1);
byte[] frame = capsule.Serialize();

Serialize multiple records

IMetaData[] records =
[
    new StringMetaData("device.serial", "SN-0042", Unit.None),
    new StringMetaData("session.id",    "abc123",  Unit.None),
];

MetaCapsule capsule = new(records, hwId: 1);
byte[] frame = capsule.Serialize();

Deserialize a received capsule

byte[] received = ReceiveFrame();
MetaCapsule capsule = new(received);

foreach (IMetaData record in capsule.Records)
{
    Console.WriteLine(record); // Key[DataType]: Value Unit
}

Request metadata from a device

byte[] requestFrame = MetaCapsule.GetRequestPayload();
// send requestFrame over transport

Implement a custom metadata type

using Oakrey.Capsule.Metadata;

public sealed class Int32MetaData(string key, int value, Unit unit)
    : MetaData<int>(key, value, unit), IMetaData
{
    public override DataType MetaType => DataType.Int;

    public void WriteTo(BinaryWriter writer)
    {
        WriteTo(writer, sizeof(int));
        writer.Write(Value);
    }
}

To deserialize custom types, extend MetaDataFactory.FromPayload with an additional case for the new DataType.

Development notes

• Factory coverage � MetaDataFactory currently deserializes only DataType.String. All other DataType values throw InvalidDataException. Add a case per type to extend support.
• String length limit � StringMetaData.WriteTo enforces a maximum value length of 255 characters; longer strings throw InvalidDataException.
• Record count limit � MetaCapsule.WritePayload enforces a maximum of 255 records per capsule; exceeding this throws InvalidDataException.
• Key validation � MetaData<T> uses Oakrey.Guards (ThrowIfEmpty) to reject null or empty keys at construction time.
• Capsule framing � all capsule types inherit from CapsuleBase and follow the Oakrey Capsule binary protocol v2.

License

MIT. Copyright Oakrey 2016-present.