opentelemetry/propagation/
text_map_propagator.rs

1//! # TextMapPropagator
2//!
3//! [`TextMapPropagator`] performs the injection and extraction of a cross-cutting concern value as
4//! string key/values pairs into carriers that travel in-band across process boundaries.
5//!
6//! The carrier of propagated data on both the client (injector) and server (extractor) side is
7//! usually an HTTP request.
8//!
9//! In order to increase compatibility, the key/value pairs MUST only consist of US-ASCII characters
10//! that make up valid HTTP header fields as per RFC 7230.
11use crate::{
12    propagation::{Extractor, Injector},
13    Context,
14};
15use std::fmt::Debug;
16use std::slice;
17
18/// Methods to inject and extract a value as text into injectors and extractors that travel
19/// in-band across process boundaries.
20pub trait TextMapPropagator: Debug {
21    /// Properly encodes the values of the current [`Context`] and injects them into
22    /// the [`Injector`].
23    ///
24    /// [`Context`]: crate::Context
25    /// [`Injector`]: crate::propagation::Injector
26    fn inject(&self, injector: &mut dyn Injector) {
27        Context::map_current(|cx| self.inject_context(cx, injector))
28    }
29
30    /// Properly encodes the values of the [`Context`] and injects them into the
31    /// [`Injector`].
32    ///
33    /// [`Context`]: crate::Context
34    /// [`Injector`]: crate::propagation::Injector
35    fn inject_context(&self, cx: &Context, injector: &mut dyn Injector);
36
37    /// Retrieves encoded data using the provided [`Extractor`]. If no data for this
38    /// format was retrieved OR if the retrieved data is invalid, then the current
39    /// [`Context`] is returned.
40    ///
41    /// [`Context`]: crate::Context
42    /// [`Injector`]: crate::propagation::Extractor
43    fn extract(&self, extractor: &dyn Extractor) -> Context {
44        Context::map_current(|cx| self.extract_with_context(cx, extractor))
45    }
46
47    /// Retrieves encoded data using the provided [`Extractor`]. If no data for this
48    /// format was retrieved OR if the retrieved data is invalid, then the given
49    /// [`Context`] is returned.
50    ///
51    /// [`Context`]: crate::Context
52    /// [`Injector`]: crate::propagation::Extractor
53    fn extract_with_context(&self, cx: &Context, extractor: &dyn Extractor) -> Context;
54
55    /// Returns iter of fields used by [`TextMapPropagator`]
56    ///
57    fn fields(&self) -> FieldIter<'_>;
58}
59
60/// An iterator over fields of a [`TextMapPropagator`]
61///
62#[derive(Debug)]
63pub struct FieldIter<'a>(slice::Iter<'a, String>);
64
65impl<'a> FieldIter<'a> {
66    /// Create a new `FieldIter` from a slice of propagator fields
67    pub fn new(fields: &'a [String]) -> Self {
68        FieldIter(fields.iter())
69    }
70}
71
72impl<'a> Iterator for FieldIter<'a> {
73    type Item = &'a str;
74    fn next(&mut self) -> Option<Self::Item> {
75        self.0.next().map(|field| field.as_str())
76    }
77}
opentelemetry/propagation/text_map_propagator.rs

opentelemetry/propagation/
text_map_propagator.rs
