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

Code before:
  /// 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);

  /// Get a baggage value from this span.
  ///
  /// Baggage data may have been set by this span or any parent spans.
  /// Returns `None` if the key was not found.
  ///
  /// Note: The returned string is temporary and should be copied if needed
  /// beyond immediate use.
  fn get_baggage(&self, key: &str) -> Option<String>;

  /// Set a baggage value on this span.
  ///
  /// All subsequent child spans will have access to this baggage.
  fn set_baggage(&self, key: &str, value: &str);

  /// Get the trace ID from this span.
  ///
  /// Returns `None` if the trace ID is not available.
  ///
  /// Note: The returned string is temporary and should be copied if needed
  /// beyond immediate use.
  fn get_trace_id(&self) -> Option<String>;

  /// Get the span ID from this span.
  ///
  /// Returns `None` if the span ID is not available.
  ///
  /// Note: The returned string is temporary and should be copied if needed
  /// beyond immediate use.
  fn get_span_id(&self) -> Option<String>;

  /// Create a child span with the given operation name.
  ///
  /// The child span must be finished by calling [`EnvoyChildSpan::finish`] when done.
  fn spawn_child(&self, operation_name: &str) -> Option<Box<dyn EnvoyChildSpan + '_>>;
}

/// Implementation of [`EnvoySpan`] that wraps the raw span pointer from Envoy.
struct EnvoySpanImpl {
  raw_ptr: abi::envoy_dynamic_module_type_span_envoy_ptr,

Review comment (suggestion):
Hi @agrawroh - I was curious about this method, maybe it could have some more documentation?

- What happens when calling this on HTTP/1, is it mapped to something like hard connection close, or is it ignored, or panic?
- HTTP filters operate on HTTP streams, not connections, so it's confusing to me having a connection-level operation here. What happens if multiple filters call this?

I found the original doc has a bit more on it

https://github.com/envoyproxy/envoy/blob/e16ab1e0d312dd455002500cf0b7d2f4d7c171e3/envoy/http/filter.h#L691

"No filter chain will proceed" - so it seems to effectively pause all the streams on a connection. Maybe at least adding something along those lines if not more could help understand the ABI.

Thanks

Code after:
  /// * `host` - The host address to override (e.g., "10.0.0.1:8080"). Must be a valid IP address.
  /// * `strict` - If true, the request will fail if the override host is not available. If false,
  ///   normal load balancing will be used as a fallback.
  ///
  /// Returns `true` if the override was set successfully, `false` if the host address is invalid.
  fn set_upstream_override_host(&mut self, host: &str, strict: bool) -> bool;

  // ------------------- Stream Control methods -------------------------

  /// Reset the HTTP stream with the specified reason.
  ///
  /// This is useful for terminating the stream when an error condition is detected or when
  /// the filter needs to abort processing.
  ///
  /// After calling this function, no further filter callbacks will be invoked for this stream
  /// except for the destroy callback.
  ///
  /// * `reason` - The reason for resetting the stream.
  /// * `details` - Details string explaining the reset reason. Can be empty.
  fn reset_stream(
    &mut self,
    reason: abi::envoy_dynamic_module_type_http_filter_stream_reset_reason,
    details: &str,
  );

  /// Send a GOAWAY frame to the downstream and close the connection.
  ///
  /// This is useful for implementing graceful connection shutdown scenarios.
  ///
  /// * `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