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: u16The metadata layout version — METADATA_VERSION for anything this
build produces.
timestamp: HlcTimestampThe 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
impl Metadata
Sourcepub fn new(timestamp: HlcTimestamp) -> Metadata
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());Sourcepub fn with(
self,
key: &str,
value: impl Into<Parameter>,
) -> Result<Metadata, IdError>
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());Sourcepub fn insert(
&mut self,
key: &str,
value: impl Into<Parameter>,
) -> Result<Option<Parameter>, IdError>
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)));Sourcepub fn insert_key(
&mut self,
key: ParamKey,
value: impl Into<Parameter>,
) -> Option<Parameter>
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.
Sourcepub fn get(&self, key: &str) -> Option<&Parameter>
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());Sourcepub fn contains_key(&self, key: &str) -> bool
pub fn contains_key(&self, key: &str) -> bool
Whether a parameter with this key is present.
Sourcepub fn entry(&mut self, key: ParamKey) -> Entry<'_, ParamKey, Parameter>
pub fn entry(&mut self, key: ParamKey) -> Entry<'_, ParamKey, Parameter>
The entry API for the parameter map, for read-modify-write updates.
Sourcepub fn strip_internal(&mut self) -> usize
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"));Sourcepub fn stripped(&self) -> Metadata
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");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());Sourcepub fn is_stream_chunk(&self) -> bool
pub fn is_stream_chunk(&self) -> bool
Whether this message is part of a stream (session_id present).
Sourcepub fn follow(&self) -> Metadata
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);Sourcepub fn request_id(&self) -> Option<&str>
pub fn request_id(&self) -> Option<&str>
The request_id, if present.
Sourcepub fn set_request_id(&mut self, id: impl Into<String>)
pub fn set_request_id(&mut self, id: impl Into<String>)
Sets the request_id.
Sourcepub fn set_goal_id(&mut self, id: impl Into<String>)
pub fn set_goal_id(&mut self, id: impl Into<String>)
Sets the goal_id.
Sourcepub fn goal_status(&self) -> Option<GoalStatus>
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.
Sourcepub fn set_goal_status(&mut self, status: GoalStatus)
pub fn set_goal_status(&mut self, status: GoalStatus)
Sets the goal_status.
Sourcepub fn session_id(&self) -> Option<&str>
pub fn session_id(&self) -> Option<&str>
The session_id, if present.
Sourcepub fn set_session_id(&mut self, id: impl Into<String>)
pub fn set_session_id(&mut self, id: impl Into<String>)
Sets the session_id.
Sourcepub fn segment_id(&self) -> Option<i64>
pub fn segment_id(&self) -> Option<i64>
The segment_id, if present.
Sourcepub fn set_segment_id(&mut self, segment: i64)
pub fn set_segment_id(&mut self, segment: i64)
Sets the segment_id.
Sourcepub fn schema_hash(&self) -> Option<&str>
pub fn schema_hash(&self) -> Option<&str>
The internal _schema_hash, if present.
Sourcepub fn insert_schema_hash(&mut self, hash: impl Into<String>)
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).
Sourcepub fn bitwise_eq(&self, other: &Metadata) -> bool
pub fn bitwise_eq(&self, other: &Metadata) -> bool
Bitwise equality, so that metadata carrying a NaN float compares
equal to itself.
Trait Implementations§
Source§impl Default for Metadata
impl Default for Metadata
Source§fn default() -> Metadata
fn default() -> Metadata
Empty metadata stamped at HlcTimestamp::EPOCH.