Skip to main content

Metadata

Struct Metadata 

Source
pub struct Metadata {
    pub version: u16,
    pub timestamp: HlcTimestamp,
    pub parameters: BTreeMap<ParamKey, Parameter>,
}
Expand description

The metadata accompanying one message.

Deliberately not #[non_exhaustive]: astrs-daemon, astrs-node-api and the recorder all build these with struct literals, and the field set is pinned by the blueprint.

§Examples

use astrs_wire::{Metadata, Parameter};
use astrs_time::HlcTimestamp;

let meta = Metadata::new(HlcTimestamp::new(10, 0))
    .with("seq", Parameter::Integer(3))?
    .with("fin", Parameter::Bool(true))?;
assert_eq!(meta.seq(), Some(3));
assert_eq!(meta.fin(), Some(true));
assert_eq!(meta.len(), 2);

Fields§

§version: u16

The metadata layout version — METADATA_VERSION for anything this build produces.

§timestamp: HlcTimestamp

The hybrid-logical-clock timestamp of the event this metadata describes (blueprint §4.3).

§parameters: BTreeMap<ParamKey, Parameter>

The key/value parameters, in key order.

Implementations§

Source§

impl Metadata

Source

pub fn new(timestamp: HlcTimestamp) -> Metadata

An empty metadata record stamped at timestamp.

§Examples
use astrs_wire::{METADATA_VERSION, Metadata};
use astrs_time::HlcTimestamp;

let meta = Metadata::new(HlcTimestamp::new(1, 2));
assert_eq!(meta.version, METADATA_VERSION);
assert!(meta.is_empty());
Source

pub fn with( self, key: &str, value: impl Into<Parameter>, ) -> Result<Metadata, IdError>

Builder form of Metadata::insert.

§Errors

crate::IdError if key is not a valid ParamKey.

§Examples
use astrs_wire::{Metadata, Parameter};
use astrs_time::HlcTimestamp;

let meta = Metadata::new(HlcTimestamp::EPOCH).with("k", Parameter::Bool(true))?;
assert_eq!(meta.get("k").and_then(Parameter::as_bool), Some(true));
assert!(Metadata::new(HlcTimestamp::EPOCH).with("bad key", Parameter::Bool(true)).is_err());
Source

pub fn insert( &mut self, key: &str, value: impl Into<Parameter>, ) -> Result<Option<Parameter>, IdError>

Inserts a parameter, returning the value it replaced.

§Errors

crate::IdError if key is not a valid ParamKey.

§Examples
use astrs_wire::{Metadata, Parameter};
use astrs_time::HlcTimestamp;

let mut meta = Metadata::new(HlcTimestamp::EPOCH);
assert_eq!(meta.insert("seq", Parameter::Integer(1))?, None);
assert_eq!(meta.insert("seq", Parameter::Integer(2))?, Some(Parameter::Integer(1)));
Source

pub fn insert_key( &mut self, key: ParamKey, value: impl Into<Parameter>, ) -> Option<Parameter>

Inserts a parameter under an already-validated key.

The infallible counterpart of Metadata::insert, for call sites that hold a ParamKey.

Source

pub fn get(&self, key: &str) -> Option<&Parameter>

Looks up a parameter by key.

§Examples
use astrs_wire::{Metadata, Parameter};
use astrs_time::HlcTimestamp;

let meta = Metadata::new(HlcTimestamp::EPOCH).with("a", Parameter::Integer(1))?;
assert!(meta.get("a").is_some());
assert!(meta.get("b").is_none());
Source

pub fn remove(&mut self, key: &str) -> Option<Parameter>

Removes a parameter, returning it.

Source

pub fn contains_key(&self, key: &str) -> bool

Whether a parameter with this key is present.

Source

pub fn entry(&mut self, key: ParamKey) -> Entry<'_, ParamKey, Parameter>

The entry API for the parameter map, for read-modify-write updates.

Source

pub fn len(&self) -> usize

The number of parameters.

Source

pub fn is_empty(&self) -> bool

Whether there are no parameters.

Source

pub fn iter(&self) -> Iter<'_, ParamKey, Parameter> ⓘ

