new sqlpage functions to read HTTP request body

sqlpage.request_body and sqlpage.request_body_base64

closes #316

Author: lovasoa

examples/official-site/sqlpage/migrations/55_request_body.sql

@@ -0,0 +1,135 @@
+INSERT INTO sqlpage_functions (
+        "name",
+        "introduced_in_version",
+        "icon",
+        "description_md"
+    )
+VALUES (
+        'request_body',
+        '0.33.0',
+        'http-post',
+        'Returns the raw request body as a string.
+
+A client (like a web browser, mobile app, or another server) can send information to your server in the request body.
+This function allows you to read that information in your SQL code,
+in order to create or update a resource in your database for instance.
+
+The request body is commonly used when building **REST APIs** (machines-to-machines interfaces)
+that receive data from the client.
+
+This is especially useful in:
+- `POST` and `PUT` requests for creating or updating resources in your database
+- Any API endpoint that needs to receive complex data
+
+### Example: Building a REST API
+
+Here''s an example of building an API endpoint that receives a json object,
+and inserts it into a database.
+
+#### `api/create_user.sql`
+```sql
+-- Get the raw JSON body
+set user_data = sqlpage.request_body();
+
+-- Insert the user into database
+with parsed_data as (
+  select 
+    json_extract($user_data, ''$.name'') as name,
+    json_extract($user_data, ''$.email'') as email
+)
+insert into users (name, email)
+select name, email from parsed_data;
+
+-- Return success response
+select ''json'' as component,
+       json_object(
+         ''status'', ''success'',
+         ''message'', ''User created successfully''
+       ) as contents;
+```
+
+### Testing the API
+
+You can test this API using curl:
+```bash
+curl -X POST http://localhost:8080/api/create_user \
+  -H "Content-Type: application/json" \
+  -d ''{"name": "John", "email": "[email protected]"}''
+```
+
+## Special cases
+
+### NULL
+
+This function returns NULL if:
+ - There is no request body
+ - The request content type is `application/x-www-form-urlencoded` or `multipart/form-data` 
+   (in these cases, use [`sqlpage.variables(''post'')`](?function=variables) instead)
+
+### Binary data
+
+If the request body is not valid text encoded in UTF-8,
+invalid characters are replaced with the Unicode replacement character `�` (U+FFFD).
+
+If you need to handle binary data,
+use [`sqlpage.request_body_base64()`](?function=request_body_base64) instead.
+'
+    );
+
+INSERT INTO sqlpage_functions (
+        "name",
+        "introduced_in_version",
+        "icon",
+        "description_md"
+    )
+VALUES (
+        'request_body_base64',
+        '0.33.0',
+        'photo-up',
+        'Returns the raw request body encoded in base64. This is useful when receiving binary data or when you need to handle non-text content in your API endpoints.
+
+### What is Base64?
+
+Base64 is a way to encode binary data (like images or files) into text that can be safely stored and transmitted. This function automatically converts the incoming request body into this format.
+
+### Example: Handling Binary Data in an API
+
+This example shows how to receive and process an image uploaded directly in the request body:
+
+```sql
+-- Assuming this is api/upload_image.sql
+-- Client would send a POST request with the raw image data
+
+-- Get the base64-encoded image data
+set image_data = sqlpage.request_body_base64();
+
+-- Store the image data in the database
+insert into images (data, uploaded_at)
+values ($image_data, current_timestamp);
+
+-- Return success response
+select ''json'' as component,
+       json_object(
+         ''status'', ''success'',
+         ''message'', ''Image uploaded successfully''
+       ) as contents;
+```
+
+You can test this API using curl:
+```bash
+curl -X POST http://localhost:8080/api/upload_image.sql \
+  -H "Content-Type: application/octet-stream" \
+  --data-binary "@/path/to/image.jpg"
+```
+
+This is particularly useful when:
+- Working with binary data (images, files, etc.)
+- The request body contains non-UTF8 characters
+- You need to pass the raw body to another system that expects base64
+
+> Note: Like [`sqlpage.request_body()`](?function=request_body), this function returns NULL if:
+> - There is no request body
+> - The request content type is `application/x-www-form-urlencoded` or `multipart/form-data`
+>   (in these cases, use [`sqlpage.variables(''post'')`](?function=variables) instead)
+'
+    );

