1use std::{
4 pin::Pin,
5 task::{Context, Poll},
6};
7
8use futures::Sink;
9use hopr_utils::network_types::crossfire_sink::CrossfireSink;
10
11#[derive(Debug)]
14pub struct WithContext<T> {
15 pub value: T,
17 span: Option<Box<tracing::Span>>,
18}
19
20impl<T> WithContext<T> {
21 pub fn new(value: T, span: tracing::Span) -> Self {
30 Self {
31 value,
32 span: (!span.is_disabled()).then(|| Box::new(span)),
35 }
36 }
37
38 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 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
60pub struct ContextSink<S> {
64 inner: S,
65 span: tracing::Span,
66}
67
68impl<S> ContextSink<S> {
69 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#[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 pub fn new(inner: CrossfireSink<WithContext<T>>) -> Self {
140 Self { inner }
141 }
142
143 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 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 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}