Expand and correct docs on procedure_http_request ABI function (#3950)

# Description of Changes

Title.

# API and ABI breaking changes

N/a

# Expected complexity level and risk

1

# Testing

- [ ] Get @coolreader18 to confirm what I've written here is correct.

Author: gefjon

crates/bindings-sys/src/lib.rs

@@ -731,15 +731,28 @@ pub mod raw {
 
         /// Perform an HTTP request as specified by the buffer `request_ptr[..request_len]`,
         /// suspending execution until the request is complete,
-        /// then return its response via a [`BytesSource`] written to `out`.
+        /// then return its response details via a [`BytesSource`] written to `out[0]`
+        /// and its response body via another [`BytesSource`] written to `out[1]`.
         ///
         /// `request_ptr[..request_len]` should store a BSATN-serialized `spacetimedb_lib::http::Request` object
         /// containing the details of the request to be performed.
         ///
-        /// If the request is successful, a [`BytesSource`] is written to `out`
-        /// containing a BSATN-encoded `spacetimedb_lib::http::Response` object.
+        /// `body_ptr[..body_len]` should store a byte array, which will be treated as the body of the request.
+        /// `body_ptr` should be non-null and within the bounds of linear memory even when `body_len` is 0.
+        ///
+        /// If the request is successful, a [`BytesSource`] is written to `out[0]`
+        /// containing a BSATN-encoded `spacetimedb_lib::http::Response` object,
+        /// another [`BytesSource`] containing the bytes of the response body are written to `out[1]`,
+        /// and this function returns 0.
+        ///
         /// "Successful" in this context includes any connection which results in any HTTP status code,
         /// regardless of the specified meaning of that code.
+        /// This includes HTTP error codes such as 404 Not Found and 500 Internal Server Error.
+        ///
+        /// If the request fails, a [`BytesSource`] is written to `out[0]`
+        /// containing a BSATN-encoded [`String`] describing the failure,
+        /// and this function returns `HTTP_ERROR`.
+        /// In this case, `out[1]` is not written.
         ///
         /// # Errors
         ///
@@ -759,6 +772,7 @@ pub mod raw {
         /// Traps if:
         ///
         /// - `request_ptr` is NULL or `request_ptr[..request_len]` is not in bounds of WASM memory.
+        /// - `body_ptr` is NULL or `body_ptr[..body_len]` is not in bounds of WASM memory.
         /// - `out` is NULL or `out[..size_of::<RowIter>()]` is not in bounds of WASM memory.
         /// - `request_ptr[..request_len]` does not contain a valid BSATN-serialized `spacetimedb_lib::http::Request` object.
         #[cfg(feature = "unstable")]

crates/core/src/host/wasmtime/wasm_instance_env.rs

@@ -1650,19 +1650,28 @@ impl WasmInstanceEnv {
     /// Perform an HTTP request as specified by the buffer `request_ptr[..request_len]`,
     /// suspending execution until the request is complete,
     /// then return its response details via a [`BytesSource`] written to `out[0]`
-    /// and its response body via a [`BytesSource`] written to `out[1]`.
+    /// and its response body via another [`BytesSource`] written to `out[1]`.
     ///
     /// `request_ptr[..request_len]` should store a BSATN-serialized [`spacetimedb_lib::http::Request`] object
     /// containing the details of the request to be performed.
     ///
-    /// `body_ptr[..body_len]` should store the body of the request to be performed;
+    /// `body_ptr[..body_len]` should store a byte array, which will be treated as the body of the request.
+    /// `body_ptr` should be non-null and within the bounds of linear memory even when `body_len` is 0.
+    ///
+    /// If the request is successful, a [`BytesSource`] is written to `out[0]`
+    /// containing a BSATN-encoded [`spacetimedb_lib::http::Response`] object,
+    /// another [`BytesSource`] containing the bytes of the response body are written to `out[1]`,
+    /// and this function returns 0.
     ///
-    /// If the request is successful, a [`BytesSource`] is written to `out`
-    /// containing a BSATN-encoded [`spacetimedb_lib::http::Response`] object.
     /// "Successful" in this context includes any connection which results in any HTTP status code,
     /// regardless of the specified meaning of that code.
     /// This includes HTTP error codes such as 404 Not Found and 500 Internal Server Error.
     ///
+    /// If the request fails, a [`BytesSource`] is written to `out[0]`
+    /// containing a BSATN-encoded `String` describing the failure,
+    /// and this function returns `HTTP_ERROR`.
+    /// In this case, `out[1]` is not written.
+    ///
     /// # Errors
     ///
     /// Returns an error:
@@ -1674,7 +1683,7 @@ impl WasmInstanceEnv {
     ///   In this case, `out` is not written.
     /// - `HTTP_ERROR` if an error occurs while executing the HTTP request.
     ///   In this case, a [`BytesSource`] is written to `out`
-    ///   containing a BSATN-encoded [`spacetimedb_lib::http::Error`] object.
+    ///   containing a BSATN-encoded [`String`].
     ///
     /// # Traps
     ///
@@ -1683,6 +1692,7 @@ impl WasmInstanceEnv {
     /// - `request_ptr` is NULL or `request_ptr[..request_len]` is not in bounds of WASM memory.
     /// - `body_ptr` is NULL or `body_ptr[..body_len]` is not in bounds of WASM memory.
     /// - `out` is NULL or `out[..size_of::<RowIter>()]` is not in bounds of WASM memory.
+    /// - `request_ptr[..request_len]` does not contain a valid BSATN-serialized `spacetimedb_lib::http::Request` object.
     pub fn procedure_http_request<'caller>(
         caller: Caller<'caller, Self>,
         (request_ptr, request_len, body_ptr, body_len, out): (WasmPtr<u8>, u32, WasmPtr<u8>, u32, WasmPtr<u32>),

crates/lib/src/http.rs

@@ -1,4 +1,4 @@
-//! `SpacetimeType`-ified HTTP request, response and error types,
+//! `SpacetimeType`-ified HTTP request and response types,
 //! for use in the procedure HTTP API.
 //!
 //! The types here are all mirrors of various types within the `http` crate.