src/webserver/database/sqlpage_functions/functions.rs

@@ -46,6 +46,8 @@ super::function_definition_macro::sqlpage_functions! {
 
     variables((&RequestInfo), get_or_post: Option<Cow<str>>);
     version();
+    request_body((&RequestInfo));
+    request_body_base64((&RequestInfo));
 }
 
 /// Returns the password from the HTTP basic auth header, if present.
@@ -604,3 +606,26 @@ async fn variables<'a>(
 async fn version() -> &'static str {
     env!("CARGO_PKG_VERSION")
 }
+
+/// Returns the raw request body as a string.
+/// If the request body is not valid UTF-8, invalid characters are replaced with the Unicode replacement character.
+/// Returns NULL if there is no request body or if the request content type is
+/// application/x-www-form-urlencoded or multipart/form-data (in this case, the body is accessible via the `post_variables` field).
+async fn request_body(request: &RequestInfo) -> Option<String> {
+    let raw_body = request.raw_body.as_ref()?;
+    Some(String::from_utf8_lossy(raw_body).to_string())
+}
+
+/// Returns the raw request body encoded in base64.
+/// Returns NULL if there is no request body or if the request content type is
+/// application/x-www-form-urlencoded or multipart/form-data (in this case, the body is accessible via the `post_variables` field).
+async fn request_body_base64(request: &RequestInfo) -> Option<String> {
+    let raw_body = request.raw_body.as_ref()?;
+    let mut base64_string = String::with_capacity((raw_body.len() * 4 + 2) / 3);
+    base64::Engine::encode_string(
+        &base64::engine::general_purpose::STANDARD,
+        raw_body,
+        &mut base64_string,
+    );
+    Some(base64_string)
+}

src/webserver/http_request_info.rs

@@ -38,6 +38,7 @@ pub struct RequestInfo {
     pub basic_auth: Option<Basic>,
     pub app_state: Arc<AppState>,
     pub clone_depth: u8,
+    pub raw_body: Option<Vec<u8>>,
 }
 
 impl RequestInfo {
@@ -56,6 +57,7 @@ impl RequestInfo {
             basic_auth: self.basic_auth.clone(),
             app_state: self.app_state.clone(),
             clone_depth: self.clone_depth + 1,
+            raw_body: self.raw_body.clone(),
         }
     }
 }
