rama_net/extensions.rs
1//! Best-effort breadcrumbs marking that a stream has been transformed,
2//! such as moving into a decoding stream or lifted as a multiplex stream.
3//! Inserted by services that decode / terminate / multiplex an outer layer;
4//! observed by code that wants to either:
5//!
6//! * trace what happened to a connection on its way through the
7//! stack, or
8//! * act on the knowledge that the bytes here are no longer the
9//! raw bytes on the wire — e.g. to skip an optimisation that
10//! only applies to untouched connections.
11//!
12//! **Not** a strict guarantee. Nothing enforces that every
13//! transformer inserts one. Compose your stack with care first;
14//! treat these as one slice in a Swiss-cheese defense and as
15//! handy trace breadcrumbs.
16
17use rama_core::extensions::Extension;
18
19/// A handshake / transition completed on this stream: from here
20/// the bytes (or their meaning) are no longer the raw wire form.
21/// Examples: TLS termination, HTTP upgrade, SOCKS5 handshake,
22/// HTTP/1 or HTTP/2 connection handshake.
23#[derive(Debug, Clone, Copy, Extension)]
24#[extension(tags(net))]
25pub struct StreamTransformed {
26 /// Free-form tag for the inserting site; surfaces in traces.
27 pub by: &'static str,
28}
29
30/// This point sees one of several logical streams multiplexed
31/// over a shared underlying transport (HTTP/2, HTTP/3, gRPC).
32#[derive(Debug, Clone, Copy, Extension)]
33#[extension(tags(net))]
34pub struct StreamMultiplexed {
35 /// Free-form tag for the inserting site; surfaces in traces.
36 pub by: &'static str,
37}