///|
/// A point one attempt's exchange reached in its backend, for observation
/// only (CONTRACT.md, Backend rule 13). A backend reports the points it can
/// see, in the order below, each at most once per attempt, and never after
/// the send returned or raised; JS fetch sees none of them and reports
/// nothing. The cases are declared in the order they happen.
///
/// ```mbt check
/// test {
/// let seen = []
/// let request = @mttp_core.Request::get("http://example.test/")
/// let request = {
/// ..request,
/// attributes: request.attributes.put(@mttp_core.on_phase, event => {
/// seen.push(event)
/// }),
/// }
/// // A backend looks the callback up and reports what it reached.
/// if request.attributes.get(@mttp_core.on_phase) is Some(report) {
/// report(Dialed(addr="example.test:80"))
/// report(Pooled(reused=false))
/// }
/// assert_eq(seen, [Dialed(addr="example.test:80"), Pooled(reused=false)])
/// }
/// ```
#derive(Eq, Debug)
#non_exhaustive
pub(all) enum PhaseEvent {
/// A new connection is open to `addr`, written `host:port` with an IPv6
/// host in brackets: the origin, or the proxy when one carries the
/// request (OpenTelemetry `server.address` and `server.port`).
Dialed(addr~ : String)
/// The connection's TLS handshake finished.
TlsDone
/// The attempt has its connection: `reused` is true for one taken from
/// the idle pool (no `Dialed` or `TlsDone` precedes it), false for one
/// dialled for it.
Pooled(reused~ : Bool)
/// The whole request, head and body, was written.
Written
/// The first byte of the response arrived.
FirstByte
}
///|
/// Compares phase events.
pub extend PhaseEvent with Eq::{equal, not_equal}
///|
/// Formats a phase event for diagnostics.
pub extend PhaseEvent with @debug.Debug::{to_repr}
///|
/// Set on a request by the caller that wants its backend's `PhaseEvent`s:
/// the backend calls it as the exchange reaches each point. A `Client`
/// built with `events` sets it on every attempt. Wrappers pass request
/// attributes on, so it reaches the engine underneath.
pub let on_phase : AttributeKey[(PhaseEvent) -> Unit] = AttributeKey::new(
"on_phase",
)