rifts 0.3.4

Rift Realtime Protocol / 1.0 — server + client implementation
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118

//! # Lightweight Distributed Tracing Context (TraceContext)
//!
//! This module implements the tracing context model defined in spec section 23.1.
//!
//! The full protocol supports five fields: `trace_id`, `span_id`, `parent_span_id`,
//! `sampled`, and `baggage`. This implementation covers the minimum set required by
//! the server side (excluding `baggage`).
//!
//! ## Tracing Model
//!
//! ```text
//! RootSpan (new_root)
//!   ├── trace_id = ULID-1
//!   ├── span_id  = ULID-2
//!   ├── parent   = None
//!   └── sampled  = true
//!         │
//!         └── ChildSpan (child)
//!               ├── trace_id = ULID-1 (inherited)
//!               ├── span_id  = ULID-3
//!               ├── parent   = ULID-2
//!               └── sampled  = true (inherited)
//! ```
//!
//! Uses ULID as the ID generator, ensuring time-ordered and globally unique identifiers.
//!
//! ## Relationship with OpenTelemetry
//!
//! `TraceContext` is a protocol-layer concept, propagated only within frames.
//! In production it should be mapped to an OTLP `SpanContext` to integrate with
//! backends such as Jaeger or Zipkin.

use ulid::Ulid;

/// Tracing context attached to protocol frames.
///
/// Each [`Frame`](crate::frame::Frame) may carry an optional `TraceContext`,
/// used to propagate tracing information between client and server for
/// end-to-end distributed tracing.
///
/// # Field Descriptions
///
/// - `trace_id`: A globally unique trace chain identifier, shared across the
///   upstream and downstream of a single business operation.
/// - `span_id`: A unique identifier for the current operation.
/// - `parent_span_id`: The span ID of the parent operation, used to build the call tree.
/// - `sampled`: Whether this trace is sampled (`true` means the tracing backend
///   should record this trace chain).
#[derive(Debug, Clone, Default)]
pub struct TraceContext {
    /// Globally unique trace chain identifier (ULID string).
    ///
    /// `None` indicates that no tracing information is present.
    pub trace_id: Option<String>,

    /// Identifier for the current operation/span (ULID string).
    pub span_id: Option<String>,

    /// Span identifier of the parent operation, used to build the call tree.
    ///
    /// For root spans, this value is `None`.
    pub parent_span_id: Option<String>,

    /// Whether this trace is sampled.
    ///
    /// `true` means the tracing backend should record this trace chain;
    /// `false` means propagate only, do not record.
    /// Defaults to `true` (set in [`new_root`](TraceContext::new_root)).
    pub sampled: bool,
}

impl TraceContext {
    /// Creates a brand-new root tracing context.
    ///
    /// Generates independent `trace_id` and `span_id` with no parent span.
    /// This is the entry point for creating a tracing context when a new
    /// connection is established on the server side.
    pub fn new_root() -> Self {
        Self {
            trace_id: Some(Ulid::new().to_string()),
            span_id: Some(Ulid::new().to_string()),
            parent_span_id: None,
            sampled: true,
        }
    }

    /// Creates a child span based on the current context.
    ///
    /// The child span inherits the parent's `trace_id` and `sampled` flag.
    /// `parent_span_id` points to the current span, and a new `span_id` is generated.
    ///
    /// Used to record sub-operations during server-side processing (e.g., creating
    /// a child span when publishing a message).
    pub fn child(&self) -> Self {
        Self {
            trace_id: self.trace_id.clone(),
            span_id: Some(Ulid::new().to_string()),
            parent_span_id: self.span_id.clone(),
            sampled: self.sampled,
        }
    }
}

#[cfg(test)]
mod tests {
    use super::*;

    #[test]
    fn root_then_child() {
        let r = TraceContext::new_root();
        assert!(r.trace_id.is_some());
        assert!(r.span_id.is_some());
        let c = r.child();
        assert_eq!(c.trace_id, r.trace_id);
        assert_eq!(c.parent_span_id, r.span_id);
        assert_ne!(c.span_id, r.span_id);
    }
}