Skip to main content

hopr_utils_tracing/
lib.rs

1//! Tracing context carried across bounded queues shared by asynchronous producers.
2
3use std::{
4    pin::Pin,
5    task::{Context, Poll},
6};
7
8use futures::Sink;
9use hopr_utils::network_types::crossfire_sink::CrossfireSink;
10
11/// A value and the local span under which its asynchronous work should run.
12/// This envelope is never serialized or sent to a remote node.
13#[derive(Debug)]
14pub struct WithContext<T> {
15    /// The queued value.
16    pub value: T,
17    span: Option<Box<tracing::Span>>,
18}
19
20impl<T> WithContext<T> {
21    /// Attaches an explicit local span, independently of automatic capture.
22    ///
23    /// ```
24    /// let message = hopr_utils_tracing::WithContext::new("payload", tracing::Span::none());
25    /// let (value, span) = message.into_parts();
26    /// assert_eq!(value, "payload");
27    /// assert!(span.is_disabled());
28    /// ```
29    pub fn new(value: T, span: tracing::Span) -> Self {
30        Self {
31            value,
32            // Keep disabled messages compact and allocation-free. Active spans retain their
33            // subscriber and lifetime exactly as an inline Span would.
34            span: (!span.is_disabled()).then(|| Box::new(span)),
35        }
36    }
37
38    /// Borrows the retained span, or a disabled span when no context was captured.
39    pub fn span(&self) -> &tracing::Span {
40        static DISABLED: tracing::Span = tracing::Span::none();
41        self.span.as_deref().unwrap_or(&DISABLED)
42    }
43
44    /// Recovers the value and its owned span without cloning either.
45    pub fn into_parts(self) -> (T, tracing::Span) {
46        (self.value, self.span.map_or_else(tracing::Span::none, |span| *span))
47    }
48}
49
50impl<T> From<T> for WithContext<T> {
51    fn from(value: T) -> Self {
52        #[cfg(feature = "tracing-context")]
53        let span = tracing::Span::current();
54        #[cfg(not(feature = "tracing-context"))]
55        let span = tracing::Span::none();
56        Self::new(value, span)
57    }
58}
59
60/// Restores message context while sending values and completing downstream I/O.
61/// Readiness uses the caller's context. The last message's span is retained across pending
62/// flush/close polls and released when either operation completes successfully.
63pub struct ContextSink<S> {
64    inner: S,
65    span: tracing::Span,
66}
67
68impl<S> ContextSink<S> {
69    /// Wraps a downstream sink that accepts the unwrapped message values.
70    pub fn new(inner: S) -> Self {
71        Self {
72            inner,
73            span: tracing::Span::none(),
74        }
75    }
76}
77
78impl<S, T> Sink<WithContext<T>> for ContextSink<S>
79where
80    S: Sink<T> + Unpin,
81{
82    type Error = S::Error;
83
84    fn poll_ready(self: Pin<&mut Self>, cx: &mut Context<'_>) -> Poll<Result<(), Self::Error>> {
85        let this = self.get_mut();
86        Pin::new(&mut this.inner).poll_ready(cx)
87    }
88
89    fn start_send(self: Pin<&mut Self>, item: WithContext<T>) -> Result<(), Self::Error> {
90        let this = self.get_mut();
91        let (value, span) = item.into_parts();
92        this.span = span;
93        let _entered = this.span.enter();
94        Pin::new(&mut this.inner).start_send(value)
95    }
96
97    fn poll_flush(self: Pin<&mut Self>, cx: &mut Context<'_>) -> Poll<Result<(), Self::Error>> {
98        let this = self.get_mut();
99        let poll = {
100            let _entered = this.span.enter();
101            Pin::new(&mut this.inner).poll_flush(cx)
102        };
103        if matches!(poll, Poll::Ready(Ok(()))) {
104            this.span = tracing::Span::none();
105        }
106        poll
107    }
108
109    fn poll_close(self: Pin<&mut Self>, cx: &mut Context<'_>) -> Poll<Result<(), Self::Error>> {
110        let this = self.get_mut();
111        let poll = {
112            let _entered = this.span.enter();
113            Pin::new(&mut this.inner).poll_close(cx)
114        };
115        if matches!(poll, Poll::Ready(Ok(()))) {
116            this.span = tracing::Span::none();
117        }
118        poll
119    }
120}
121
122/// A bounded sender that captures the producer's span when a message is enqueued.
123/// Capture requires `tracing-context`; without it, messages carry a disabled span.
124#[derive(Debug)]
125pub struct ContextSender<T: Send + 'static> {
126    inner: CrossfireSink<WithContext<T>>,
127}
128
129impl<T: Send + 'static> Clone for ContextSender<T> {
130    fn clone(&self) -> Self {
131        Self {
132            inner: self.inner.clone(),
133        }
134    }
135}
136
137impl<T: Send + 'static> ContextSender<T> {
138    /// Wraps a bounded queue sender whose receiver yields context envelopes.
139    pub fn new(inner: CrossfireSink<WithContext<T>>) -> Self {
140        Self { inner }
141    }
142
143    /// Attempts to enqueue without waiting, retaining the original value on failure.
144    pub fn try_send(&self, item: T) -> Result<(), crossfire::TrySendError<T>> {
145        self.inner.try_send(item.into()).map_err(|error| match error {
146            crossfire::TrySendError::Full(message) => crossfire::TrySendError::Full(message.value),
147            crossfire::TrySendError::Disconnected(message) => crossfire::TrySendError::Disconnected(message.value),
148        })
149    }
150}
151
152impl<T: Send + 'static> Sink<T> for ContextSender<T>
153where
154    CrossfireSink<WithContext<T>>: Sink<WithContext<T>> + Unpin,
155{
156    type Error = <CrossfireSink<WithContext<T>> as Sink<WithContext<T>>>::Error;
157
158    fn poll_ready(self: Pin<&mut Self>, cx: &mut Context<'_>) -> Poll<Result<(), Self::Error>> {
159        Pin::new(&mut self.get_mut().inner).poll_ready(cx)
160    }
161
162    fn start_send(self: Pin<&mut Self>, item: T) -> Result<(), Self::Error> {
163        Pin::new(&mut self.get_mut().inner).start_send(item.into())
164    }
165
166    fn poll_flush(self: Pin<&mut Self>, cx: &mut Context<'_>) -> Poll<Result<(), Self::Error>> {
167        Pin::new(&mut self.get_mut().inner).poll_flush(cx)
168    }
169
170    fn poll_close(self: Pin<&mut Self>, cx: &mut Context<'_>) -> Poll<Result<(), Self::Error>> {
171        Pin::new(&mut self.get_mut().inner).poll_close(cx)
172    }
173}
174
175#[cfg(test)]
176mod tests {
177    use futures::StreamExt;
178    use hopr_utils::network_types::crossfire_sink::bounded_sink_channel;
179
180    use super::*;
181
182    #[derive(Default)]
183    struct ObservedSink {
184        events: Vec<(&'static str, Option<tracing::span::Id>)>,
185        received: Vec<u8>,
186        pending: bool,
187    }
188
189    impl ObservedSink {
190        fn observe(&mut self, operation: &'static str) {
191            self.events.push((operation, tracing::Span::current().id()));
192        }
193
194        fn poll_io(&mut self, operation: &'static str) -> Poll<Result<(), std::convert::Infallible>> {
195            self.observe(operation);
196            if std::mem::take(&mut self.pending) {
197                Poll::Pending
198            } else {
199                Poll::Ready(Ok(()))
200            }
201        }
202    }
203
204    impl Sink<u8> for ObservedSink {
205        type Error = std::convert::Infallible;
206
207        fn poll_ready(self: Pin<&mut Self>, _: &mut Context<'_>) -> Poll<Result<(), Self::Error>> {
208            self.get_mut().observe("ready");
209            Poll::Ready(Ok(()))
210        }
211
212        fn start_send(self: Pin<&mut Self>, item: u8) -> Result<(), Self::Error> {
213            let this = self.get_mut();
214            this.observe("send");
215            this.received.push(item);
216            Ok(())
217        }
218
219        fn poll_flush(self: Pin<&mut Self>, _: &mut Context<'_>) -> Poll<Result<(), Self::Error>> {
220            self.get_mut().poll_io("flush")
221        }
222
223        fn poll_close(self: Pin<&mut Self>, _: &mut Context<'_>) -> Poll<Result<(), Self::Error>> {
224            self.get_mut().poll_io("close")
225        }
226    }
227
228    #[test]
229    fn sink_readiness_should_use_the_caller_context_instead_of_the_previous_message() -> anyhow::Result<()> {
230        tracing::subscriber::with_default(test_log::tracing_subscriber::registry(), || {
231            let previous = tracing::debug_span!("previous_packet");
232            let previous_id = previous.id();
233            let caller = tracing::debug_span!("next_caller");
234            let mut sink = ContextSink::new(ObservedSink::default());
235            let mut cx = Context::from_waker(futures::task::noop_waker_ref());
236            assert_eq!(Pin::new(&mut sink).poll_ready(&mut cx), Poll::Ready(Ok(())));
237            Pin::new(&mut sink).start_send(WithContext::new(42, previous))?;
238            caller.in_scope(|| {
239                assert_eq!(Pin::new(&mut sink).poll_ready(&mut cx), Poll::Ready(Ok(())));
240            });
241            assert!(previous_id.is_some(), "fixture needs an active message span");
242            assert!(caller.id().is_some(), "fixture needs an active caller span");
243            assert_eq!(sink.inner.received, [42]);
244            assert_eq!(
245                sink.inner.events,
246                [("ready", None), ("send", previous_id), ("ready", caller.id())]
247            );
248            anyhow::Ok(())
249        })
250    }
251
252    #[test]
253    fn completed_io_should_release_the_last_message_span_while_the_sink_stays_alive() -> anyhow::Result<()> {
254        use std::sync::{
255            Arc,
256            atomic::{AtomicUsize, Ordering},
257        };
258
259        use test_log::tracing_subscriber::{self as subscriber, layer::SubscriberExt};
260
261        struct Closures(Arc<AtomicUsize>);
262        impl<S: tracing::Subscriber> subscriber::Layer<S> for Closures {
263            fn on_close(&self, _: tracing::span::Id, _: subscriber::layer::Context<'_, S>) {
264                self.0.fetch_add(1, Ordering::Relaxed);
265            }
266        }
267
268        for closing in [false, true] {
269            let closed = Arc::new(AtomicUsize::new(0));
270            let subscriber = subscriber::registry().with(Closures(closed.clone()));
271            tracing::subscriber::with_default(subscriber, || {
272                use anyhow::Context as _;
273
274                let message_span = tracing::debug_span!("in_flight_packet");
275                let message_id = message_span.id().context("fixture needs an active span")?;
276                let mut sink = ContextSink::new(ObservedSink {
277                    pending: true,
278                    ..Default::default()
279                });
280                let mut cx = Context::from_waker(futures::task::noop_waker_ref());
281                let operation = if closing { "close" } else { "flush" };
282                let poll_io = |sink: &mut ContextSink<ObservedSink>, cx: &mut Context<'_>| {
283                    if closing {
284                        Pin::new(sink).poll_close(cx)
285                    } else {
286                        Pin::new(sink).poll_flush(cx)
287                    }
288                };
289                assert_eq!(Pin::new(&mut sink).poll_ready(&mut cx), Poll::Ready(Ok(())));
290                Pin::new(&mut sink).start_send(WithContext::new(42, message_span))?;
291                assert_eq!(closed.load(Ordering::Relaxed), 0);
292                assert_eq!(poll_io(&mut sink, &mut cx), Poll::Pending);
293                assert_eq!(closed.load(Ordering::Relaxed), 0, "pending I/O must retain context");
294                assert_eq!(poll_io(&mut sink, &mut cx), Poll::Ready(Ok(())));
295                assert_eq!(
296                    closed.load(Ordering::Relaxed),
297                    1,
298                    "completed {operation} must close the final span without dropping the sink"
299                );
300                let mut expected = vec![
301                    ("ready", None),
302                    ("send", Some(message_id.clone())),
303                    (operation, Some(message_id.clone())),
304                    (operation, Some(message_id)),
305                ];
306                if !closing {
307                    // Once flushed, empty I/O must not reuse the completed message's context.
308                    assert_eq!(Pin::new(&mut sink).poll_flush(&mut cx), Poll::Ready(Ok(())));
309                    assert_eq!(Pin::new(&mut sink).poll_close(&mut cx), Poll::Ready(Ok(())));
310                    expected.extend([("flush", None), ("close", None)]);
311                }
312                assert_eq!(sink.inner.received, [42]);
313                assert_eq!(sink.inner.events, expected);
314                anyhow::Ok(())
315            })?;
316        }
317        Ok(())
318    }
319
320    #[test]
321    fn disabled_context_should_keep_the_envelope_compact() {
322        assert_eq!(
323            std::mem::size_of::<WithContext<u64>>(),
324            std::mem::size_of::<(u64, usize)>(),
325            "disabled spans must not occupy an inline Span in every queue slot"
326        );
327        let message = WithContext::new(42, tracing::Span::none());
328        assert!(message.span.is_none(), "disabled context must not allocate");
329        let (value, span) = message.into_parts();
330        assert_eq!(value, 42);
331        assert!(span.is_disabled());
332    }
333
334    #[tokio::test]
335    async fn sender_clones_should_share_capacity_and_return_rejected_values() -> anyhow::Result<()> {
336        let (tx, rx) = bounded_sink_channel(1);
337        let tx = ContextSender::new(tx);
338        let clone = tx.clone();
339        tx.try_send(1u8)?;
340        assert!(matches!(clone.try_send(2), Err(crossfire::TrySendError::Full(2))));
341        futures::pin_mut!(rx);
342        assert_eq!(rx.next().await.map(|message| message.value), Some(1));
343        clone.try_send(3)?;
344        Ok(())
345    }
346
347    #[test]
348    fn disconnected_sender_should_return_the_owned_message() {
349        let (tx, rx) = bounded_sink_channel(1);
350        let tx = ContextSender::new(tx);
351        drop(rx);
352        let message = vec![1u8, 2, 3];
353        match tx.try_send(message.clone()) {
354            Err(crossfire::TrySendError::Disconnected(returned)) => assert_eq!(returned, message),
355            result => panic!("expected disconnected sender to return the message, got {result:?}"),
356        }
357    }
358
359    #[tokio::test]
360    async fn sink_should_capture_the_producer_span_and_close_after_delivery() -> anyhow::Result<()> {
361        use futures::SinkExt;
362        use tracing::{Instrument, instrument::WithSubscriber};
363
364        async {
365            let (tx, rx) = bounded_sink_channel(1);
366            let mut tx = ContextSender::new(tx);
367            let producer = tracing::debug_span!("producer");
368            assert!(!producer.is_disabled(), "fixture needs an active producer span");
369            // Explicit pipeline context is preserved even when automatic capture is disabled.
370            let explicit = WithContext::new(7u8, producer.clone());
371            assert!(explicit.span.is_some());
372            let (value, restored) = explicit.into_parts();
373            assert_eq!(value, 7);
374            assert_eq!(restored.id(), producer.id());
375            let expected = if cfg!(feature = "tracing-context") {
376                producer.id()
377            } else {
378                None
379            };
380            tx.send(vec![42u8]).instrument(producer).await?;
381            futures::pin_mut!(rx);
382            let message = rx
383                .next()
384                .await
385                .ok_or_else(|| anyhow::anyhow!("missing queued message"))?;
386            assert_eq!(message.value, [42]);
387            assert_eq!(message.span().id(), expected);
388            tx.close().await?;
389            drop(tx);
390            assert!(
391                rx.next().await.is_none(),
392                "closing must preserve delivery and then terminate"
393            );
394            anyhow::Ok(())
395        }
396        .with_subscriber(test_log::tracing_subscriber::registry())
397        .await
398    }
399}