use std::cell::{Cell, RefCell};
use std::future::Future;
use std::marker::PhantomData;
use std::pin::Pin;
use std::task::{Context, Poll};
use super::header::{
fmt_correlation_id, next_correlation_id, RpcHeader, ServiceRef, CORRELATION_ID_LEN,
};
use crate::CancellationToken;
thread_local! {
static CURRENT: Cell<Option<CallContext>> = const { Cell::new(None) };
static CURRENT_CANCEL: RefCell<Option<CancellationToken>> = const { RefCell::new(None) };
}
#[derive(Debug, Clone, Copy, PartialEq, Eq, Default)]
pub struct TraceContext {
pub trace_id: [u8; 16],
pub parent_span_id: u64,
pub flags: u8,
}
impl TraceContext {
#[inline]
pub fn is_present(&self) -> bool {
self.trace_id != [0u8; 16]
}
#[inline]
pub fn is_sampled(&self) -> bool {
self.flags & 1 == 1
}
pub fn trace_id_hex(&self) -> String {
hex_trace_id(&self.trace_id)
}
#[inline]
pub fn new_root() -> Self {
Self {
trace_id: next_correlation_id(),
parent_span_id: 0,
flags: 0,
}
}
#[inline]
pub fn child_of(&self, span_id: u64) -> Self {
Self {
trace_id: self.trace_id,
parent_span_id: span_id,
flags: self.flags,
}
}
#[inline]
pub fn continued_or_root(&self, span_id: u64) -> Self {
if self.is_present() {
self.child_of(span_id)
} else {
Self::new_root()
}
}
}
fn hex_trace_id(bytes: &[u8; 16]) -> String {
use std::fmt::Write as _;
let mut out = String::with_capacity(32);
for byte in bytes {
let _ = write!(out, "{byte:02x}");
}
out
}
#[inline]
fn span_id_of(correlation_id: &[u8; CORRELATION_ID_LEN]) -> u64 {
let mut bytes = [0u8; 8];
bytes.copy_from_slice(&correlation_id[..8]);
u64::from_be_bytes(bytes)
}
#[cfg(feature = "tracing")]
macro_rules! rpc_span {
($ctx:expr $(, kind = $kind:expr)?) => {
tracing::info_span!(
"rpc",
$(kind = $kind,)?
service = $ctx.service_name,
version = $ctx.service_version,
method = $ctx.method,
corr = ?span_fields::Correlation(&$ctx.correlation_id),
trace = ?span_fields::TraceId(&$ctx.trace.trace_id),
parent = $ctx.trace.parent_span_id,
span = $ctx.span_id,
sampled = $ctx.trace.is_sampled(),
)
};
}
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub struct CallContext {
correlation_id: [u8; CORRELATION_ID_LEN],
service_name: &'static str,
service_id: u32,
service_version: u16,
method: &'static str,
received_at_ns: u64,
trace: TraceContext,
span_id: u64,
}
impl CallContext {
#[inline]
pub fn new(header: &RpcHeader, service_name: &'static str, method: &'static str) -> Self {
Self {
correlation_id: header.correlation_id,
service_name,
service_id: header.service_id,
service_version: header.service_version,
method,
received_at_ns: header.timestamp_ns,
trace: header.trace(),
span_id: span_id_of(&header.correlation_id),
}
}
#[inline]
pub fn local(service: ServiceRef, service_name: &'static str, method: &'static str) -> Self {
let correlation_id = next_correlation_id();
let trace = match Self::current() {
Some(parent) => parent.child_trace(),
None => TraceContext::new_root(),
};
Self {
correlation_id,
service_name,
service_id: service.id,
service_version: service.version,
method,
received_at_ns: 0,
trace,
span_id: span_id_of(&correlation_id),
}
}
#[inline]
pub fn correlation_id(&self) -> &[u8; CORRELATION_ID_LEN] {
&self.correlation_id
}
pub fn correlation(&self) -> String {
fmt_correlation_id(&self.correlation_id)
}
#[inline]
pub fn service_id(&self) -> u32 {
self.service_id
}
#[inline]
pub fn service_name(&self) -> &'static str {
self.service_name
}
#[inline]
pub fn service_version(&self) -> u16 {
self.service_version
}
#[inline]
pub fn method(&self) -> &'static str {
self.method
}
#[inline]
pub fn received_at_ns(&self) -> u64 {
self.received_at_ns
}
#[inline]
pub fn trace(&self) -> TraceContext {
self.trace
}
#[inline]
pub fn span_id(&self) -> u64 {
self.span_id
}
#[inline]
pub fn child_trace(&self) -> TraceContext {
self.trace.continued_or_root(self.span_id)
}
#[inline]
pub fn current() -> Option<CallContext> {
CURRENT.with(Cell::get)
}
#[inline]
pub fn cancellation() -> Option<CancellationToken> {
CURRENT_CANCEL.with(|slot| slot.borrow().clone())
}
#[must_use = "the context is only ambient while the returned scope is alive"]
pub fn enter_ambient(self) -> AmbientScope {
AmbientScope {
previous: CURRENT.with(|slot| slot.replace(Some(self))),
_not_send: PhantomData,
}
}
#[cfg(feature = "tracing")]
pub fn span(&self) -> tracing::Span {
rpc_span!(self)
}
#[cfg(feature = "tracing")]
fn span_local(&self) -> tracing::Span {
rpc_span!(self, kind = "local")
}
#[must_use = "the context is only ambient while the returned scope is alive"]
pub fn enter(self) -> CallContextScope {
let _ambient = self.enter_ambient();
#[cfg(feature = "tracing")]
let _span = self.span().entered();
CallContextScope {
_ambient,
#[cfg(feature = "tracing")]
_span,
}
}
}
pub type BoxResponseFuture = Pin<Box<dyn Future<Output = ()> + Send + 'static>>;
pub fn call_scoped<F>(ctx: CallContext, future: F) -> BoxResponseFuture
where
F: Future<Output = ()> + Send + 'static,
{
#[cfg(feature = "tracing")]
let span = ctx.span();
Box::pin(CallScope {
ctx,
inner: Box::pin(future),
#[cfg(feature = "tracing")]
span,
})
}
pub async fn local_call_scoped<F>(
service: ServiceRef,
service_name: &'static str,
method: &'static str,
future: F,
) -> F::Output
where
F: Future,
{
#[cfg(feature = "tracing")]
{
let ctx = CallContext::local(service, service_name, method);
let span = ctx.span_local();
let mut future = std::pin::pin!(future);
return std::future::poll_fn(move |cx| {
let _ambient = ctx.enter_ambient();
let _span = span.enter();
future.as_mut().poll(cx)
})
.await;
}
#[cfg(not(feature = "tracing"))]
{
let _ = (service, service_name, method);
future.await
}
}
struct CallScope {
ctx: CallContext,
inner: BoxResponseFuture,
#[cfg(feature = "tracing")]
span: tracing::Span,
}
impl Future for CallScope {
type Output = ();
fn poll(self: Pin<&mut Self>, cx: &mut Context<'_>) -> Poll<()> {
let this = self.get_mut();
let _ambient = this.ctx.enter_ambient();
#[cfg(feature = "tracing")]
let _span = this.span.enter();
this.inner.as_mut().poll(cx)
}
}
#[cfg(feature = "tracing")]
mod span_fields {
use std::fmt;
use crate::types::header::{fmt_correlation_id, CORRELATION_ID_LEN};
pub(super) struct Correlation<'a>(pub(super) &'a [u8; CORRELATION_ID_LEN]);
impl fmt::Debug for Correlation<'_> {
fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
f.write_str(&fmt_correlation_id(self.0))
}
}
pub(super) struct TraceId<'a>(pub(super) &'a [u8; 16]);
impl fmt::Debug for TraceId<'_> {
fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
f.write_str(&super::hex_trace_id(self.0))
}
}
}
#[must_use = "the token is only ambient while the returned scope is alive"]
pub(crate) fn install_call_cancellation(token: CancellationToken) -> AmbientCancelScope {
AmbientCancelScope {
previous: CURRENT_CANCEL.with(|slot| slot.replace(Some(token))),
}
}
pub(crate) struct AmbientCancelScope {
previous: Option<CancellationToken>,
}
impl Drop for AmbientCancelScope {
fn drop(&mut self) {
CURRENT_CANCEL.with(|slot| *slot.borrow_mut() = self.previous.take());
}
}
pub struct AmbientScope {
previous: Option<CallContext>,
_not_send: PhantomData<*const ()>,
}
impl Drop for AmbientScope {
fn drop(&mut self) {
CURRENT.with(|slot| slot.set(self.previous));
}
}
pub struct CallContextScope {
_ambient: AmbientScope,
#[cfg(feature = "tracing")]
_span: tracing::span::EnteredSpan,
}
#[cfg(test)]
mod tests {
use super::*;
use crate::types::header::service_id_of;
#[test]
fn a_context_mirrors_the_request_header() {
let id = service_id_of("Db");
let header = RpcHeader::request("get_user_age", id, 3);
let ctx = CallContext::new(&header, "Db", "get_user_age");
assert_eq!(ctx.correlation_id(), &header.correlation_id);
assert_eq!(ctx.service_id(), id);
assert_eq!(ctx.service_version(), 3);
assert_eq!(ctx.method(), "get_user_age");
assert_eq!(ctx.received_at_ns(), header.timestamp_ns);
assert_eq!(ctx.correlation().len(), 36);
}
#[test]
fn no_trace_is_present_until_the_wire_carries_one() {
let header = RpcHeader::request("ping", 7, 1);
let ctx = CallContext::new(&header, "Ping", "ping");
assert!(!ctx.trace().is_present());
assert!(!ctx.trace().is_sampled());
}
#[test]
fn a_child_call_continues_the_trace_and_parents_on_our_span() {
let header = RpcHeader::request("outer", 1, 1).with_trace(TraceContext::new_root());
let ctx = CallContext::new(&header, "Outer", "outer");
assert!(ctx.trace().is_present());
let out = ctx.child_trace();
assert_eq!(out.trace_id, ctx.trace().trace_id, "same trace");
assert_eq!(out.parent_span_id, ctx.span_id(), "parented on our span");
let header = RpcHeader::request("mid", 2, 1).with_trace(out);
let ctx = CallContext::new(&header, "Mid", "mid");
let out = ctx.child_trace();
assert_eq!(out.trace_id, header.trace().trace_id);
assert_eq!(out.parent_span_id, ctx.span_id());
assert_ne!(
out.parent_span_id, 0,
"a nested hop is not a root: it has a parent"
);
}
#[test]
fn a_call_outside_any_trace_starts_one() {
let header = RpcHeader::request("root", 1, 1);
let ctx = CallContext::new(&header, "Root", "root");
assert!(!ctx.trace().is_present());
let out = ctx.child_trace();
assert!(out.is_present(), "a fresh trace is started");
assert_eq!(out.parent_span_id, 0, "a root has no parent");
assert_ne!(
out.trace_id,
ctx.trace().trace_id,
"the fresh id replaces the absent one rather than reusing it"
);
}
#[test]
fn the_cancellation_token_is_ambient_only_within_its_scope() {
assert!(
CallContext::cancellation().is_none(),
"nothing before entering"
);
let outer = CancellationToken::new();
let outer_scope = install_call_cancellation(outer.clone());
assert!(
!CallContext::cancellation()
.expect("the outer token is ambient")
.is_cancelled(),
"a fresh token is not cancelled"
);
{
let inner = CancellationToken::new();
let _inner_scope = install_call_cancellation(inner.clone());
inner.cancel();
assert!(
CallContext::cancellation().unwrap().is_cancelled(),
"the inner token is the ambient one"
);
}
assert!(
!CallContext::cancellation().unwrap().is_cancelled(),
"the outer token is back"
);
drop(outer_scope);
assert!(
CallContext::cancellation().is_none(),
"the slot is restored after"
);
}
#[test]
fn a_context_without_a_transport_wrapper_has_no_token() {
let header = RpcHeader::request("ping", 7, 1);
let task = call_scoped(CallContext::new(&header, "Ping", "ping"), async {
assert!(CallContext::current().is_some(), "the context is installed");
assert!(
CallContext::cancellation().is_none(),
"no token was installed by the transport"
);
});
futures_lite::future::block_on(task);
}
#[test]
fn the_context_is_ambient_only_within_its_scope() {
assert!(CallContext::current().is_none(), "nothing before entering");
let outer = CallContext::new(&RpcHeader::request("outer", 1, 1), "Outer", "outer");
let _outer_scope = outer.enter();
assert_eq!(CallContext::current().unwrap().method(), "outer");
{
let inner = CallContext::new(&RpcHeader::request("inner", 2, 1), "Inner", "inner");
let _inner_scope = inner.enter();
assert_eq!(CallContext::current().unwrap().method(), "inner");
}
assert_eq!(CallContext::current().unwrap().method(), "outer");
drop(_outer_scope);
assert!(
CallContext::current().is_none(),
"the slot is restored after"
);
}
#[cfg(feature = "tracing")]
#[derive(Default)]
struct SpanRecorder {
names: std::sync::Mutex<Vec<String>>,
entered: std::sync::atomic::AtomicUsize,
exited: std::sync::atomic::AtomicUsize,
}
#[cfg(feature = "tracing")]
impl tracing::Subscriber for SpanRecorder {
fn enabled(&self, _metadata: &tracing::Metadata<'_>) -> bool {
true
}
fn new_span(&self, span: &tracing::span::Attributes<'_>) -> tracing::Id {
let mut names = self.names.lock().unwrap_or_else(|e| e.into_inner());
names.push(span.metadata().name().to_owned());
tracing::Id::from_u64(names.len() as u64)
}
fn record(&self, _span: &tracing::Id, _values: &tracing::span::Record<'_>) {}
fn record_follows_from(&self, _span: &tracing::Id, _follows: &tracing::Id) {}
fn event(&self, _event: &tracing::Event<'_>) {}
fn enter(&self, _span: &tracing::Id) {
self.entered
.fetch_add(1, std::sync::atomic::Ordering::Relaxed);
}
fn exit(&self, _span: &tracing::Id) {
self.exited
.fetch_add(1, std::sync::atomic::Ordering::Relaxed);
}
}
#[cfg(feature = "tracing")]
#[test]
fn the_call_scope_emits_and_enters_a_span() {
use std::sync::atomic::Ordering;
use std::sync::Arc;
let recorder = Arc::new(SpanRecorder::default());
let dispatch = tracing::Dispatch::new(Arc::clone(&recorder));
tracing::dispatcher::with_default(&dispatch, || {
let header = RpcHeader::request("ping", 7, 1);
let _scope = CallContext::new(&header, "Ping", "ping").enter();
assert_eq!(
recorder.entered.load(Ordering::Relaxed),
1,
"the span is entered while the call runs"
);
});
let names = recorder.names.lock().unwrap_or_else(|e| e.into_inner());
assert_eq!(*names, ["rpc"], "one span per call, named after the RPC");
assert_eq!(recorder.entered.load(Ordering::Relaxed), 1, "entered once");
assert_eq!(
recorder.exited.load(Ordering::Relaxed),
1,
"exited when the scope drops"
);
}
#[cfg(feature = "tracing")]
#[test]
fn the_call_scope_enters_one_span_per_poll() {
use std::sync::atomic::Ordering;
use std::sync::Arc;
async fn yields_once() {
let mut yielded = false;
futures_lite::future::poll_fn(|_cx| {
if yielded {
Poll::Ready(())
} else {
yielded = true;
Poll::Pending
}
})
.await;
}
let recorder = Arc::new(SpanRecorder::default());
let dispatch = tracing::Dispatch::new(Arc::clone(&recorder));
tracing::dispatcher::with_default(&dispatch, || {
let header = RpcHeader::request("ping", 7, 1);
let mut task = call_scoped(CallContext::new(&header, "Ping", "ping"), yields_once());
let mut cx = Context::from_waker(std::task::Waker::noop());
assert!(task.as_mut().poll(&mut cx).is_pending());
assert!(task.as_mut().poll(&mut cx).is_ready());
});
let names = recorder
.names
.lock()
.unwrap_or_else(|e| e.into_inner())
.clone();
assert_eq!(
names,
["rpc"],
"one span for the whole call, not one per poll"
);
assert_eq!(
recorder.entered.load(Ordering::Relaxed),
2,
"entered around each of the two polls"
);
assert_eq!(
recorder.exited.load(Ordering::Relaxed),
2,
"and left after each"
);
}
#[test]
fn the_context_follows_the_task_being_polled() {
use std::sync::{Arc, Mutex};
async fn yield_once() {
let mut yielded = false;
futures_lite::future::poll_fn(|_cx| {
if yielded {
Poll::Ready(())
} else {
yielded = true;
Poll::Pending
}
})
.await;
}
type Seen = Vec<(&'static str, Option<&'static str>)>;
let seen: Arc<Mutex<Seen>> = Arc::default();
let task = |method: &'static str, seen: Arc<Mutex<Seen>>| {
let ctx = CallContext::new(&RpcHeader::request(method, 1, 1), "Svc", method);
call_scoped(ctx, async move {
let observed = CallContext::current().map(|ctx| ctx.method());
seen.lock().unwrap().push((method, observed));
yield_once().await;
let observed = CallContext::current().map(|ctx| ctx.method());
seen.lock().unwrap().push((method, observed));
})
};
let mut first = std::pin::pin!(task("first", Arc::clone(&seen)));
let mut second = std::pin::pin!(task("second", Arc::clone(&seen)));
let mut cx = Context::from_waker(std::task::Waker::noop());
assert!(first.as_mut().poll(&mut cx).is_pending());
assert!(second.as_mut().poll(&mut cx).is_pending());
assert!(first.as_mut().poll(&mut cx).is_ready());
assert!(second.as_mut().poll(&mut cx).is_ready());
assert_eq!(
&*seen.lock().unwrap(),
&[
("first", Some("first")),
("second", Some("second")),
("first", Some("first")),
("second", Some("second")),
],
"each poll must observe the context of its own call"
);
}
#[test]
fn a_local_context_names_the_callee_and_carries_no_clock() {
let ctx = CallContext::local(ServiceRef::new(7, 3), "Leaf", "reserve");
assert_eq!(
ctx.service_id(),
7,
"the callee's identity, not the caller's"
);
assert_eq!(ctx.service_version(), 3);
assert_eq!(ctx.method(), "reserve");
assert_eq!(
ctx.received_at_ns(),
0,
"nothing was emitted on the wire, so there is no emission instant"
);
assert_eq!(
ctx.correlation().len(),
36,
"a correlation id is still minted: it is what joins a log line to the call"
);
assert!(
ctx.trace().is_present(),
"outside any ambient call, a direct call starts a trace"
);
assert_eq!(ctx.trace().parent_span_id, 0, "a root has no parent");
}
#[test]
fn a_local_context_continues_the_ambient_trace_and_parents_on_it() {
let header = RpcHeader::request("place_order", 1, 1).with_trace(TraceContext::new_root());
let parent = CallContext::new(&header, "OrderService", "place_order");
let child = {
let _scope = parent.enter_ambient();
assert_eq!(
CallContext::current(),
Some(parent),
"inside the scope, the caller is the ambient context"
);
CallContext::local(ServiceRef::new(7, 1), "Leaf", "reserve")
};
assert_eq!(
child.trace().trace_id,
parent.trace().trace_id,
"same trace"
);
assert_eq!(
child.trace().parent_span_id,
parent.span_id(),
"the delegation parents on the caller's span"
);
assert_eq!(
CallContext::current(),
None,
"leaving the scope restores the previous value, which was none"
);
}
#[test]
fn a_direct_call_is_a_plain_await_unless_the_deployment_collects() {
let observed = pollster::block_on(local_call_scoped(
ServiceRef::new(7, 3),
"Leaf",
"reserve",
async { CallContext::current() },
));
#[cfg(feature = "tracing")]
{
let ctx = observed.expect("with a collector, the callee sees its own context");
assert_eq!(ctx.service_id(), 7);
assert_eq!(
ctx.service_name(),
"Leaf",
"the declared name travels with the call, for the span and the logs"
);
assert_eq!(ctx.method(), "reserve");
}
#[cfg(not(feature = "tracing"))]
{
assert!(
observed.is_none(),
"with no collector, no context is built and none is installed"
);
}
}
}