Iterates the parameters in key order.

Source

pub fn keys(&self) -> Keys<'_, ParamKey, Parameter> ⓘ

Iterates the keys in order.

Source

pub fn values(&self) -> Values<'_, ParamKey, Parameter> ⓘ

Iterates the values in key order.

Source

pub fn strip_internal(&mut self) -> usize

Removes every AstRS-internal (_-prefixed) parameter in place.

Called by the node API immediately before an NodeEvent::Input is handed to user code, so application code never sees the plumbing (blueprint §6.1).

Returns the number of parameters removed.

§Examples
use astrs_wire::{Metadata, Parameter};
use astrs_time::HlcTimestamp;

let mut meta = Metadata::new(HlcTimestamp::EPOCH)
    .with("seq", Parameter::Integer(1))?
    .with("_schema_hash", Parameter::String("abc".into()))?
    .with("_trace", Parameter::String("t".into()))?;

assert_eq!(meta.strip_internal(), 2);
assert_eq!(meta.len(), 1);
assert!(meta.contains_key("seq"));
Source

pub fn stripped(&self) -> Metadata

A copy with the internal parameters removed.

§Examples
use astrs_wire::{Metadata, Parameter};
use astrs_time::HlcTimestamp;

let meta = Metadata::new(HlcTimestamp::EPOCH)
    .with("_schema_hash", Parameter::String("abc".into()))?;
assert!(meta.stripped().is_empty());
assert_eq!(meta.len(), 1, "the original is untouched");
Source

pub fn is_correlated(&self) -> bool

Whether this message is correlated — carries a request_id, goal_id or goal_status.

Blueprint §11.2: correlated messages are immune to queue eviction, because dropping a service response or a goal-status update would wedge a client forever.

§Examples
use astrs_wire::{Metadata, Parameter};
use astrs_time::HlcTimestamp;

let plain = Metadata::new(HlcTimestamp::EPOCH).with("seq", Parameter::Integer(1))?;
assert!(!plain.is_correlated());

let correlated = plain.clone().with("request_id", Parameter::String("r".into()))?;
assert!(correlated.is_correlated());
Source

pub fn is_stream_chunk(&self) -> bool

Whether this message is part of a stream (session_id present).

Source

pub fn follow(&self) -> Metadata

Derives the metadata for a message produced in response to this one.

This is the meta.follow() of the node API example in blueprint §9.1. It preserves exactly the keys that must survive a hop — the correlation keys and the stream keys — and drops everything else, including all internal plumbing, which the sender will re-stamp for its own payload. The timestamp is inherited so that causality is visible in a recording; callers with a live clock should overwrite it with a fresh reading.

§Examples
use astrs_wire::{Metadata, Parameter};
use astrs_time::HlcTimestamp;

let incoming = Metadata::new(HlcTimestamp::new(5, 0))
    .with("request_id", Parameter::String("r-1".into()))?
    .with("seq", Parameter::Integer(9))?
    .with("user_note", Parameter::String("ignored".into()))?
    .with("_schema_hash", Parameter::String("h".into()))?;

let outgoing = incoming.follow();
assert_eq!(outgoing.request_id(), Some("r-1"));
assert_eq!(outgoing.seq(), Some(9));
assert!(!outgoing.contains_key("user_note"));
assert!(!outgoing.contains_key("_schema_hash"));
assert_eq!(outgoing.timestamp, incoming.timestamp);
Source

pub fn request_id(&self) -> Option<&str>

The request_id, if present.

Source

pub fn set_request_id(&mut self, id: impl Into<String>)

Sets the request_id.

Source

pub fn goal_id(&self) -> Option<&str>

The goal_id, if present.

Source

pub fn set_goal_id(&mut self, id: impl Into<String>)

Sets the goal_id.

Source

pub fn goal_status(&self) -> Option<GoalStatus>

The goal_status, if present and recognised.

A status code this build does not know yields None; the raw integer is still readable through Metadata::get.

Source

pub fn set_goal_status(&mut self, status: GoalStatus)

Sets the goal_status.

Source

pub fn session_id(&self) -> Option<&str>

