docs and tests

Author: lovasoa

examples/official-site/sqlpage/migrations/57_client_ip.sql

@@ -0,0 +1,46 @@
+INSERT INTO
+        sqlpage_functions (
+                "name",
+                "introduced_in_version",
+                "icon",
+                "description_md"
+        )
+VALUES
+        (
+                'client_ip',
+                '0.33.0',
+                'network',
+                'Returns the IP address of the client making the HTTP request.
+
+### Example
+
+```sql
+insert into connection_log (client_ip) values (sqlpage.client_ip());
+```
+
+### Details
+
+The function returns:
+- The IP address of the client as a string
+- `null` if the client IP cannot be determined (e.g., when serving through a Unix socket)
+
+### ⚠️ Important Notes for Production Use
+
+When running behind a reverse proxy (e.g., Nginx, Apache, Cloudflare):
+- This function will return the IP address of the reverse proxy, not the actual client
+- To get the real client IP, use [`sqlpage.header`](?function=header): `sqlpage.header(''x-forwarded-for'')` or `sqlpage.header(''x-real-ip'')`
+  - The exact header name depends on your reverse proxy configuration
+
+Example with reverse proxy:
+```sql
+-- Choose the appropriate header based on your setup
+select coalesce(
+    sqlpage.header(''x-forwarded-for''),
+    sqlpage.header(''x-real-ip''),
+    sqlpage.client_ip()
+) as real_client_ip;
+```
+
+For security-critical applications, ensure your reverse proxy is properly configured to set and validate these headers.
+'
+        );

src/webserver/database/sqlpage_functions/functions.rs

@@ -16,6 +16,7 @@ super::function_definition_macro::sqlpage_functions! {
     basic_auth_password((&RequestInfo));
     basic_auth_username((&RequestInfo));
 
+    client_ip((&RequestInfo));
     cookie((&RequestInfo), name: Cow<str>);
     current_working_directory();
 
@@ -634,3 +635,7 @@ async fn request_body_base64(request: &RequestInfo) -> Option<String> {
 async fn headers(request: &RequestInfo) -> String {
     serde_json::to_string(&request.headers).unwrap_or_default()
 }
+
+async fn client_ip(request: &RequestInfo) -> Option<String> {
+    Some(request.client_ip?.to_string())
+}

tests/sql_test_files/it_works_client_ip.sql

@@ -0,0 +1,4 @@
+select 'text' as component,
+    case when sqlpage.client_ip() is null then 'It works !'
+        else 'It failed ! Got: ' || sqlpage.client_ip()
+    end as contents;