From 0f653af7f429a6dd13903e2201a773083ee0787f Mon Sep 17 00:00:00 2001
From: Younes <3153107+younes-io@users.noreply.github.com>
Date: Sun, 18 Jun 2023 14:09:49 +0200
Subject: [PATCH 1/2] Document hostcalls::dispatch_http_call

Signed-off-by: Younes <dev@younes.io>
---
 src/hostcalls.rs | 44 ++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 44 insertions(+)

diff --git a/src/hostcalls.rs b/src/hostcalls.rs
index f1c47793..ee2412d3 100644
--- a/src/hostcalls.rs
+++ b/src/hostcalls.rs
@@ -741,6 +741,50 @@ 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`: The URL or host of the upstream server to which the HTTP call will be made.
+/// * `headers`: A vector of tuples representing the HTTP headers to include in the request.
+///              Each tuple consists of a header name and value.
+/// * `body`: An optional byte slice representing the request body.
+/// * `trailers`: An optional vector of tuples representing the HTTP trailers to include in
+///               the request. Each tuple consists of a trailer name and value.
+/// * `timeout`: The duration after which the HTTP call will time out if no response is received.
+///
+/// # 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;
+///
+/// let upstream = "http://example.com";
+/// let headers = vec![("Content-Type", "application/json")];
+/// let body = Some(b"request body");
+/// let trailers = Some(vec![("Trailer-Name", "trailer value")]);
+/// let timeout = std::time::Duration::from_secs(5);
+///
+/// let result = dispatch_http_call(upstream, headers, body, trailers, timeout);
+///
+/// match result {
+///     Ok(status_code) => {
+///         println!("HTTP call successful. Status code: {}", status_code);
+///     }
+///     Err(error) => {
+///         println!("HTTP call failed. Error: {:?}", error);
+///     }
+/// }
+/// ```
 pub fn dispatch_http_call(
     upstream: &str,
     headers: Vec<(&str, &str)>,

From 4b9a685ad3ab435ea71c9f37b1794610b11da2f0 Mon Sep 17 00:00:00 2001
From: Younes <dev@younes.io>
Date: Sun, 18 Jun 2023 14:43:28 +0200
Subject: [PATCH 2/2] Update hostcalls.rs

Signed-off-by: Younes <dev@younes.io>
---
 src/hostcalls.rs | 43 ++++++++++++++++++++-----------------------
 1 file changed, 20 insertions(+), 23 deletions(-)

diff --git a/src/hostcalls.rs b/src/hostcalls.rs
index ee2412d3..d9e8d705 100644
--- a/src/hostcalls.rs
+++ b/src/hostcalls.rs
@@ -749,39 +749,36 @@ extern "C" {
 ///
 /// # Arguments
 ///
-/// * `upstream`: The URL or host of the upstream server to which the HTTP call will be made.
-/// * `headers`: A vector of tuples representing the HTTP headers to include in the request.
-///              Each tuple consists of a header name and value.
-/// * `body`: An optional byte slice representing the request body.
-/// * `trailers`: An optional vector of tuples representing the HTTP trailers to include in
-///               the request. Each tuple consists of a trailer name and value.
-/// * `timeout`: The duration after which the HTTP call will time out if no response is received.
+/// * `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.
+/// 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;
 ///
-/// let upstream = "http://example.com";
-/// let headers = vec![("Content-Type", "application/json")];
-/// let body = Some(b"request body");
-/// let trailers = Some(vec![("Trailer-Name", "trailer value")]);
-/// let timeout = std::time::Duration::from_secs(5);
+/// 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);
 ///
-/// let result = dispatch_http_call(upstream, headers, body, trailers, timeout);
-///
-/// match result {
-///     Ok(status_code) => {
-///         println!("HTTP call successful. Status code: {}", status_code);
-///     }
-///     Err(error) => {
-///         println!("HTTP call failed. Error: {:?}", error);
+///     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);
+///         }
 ///     }
 /// }
 /// ```