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
Enable json for bounded JSON-slice decoding and buffered encoding; JSON APIs for schemas and filters also require their respective features
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);

Comparison predicates in the filter feature use three-valued logic: a missing or unset value is unknown, remains unknown through negation, and does not match at the public API boundary. Existence predicates are an exception: exists and not_exists always return definite Booleans, and exists(...).not() is true when no concrete value is stored.

§Bounded JSON

Enable the json feature to use the bounded JSON helpers. The default helpers use the crate’s default decode or encode budget profile; use the corresponding _with_limits helper to configure a profile for that operation. Add features = ["json"] to the crate dependency. Decode and encode budgets are independent.

use qubit_metadata::Metadata;

let metadata = Metadata::new().with("tenant_id", "acme");
let encoded = metadata.to_json_vec()?;
let decoded = Metadata::decode_json_slice(&encoded)?;
assert_eq!(decoded.get_ref::<str>("tenant_id")?, "acme");

For complete untrusted JSON input, use the bounded slice decoder. Ordinary Serde paths still check the domain wire contract, but do not automatically provide the dedicated helper’s complete-input byte admission and unified JSON traversal budget. See the bounded JSON decoding guide and bounded JSON encoding guide for configuration and writer behavior. Writer helpers buffer the complete document; a destination I/O error may leave a written prefix.

use qubit_metadata::FilterExpression;
use qubit_metadata::Metadata;
use qubit_metadata::MetadataFilter;

let metadata = Metadata::new();
let comparison = MetadataFilter::builder()
    .expression(FilterExpression::builder().eq("tenant", "acme").not().build()?)
    .build()?;
let absent = MetadataFilter::builder()
    .expression(FilterExpression::builder().not_exists("tenant").build()?)
    .build()?;
let negated_exists = MetadataFilter::builder()
    .expression(FilterExpression::builder().exists("tenant").not().build()?)
    .build()?;
assert!(!comparison.matches(&metadata));
assert!(absent.matches(&metadata));
assert!(negated_exists.matches(&metadata));

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 number of bytes in a complete metadata JSON document.
DEFAULT_MAX_KEY_BYTES: Default maximum UTF-8 byte length of one metadata or schema key.
DEFAULT_MAX_METADATA_ENTRIES: Default maximum number of entries accepted in a metadata map.
DEFAULT_MAX_SCHEMA_FIELDS: Default maximum number of fields accepted in a metadata schema.

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: Reports the outcome of schema validation that may collect multiple issues.