Struct TraceEvent 

pub struct TraceEvent {
    pub seq: u64,
    pub timestamp: i64,
    pub peer: Option<String>,
    pub data: EventData,
    pub extra: Vec<(Value, Value)>,
}

A single event in a .moqtrace file.

Fields

seq: u64

Monotonically increasing sequence number (0-based). Segment-local in a segmented trace, so ordering across segments is (segment, seq).

timestamp: i64

Timestamp in microseconds since the containing segment’s start time.

peer: Option<String>

Which peer this event pertains to.

Required when the trace’s perspective is RelayTap, where a single trace covers many concurrent sessions; omitted otherwise, since a single-session trace has only one peer to speak of. The identifier is source-local: the same string in two traces from different sources does not name the same peer.

data: EventData

Event-specific data.

extra: Vec<(Value, Value)>

Keys on this event that this version of the crate could not use, kept verbatim.

Optional keys may be added to an existing event type without a format version bump, so “unknown keys MUST be ignored” is a rule about reading past them. It is not a licence to drop them: a tool that reads a trace and writes it back — a redaction pass, a filter, a re-segmentation — would otherwise emit a valid file that looks like it never carried them, and one tool’s ignorance would become permanent for every reader downstream of it.

A key this crate does know lands here too when its value is not of a type that key can hold — "ta": "hello" on an event 1, say. SPEC.md treats such a key as unrecognised: the value is ignored for meaning, the field that would have held it reads None, and the entry is written back unchanged. Knowing more about a key must not mean preserving it less.

EventData::Unknown already does this for an event type the crate cannot name. This is the same guarantee one level down, for a key on a type it can.

Unchanged binds the value and not its encoding, exactly as it does for TraceHeader::extra: on the way out an integral float in a stored value is written as a CBOR integer and a byte string under RFC 8746’s tag 64 as major type 2, at any depth. SPEC.md’s two encoding rules are about every byte a writer emits rather than only the keys it understood, and the JavaScript implementation’s decoder folds both shapes away before its own code runs, so it could not emit either however hard it tried. Nothing a comparison of the two values can see changes, with the single exception SPEC.md names: -0.0 written as 0 loses its sign.

A CBOR map may not carry one key twice, and this list can: it is an ordered list of pairs, not a map. So on the way out an entry naming a key the event writes from a field is dropped, and of two entries sharing a key the first is written — as it is for a map nested inside a stored value, which is a map this crate emits too.

The same two passes govern the other opaque values an event carries: a control message’s "msg", an annotation’s "data" and an EventData::Unknown’s fields.

Empty for every event this crate constructs itself.

Implementations

impl TraceEvent

pub fn new(seq: u64, timestamp: i64, data: EventData) -> Self

An event with no peer identifier — the single-session case.

pub fn for_peer( seq: u64, timestamp: i64, peer: impl Into<String>, data: EventData, ) -> Self

An event attributed to peer — the relay-tap case.

pub fn with_extra(self, extra: Vec<(Value, Value)>) -> Self

Attach unrecognised keys, for a caller reconstructing an event it did not decode itself.

Keys that collide with ones the event writes from its own fields are dropped on serialization rather than written twice, since a CBOR map with a repeated key is malformed and the event’s own value is the one the reader would have produced. A key the event’s type merely defines does not collide: an optional field holding None writes nothing, so the entry here is the only copy of that key and is written.

pub fn event_type(&self) -> u64

The event type discriminant this event serializes as.

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

Extract the request_id from a control message’s decoded "msg" field, if present.

Returns None for non-control-message events, for a "msg" that is not a map, and for a map that names the field something else. Drafts 07 through 10 call it subscribe_id, and this does not answer for them: the two names sit on different messages with different meanings, and a reader that wants either can ask the map itself.

The key is request_id, in the snake_case the drafts use, because that is what every writer of these files produces. It read requestId until draft-20, and matched nothing — not this crate’s own corpus, and not a trace written by any other implementation.

pub fn message_type(&self) -> Option<u64>

Return the message type for control message events.

pub fn direction(&self) -> Option<Direction>

Return the direction for events that have one.

Trait Implementations

impl Clone for TraceEvent

fn clone(&self) -> TraceEvent

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl Debug for TraceEvent

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

Formats the value using the given formatter.

impl From<&TraceEvent> for Value

Build a CBOR Value from a TraceEvent by running it through the crate’s Serialize impl. Convenience for tests and inspection — the hot write path in MoqTraceWriter uses Serialize directly and never materializes a Value.

fn from(event: &TraceEvent) -> Self

Converts to this type from the input type.

impl PartialEq for TraceEvent

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

Equality operator ==.

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

Inequality operator !=.

impl Serialize for TraceEvent

fn serialize<S: Serializer>(&self, ser: S) -> Result<S::Ok, S::Error>

Serialize this value into the given Serde serializer.

impl StructuralPartialEq for TraceEvent

impl TryFrom<Value> for TraceEvent

type Error = MoqTraceError

The type returned in the event of a conversion error.

fn try_from(value: Value) -> Result<Self, MoqTraceError>

Performs the conversion.