The session_id, if present.

Source

pub fn set_session_id(&mut self, id: impl Into<String>)

Sets the session_id.

Source

pub fn segment_id(&self) -> Option<i64>

The segment_id, if present.

Source

pub fn set_segment_id(&mut self, segment: i64)

Sets the segment_id.

Source

pub fn seq(&self) -> Option<i64>

The seq, if present.

Source

pub fn set_seq(&mut self, seq: i64)

Sets the seq.

Source

pub fn fin(&self) -> Option<bool>

The fin flag, if present.

Source

pub fn set_fin(&mut self, fin: bool)

Sets the fin flag.

Source

pub fn flush(&self) -> Option<bool>

The flush flag, if present.

Source

pub fn set_flush(&mut self, flush: bool)

Sets the flush flag.

Source

pub fn schema_hash(&self) -> Option<&str>

The internal _schema_hash, if present.

Source

pub fn insert_schema_hash(&mut self, hash: impl Into<String>)

Stamps the internal _schema_hash.

Set by the sending side from astrs-data’s SchemaHash so receivers can cache decoded schemas and detect type drift cheaply (§6.1).

Source

pub fn bitwise_eq(&self, other: &Metadata) -> bool

Bitwise equality, so that metadata carrying a NaN float compares equal to itself.

See Parameter::bitwise_eq.

Trait Implementations§

Source§

impl Clone for Metadata

Source§

fn clone(&self) -> Metadata

Returns a duplicate of the value. Read more
1.0.0 (const: unstable) · Source§

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source. Read more
Source§

impl Debug for Metadata

Source§

