Crate qubit_metadata

Expand description

§qubit-metadata

A general-purpose, typed-value, extensible metadata model for Rust.

This crate provides a Metadata type — a structured key-value store designed for any domain that needs to attach typed annotations to its data models. It is not a plain HashMap — it is a structured extensibility point with strict typed access, explicit conversion helpers, qubit_value::Value backing, and first-class serde support.

§Design Goals

Typed Values: Strict typed reads, explicit conversion helpers, chainable set, and replacement-aware insert APIs backed by qubit_value::Value
Generality: No domain-specific assumptions — usable in any Rust project
Schema Support: Optional schema validation for metadata and filters through the schema feature
Serialization: First-class serde support for JSON interchange
Filtering: Composable query conditions through the filter feature

§Features

Core type: Metadata — an ordered key-value store with typed accessors
Enable filter for composable filter expressions and their public types
Enable schema (which includes filter) for field definitions and validation APIs
Error type: MetadataError — structured failure reporting for reads, conversions, validation, and wire boundaries
schema also provides aggregate validation errors

§Example

use qubit_metadata::Metadata;

let meta = Metadata::new()
    .with("author", "alice")
    .with("priority", 3_i64);

// Optional strict reads distinguish absence from conversion/type failures.
let author = meta.get_optional::<String>("author").unwrap();
assert_eq!(author.as_deref(), Some("alice"));

// Explicit API: preserve failure reasons for diagnostics.
let priority = meta.convert::<i64>("priority").unwrap();
assert_eq!(priority, 3);

The filter feature uses fail-closed three-valued logic: a missing or unset value stays unknown through negation and does not match at the public API boundary.

Metadata’s Debug and Display implementations are bounded and rendered through the default redaction policy. They are useful diagnostic views, not a confidentiality boundary for arbitrary user-defined keys or error text.

Structs§

FilterExpression: An immutable Boolean expression in a crate::MetadataFilter.
FilterExpressionBuilder: Fluent builder for a non-empty FilterExpression.
FilterLimits: Resource bounds enforced for every constructed or deserialized filter.
FilterLimitsBuilder: Fluent builder for validated filter limits.
FilterMatchOptions: Match policies used when evaluating a crate::MetadataFilter.
FilterMatchOptionsBuilder: Fluent builder for filter match options.
Metadata: A structured, key-sorted, typed key-value store for metadata fields.
MetadataField: Definition of one metadata field in a crate::MetadataSchema.
MetadataFilter: An expression, its matching policy, and its resource limits.
MetadataFilterBuilder: Builder for the non-logical configuration of a MetadataFilter.
MetadataLimits: Domain-specific metadata limits composed with a shared JSON profile.
MetadataLimitsBuilder: Builder for MetadataLimits.
MetadataSchema: Schema for metadata fields.
MetadataSchemaBuilder: Builder for MetadataSchema.
MetadataValidationError: Aggregate error returned by schema-level validation APIs.

Enums§

Condition: A single comparison operator applied to one metadata key.
FilterExpressionView: A borrowed, read-only view of one FilterExpression node.
FilterLimitKind: Identifies one resource bounded while constructing or decoding a filter.
MetadataError: Errors produced by explicit metadata accessors and schema validation.
MetadataWireDecodeError: Failure returned by a bounded metadata JSON decoding API.
MetadataWireEncodeError: Failure returned by bounded metadata JSON encoding APIs.
MetadataWireLimitKind: A metadata resource category bounded by the strict V1 wire contract.
UnknownFilterFieldPolicy: Policy for filter fields that are not declared by a schema.
UnknownMetadataFieldPolicy: Policy for metadata fields that are not declared by a schema.

Constants§

DEFAULT_MAX_JSON_BYTES: Default maximum complete metadata JSON input or output length.
DEFAULT_MAX_KEY_BYTES: Default maximum UTF-8 bytes in one metadata key.
DEFAULT_MAX_METADATA_ENTRIES: Default maximum metadata map entries accepted by the JSON profile.
DEFAULT_MAX_SCHEMA_FIELDS: Default maximum schema fields accepted by the JSON profile.

Functions§

default_json_decode_limits: Creates the default metadata JSON decoding profile.
default_json_encode_limits: Creates the default metadata JSON encoding profile.
default_json_value_limits: Creates the default direction-independent metadata JSON value profile.

Type Aliases§

MetadataResult: Result type used by explicit Metadata operations that report failure reasons instead of collapsing them into None.
MetadataValidationResult: Result type for schema validation that may report multiple issues.