Repository: envoyproxy/envoy
File: source/extensions/dynamic_modules/sdk/rust/src/lib.rs (Rust)

Code before:
  ///
  /// * `graceful` - If true, initiates a graceful drain sequence before closing. If false, sends
  ///   GOAWAY and closes immediately.
  fn send_go_away_and_close(&mut self, graceful: bool);

  /// Recreate the HTTP stream, optionally with new headers.
  ///
  /// This is useful for implementing internal redirects or request retries.
  ///
  /// After calling this function successfully, the current filter chain will be destroyed and a new
  /// stream will be created. The filter should return StopIteration from the current event hook.
  ///
  /// * `headers` - Optional list of new headers for the recreated stream. If None, the original
  ///   headers will be reused.
  ///
  /// Returns `true` if the stream recreation was initiated successfully, `false` otherwise (e.g.,
  /// if the request body has not been fully received yet or if the stream cannot be recreated).
  fn recreate_stream<'a>(&mut self, headers: Option<Vec<(&'a str, &'a [u8])>>) -> bool;

  /// Refresh only the cluster selection for the current route without clearing the entire route
  /// cache.
  ///
  /// This is more efficient than clearing the route cache when only the cluster needs to be
  /// updated. This is useful when a filter modifies headers that affect cluster selection but not
  /// the route itself.
  fn refresh_route_cluster(&mut self);
}

/// Trait representing a tracing span.
///
/// This trait provides methods to interact with a tracing span, such as setting tags,
/// logging events, and spawning child spans.
///
/// The span is managed by Envoy and should not be finished by the module.
pub trait EnvoySpan {
  /// Set a tag on this span.
  ///
  /// Tags are key-value pairs that provide metadata about the span.
  fn set_tag(&self, key: &str, value: &str);

  /// Set the operation name on this span.
  fn set_operation(&self, operation: &str);

  /// Log an event on this span with the current timestamp.
  fn log(&self, event: &str);

  /// Override the sampling decision for this span.
  ///
  /// If sampled is false, this span and any subsequent child spans will not be
  /// reported to the tracing system.
  fn set_sampled(&self, sampled: bool);

Review comment (performance):
can you mention `clear_route_cache` method in the doc and explicitly say what this does is its subset. Also I would prefer the naming consistency with it -- like maybe `clear_route_cluster_cache`
```suggestion
  fn clear_route_cluster_cache(&mut self);
```

Code after:
  ///
  /// * `graceful` - If true, initiates a graceful drain sequence before closing. If false, sends
  ///   GOAWAY and closes immediately.
  fn send_go_away_and_close(&mut self, graceful: bool);

  /// Recreate the HTTP stream, optionally with new headers.
  ///
  /// This is useful for implementing internal redirects or request retries.
  ///
  /// After calling this function successfully, the current filter chain will be destroyed and a new
  /// stream will be created. The filter should return StopIteration from the current event hook.
  ///
  /// * `headers` - Optional list of new headers for the recreated stream. If None, the original
  ///   headers will be reused.
  ///
  /// Returns `true` if the stream recreation was initiated successfully, `false` otherwise (e.g.,
  /// if the request body has not been fully received yet or if the stream cannot be recreated).
  fn recreate_stream<'a>(&mut self, headers: Option<Vec<(&'a str, &'a [u8])>>) -> bool;

  /// Clear only the cluster selection for the current route without clearing the entire route
  /// cache.
  ///
  /// This is a subset of [`EnvoyHttpFilter::clear_route_cache`]. Use this when a filter modifies
  /// headers that affect cluster selection but not the route itself. This is more efficient than
  /// clearing the entire route cache.
  fn clear_route_cluster_cache(&mut self);
}

/// Trait representing a tracing span.
///
/// This trait provides methods to interact with a tracing span, such as setting tags,
/// logging events, and spawning child spans.
///
/// The span is managed by Envoy and should not be finished by the module.
pub trait EnvoySpan {
  /// Set a tag on this span.
  ///
  /// Tags are key-value pairs that provide metadata about the span.
  fn set_tag(&self, key: &str, value: &str);

  /// Set the operation name on this span.
  fn set_operation(&self, operation: &str);

  /// Log an event on this span with the current timestamp.
  fn log(&self, event: &str);

  /// Override the sampling decision for this span.
  ///
  /// If sampled is false, this span and any subsequent child spans will not be
  /// reported to the tracing system.
  fn set_sampled(&self, sampled: bool);