@@ -77,7 +79,8 @@ pub(crate) async fn extract_request_info(
     let method = http_req.method().clone();
     let protocol = http_req.connection_info().scheme().to_string();
     let config = &app_state.config;
-    let (post_variables, uploaded_files) = extract_post_data(http_req, payload, config).await?;
+    let (post_variables, uploaded_files, raw_body) =
+        extract_post_data(http_req, payload, config).await?;
     let headers = req.headers().iter().map(|(name, value)| {
         (
             name.to_string(),
@@ -112,28 +115,36 @@ pub(crate) async fn extract_request_info(
         app_state,
         protocol,
         clone_depth: 0,
+        raw_body,
     })
 }
 
 async fn extract_post_data(
     http_req: &mut actix_web::HttpRequest,
     payload: &mut actix_web::dev::Payload,
     config: &crate::app_config::AppConfig,
-) -> anyhow::Result<(Vec<(String, String)>, Vec<(String, TempFile)>)> {
+) -> anyhow::Result<(
+    Vec<(String, String)>,
+    Vec<(String, TempFile)>,
+    Option<Vec<u8>>,
+)> {
     let content_type = http_req
         .headers()
         .get(&CONTENT_TYPE)
         .map(AsRef::as_ref)
         .unwrap_or_default();
     if content_type.starts_with(b"application/x-www-form-urlencoded") {
         let vars = extract_urlencoded_post_variables(http_req, payload).await?;
-        Ok((vars, Vec::new()))
+        Ok((vars, Vec::new(), None))
     } else if content_type.starts_with(b"multipart/form-data") {
-        extract_multipart_post_data(http_req, payload, config).await
+        let (vars, files) = extract_multipart_post_data(http_req, payload, config).await?;
+        Ok((vars, files, None))
     } else {
-        let ct_str = String::from_utf8_lossy(content_type);
-        log::debug!("Not parsing POST data from request without known content type {ct_str}");
-        Ok((Vec::new(), Vec::new()))
+        let body = actix_web::web::Bytes::from_request(http_req, payload)
+            .await
+            .map(|bytes| bytes.to_vec())
+            .unwrap_or_default();
+        Ok((Vec::new(), Vec::new(), Some(body)))
     }
 }
 

tests/index.rs

@@ -803,6 +803,80 @@ async fn test_routing_with_prefix() {
     assert_eq!(location.to_str().unwrap(), "/prefix/");
 }
 
+#[actix_web::test]
+async fn test_request_body() -> actix_web::Result<()> {
+    let req = get_request_to("/tests/request_body_test.sql")
+        .await?
+        .insert_header(("content-type", "text/plain"))
+        .set_payload("Hello, world!")
+        .to_srv_request();
+    let resp = main_handler(req).await?;
+
+    assert_eq!(resp.status(), StatusCode::OK);
+    let body = test::read_body(resp).await;
+    let body_str = String::from_utf8(body.to_vec()).unwrap();
+    assert!(
+        body_str.contains("Hello, world!"),
+        "{body_str}\nexpected to contain: Hello, world!"
+    );
+
+    // Test with form data - should return NULL
+    let req = get_request_to("/tests/request_body_test.sql")
+        .await?
+        .insert_header(("content-type", "application/x-www-form-urlencoded"))
+        .set_payload("key=value")
+        .to_srv_request();
+    let resp = main_handler(req).await?;
+
+    assert_eq!(resp.status(), StatusCode::OK);
+    let body = test::read_body(resp).await;
+    let body_str = String::from_utf8(body.to_vec()).unwrap();
+    assert!(
+        body_str.contains("NULL"),
+        "{body_str}\nexpected NULL for form data"
+    );
+    Ok(())
+}
+
+#[actix_web::test]
+async fn test_request_body_base64() -> actix_web::Result<()> {
+    let binary_data = (0u8..=255u8).collect::<Vec<_>>();
+    let expected_base64 =
+        base64::Engine::encode(&base64::engine::general_purpose::STANDARD, &binary_data);
+
+    let req = get_request_to("/tests/request_body_base64_test.sql")
+        .await?
+        .insert_header(("content-type", "application/octet-stream"))
+        .set_payload(binary_data)
+        .to_srv_request();
+    let resp = main_handler(req).await?;
+
+    assert_eq!(resp.status(), StatusCode::OK);
+    let body = test::read_body(resp).await;
+    let body_str = String::from_utf8(body.to_vec()).unwrap();
+    assert!(
+        body_str.contains(&expected_base64),
+        "{body_str}\nexpected to contain base64: {expected_base64}"
+    );
+
+    // Test with form data - should return NULL
+    let req = get_request_to("/tests/request_body_base64_test.sql")
+        .await?
+        .insert_header(("content-type", "application/x-www-form-urlencoded"))
+        .set_payload("key=value")
+        .to_srv_request();
+    let resp = main_handler(req).await?;
+
+    assert_eq!(resp.status(), StatusCode::OK);
+    let body = test::read_body(resp).await;
+    let body_str = String::from_utf8(body.to_vec()).unwrap();
+    assert!(
+        body_str.contains("NULL"),
+        "{body_str}\nexpected NULL for form data"
+    );
+    Ok(())
+}
+
 async fn get_request_to_with_data(
     path: &str,
     data: actix_web::web::Data<AppState>,

tests/request_body_base64_test.sql

@@ -0,0 +1,2 @@
+select 'shell-empty' as component,
+    coalesce(sqlpage.request_body_base64(), 'NULL') as html; 

tests/request_body_test.sql

@@ -0,0 +1,2 @@
+select 'shell-empty' as component,
+    coalesce(sqlpage.request_body(), 'NULL') as html;