fn fmt(&self, f: &mut Formatter<'_>) -> Result<(), Error>

Formats the value using the given formatter. Read more
Source§

impl Decode for Metadata

Source§

fn decode<D>(decoder: &mut D) -> Result<Metadata, Error>
where D: Decoder<Context = ()>,

Not generic over oxicode’s decode context: the fields this reads (HlcTimestamp, Parameter) are #[derive(Decode)] types, and the derive emits context-free implementations.

Source§

impl Default for Metadata

Source§

fn default() -> Metadata

Empty metadata stamped at HlcTimestamp::EPOCH.

Source§

impl<'de> Deserialize<'de> for Metadata

Source§

fn deserialize<__D>( __deserializer: __D, ) -> Result<Metadata, <__D as Deserializer<'de>>::Error>
where __D: Deserializer<'de>,

Deserialize this value from the given Serde deserializer. Read more
Source§

impl Encode for Metadata

Source§

fn encode<E>(&self, encoder: &mut E) -> Result<(), Error>
where E: Encoder,

Encode this value into the given encoder
Source§

impl<'a> IntoIterator for &'a Metadata

Source§

type Item = (&'a ParamKey, &'a Parameter)

The type of the elements being iterated over.
Source§

type IntoIter = Iter<'a, ParamKey, Parameter>

Which kind of iterator are we turning this into?
Source§

fn into_iter(self) -> <&'a Metadata as IntoIterator>::IntoIter

Creates an iterator from a value. Read more
Source§

impl PartialEq for Metadata

Source§

fn eq(&self, other: &Metadata) -> bool

Equality operator ==. Read more
1.0.0 (const: unstable) · Source§

fn ne(&self, other: &Rhs) -> bool

Inequality operator !=. Read more
Source§

impl Serialize for Metadata

Source§

fn serialize<__S>( &self, __serializer: __S, ) -> Result<<__S as Serializer>::Ok, <__S as Serializer>::Error>
where __S: Serializer,

Serialize this value into the given Serde serializer. Read more
Source§

impl StructuralPartialEq for Metadata

Auto Trait Implementations§

Blanket Implementations§

Source§

impl<T> Allocation for T
where T: RefUnwindSafe + Send + Sync,

Source§

impl<T> Any for T
where T: 'static + ?Sized,

Source§

fn type_id(&self) -> TypeId

Gets the TypeId of self. Read more
Source§

impl<T> Borrow<T> for T
where T: ?Sized,

Source§

fn borrow(&self) -> &T

Immutably borrows from an owned value. Read more
Source§

impl<T> BorrowMut<T> for T
where T: ?Sized,

Source§

fn borrow_mut(&mut self) -> &mut T

Mutably borrows from an owned value. Read more
Source§

impl<ST, DT> CastableFrom<ST, Initialized, Initialized> for DT
where ST: ?Sized, DT: ?Sized,

Source§

impl<ST, DT> CastableFrom<ST, Uninit, Uninit> for DT
where ST: ?Sized, DT: ?Sized,

Source§

impl<T> CloneToUninit for T
where T: Clone,

Source§

unsafe fn clone_to_uninit(&self, dest: *mut u8)

🔬This is a nightly-only experimental API. (clone_to_uninit)
Performs copy-assignment from self to dest. Read more
Source§

impl<T> DeserializeOwned for T
where T: for<'de> Deserialize<'de>,

Source§

impl<T> From<T> for T

Source§

fn from(t: T) -> T

Returns the argument unchanged.

Source§

impl<T> Instrument for T

Source§

fn instrument(self, span: Span) -> Instrumented<Self> ⓘ

Instruments this type with the provided Span, returning an Instrumented wrapper. Read more
Source§

fn in_current_span(self) -> Instrumented<Self> ⓘ

Instruments this type with the current Span, returning an Instrumented wrapper. Read more
Source§

impl<T, U> Into<U> for T
where U: From<T>,

Source§

fn into(self) -> U

Calls U::from(self).

That is, this conversion is whatever the implementation of From<T> for U chooses to do.

Source§

impl<T> MaybeDebug for T

Source§

impl<T> Read<Exclusive, BecauseExclusive> for T
where T: ?Sized,

Source§

impl<T> Same for T

Source§

type Output = T

Should always be Self
Source§

impl<T> ToOwned for T
where T: Clone,

Source§

type Owned = T

The resulting type after obtaining ownership.
Source§

fn to_owned(&self) -> T

Creates owned data from borrowed data, usually by cloning. Read more
Source§

fn clone_into(&self, target: &mut T)

Uses borrowed data to replace owned data, usually by cloning. Read more
Source§

impl<T, U> TryFrom<U> for T
where U: Into<T>,

Source§

type Error = !

The type returned in the event of a conversion error.
Source§

fn try_from(value: U) -> Result<T, !>

Performs the conversion.
Source§

impl<T, U> TryInto<U> for T
where U: TryFrom<T>,

Source§

type Error = <U as TryFrom<T>>::Error

The type returned in the event of a conversion error.
Source§

fn try_into(self) -> Result<U, <U as TryFrom<T>>::Error>

Performs the conversion.
Source§

impl<V, T> VZip<V> for T
where V: MultiLane<T>,

Source§

fn vzip(self) -> V

Source§

impl<T> WireDecode for T
where T: Decode,

Source§

fn decode_exact(bytes: &[u8]) -> Result<T, WireError>

Decodes a value that must occupy all of bytes. Read more
Source§

fn decode_prefix(bytes: &[u8]) -> Result<(T, usize), WireError>

Decodes a value from the front of bytes, returning it together with the number of bytes consumed. Read more
Source§

impl<T> WireEncode for T
where T: Encode,

Source§

fn encode_size_hint(&self) -> Result<usize, WireError>

The exact number of bytes WireEncode::encode_presized will produce. Read more
Source§

fn encode_presized(&self, out: &mut Vec<u8>) -> Result<usize, WireError>

Appends the encoded form to out, reserving the exact space first. Read more
Source§

fn encode_to_vec(&self) -> Result<Vec<u8>, WireError>

Encodes into a freshly allocated, exactly-sized Vec<u8>. Read more
Source§

impl<T> WithSubscriber for T

Source§

fn with_subscriber<S>(self, subscriber: S) -> WithDispatch<Self> ⓘ
where S: Into<Dispatch>,

Attaches the provided Subscriber to this type, returning a WithDispatch wrapper. Read more
Source§

fn with_current_subscriber(self) -> WithDispatch<Self> ⓘ

Attaches the current default Subscriber to this type, returning a WithDispatch wrapper. Read more