Document hostcalls::dispatch_http_call

src/hostcalls.rs

@@ -741,6 +741,47 @@ extern "C" {
     ) -> Status;
 }
 
+/// Initiates an HTTP call to an upstream server.
+///
+/// This function sends an HTTP request to the specified `upstream` server with the provided
+/// `headers`, `body`, and `trailers`. The `timeout` parameter specifies the duration after
+/// which the call will time out if no response is received.
+///
+/// # Arguments
+///
+/// * `upstream`: A string specifying the name of the upstream cluster to send the HTTP request to.
+/// * `headers`: A vector of tuples representing the HTTP headers to include in the request. Each tuple contains a header name and its corresponding value.
+/// * `body`: An optional byte slice representing the body of the HTTP request.
+/// * `trailers`: A vector of tuples representing the trailers to include in the request. Each tuple contains a trailer name and its corresponding value.
+/// * `timeout`: A `Duration` specifying the timeout duration for the HTTP request.
+///
+/// # Returns
+///
+/// A `Result` indicating the success or failure of the HTTP call. If the call is successful, the function returns an HTTP status code as a `u32`. If an error occurs, an `Error` object is returned.
+///
+/// # Example
+///
+/// ```rust
+/// use proxy_wasm::hostcalls::dispatch_http_call;
+/// use std::time::Duration;
+///
+/// fn main() {
+///     let upstream = "my_upstream";
+///     let headers = vec![("Content-Type", "application/json")];
+///     let body = Some(b"request body");
+///     let trailers = vec![];
+///     let timeout = Duration::from_secs(5);
+///
+///     match dispatch_http_call(upstream, headers, body, trailers, timeout) {
+///         Ok(return_token) => {
+///             println!("HTTP call dispatched successfully. Return token: {}", return_token);
+///         }
+///         Err(status) => {
+///             println!("Failed to dispatch HTTP call. Error status: {:?}", status);
+///         }
+///     }
+/// }
+/// ```
 pub fn dispatch_http_call(
     upstream: &str,
     headers: Vec<(&str, &str)>,