make the headers field in sqlpage.fetch optional

fixes #805

CHANGELOG.md

@@ -17,6 +17,7 @@
  - This allows easily implementing autocomplete for form fields with a large number of possible options.
  - In the map component, add support for map pins with a description but no title.
 - Improved error messages when a parameter of a sqlpage function is invalid. Error traces used to be truncated, and made it hard to understand the exact cause of the error in some cases. In particular, calls to `sqlpage.fetch` would display an unhelpful error message when the HTTP request definition was invalid.
+- Make the `headers` field of the `sqlpage.fetch` function parameter optional. It defaults to sending a User-Agent header containing the SQLPage version.
 
 ## 0.32.1 (2025-01-03)
 

examples/official-site/sqlpage/migrations/40_fetch.sql

@@ -80,13 +80,13 @@ set api_results = sqlpage.fetch($request);
 # JSON parameter format
 
 The fetch function accepts either a URL string, or a JSON object with the following parameters:
+ - `url`: The URL to fetch. Required.
  - `method`: The HTTP method to use. Defaults to `GET`.
- - `url`: The URL to fetch.
- - `headers`: A JSON object with the headers to send.
- - `body`: The body of the request. If it is a JSON object, it will be sent as JSON. If it is a string, it will be sent as is.
+ - `headers`: A JSON object with the headers to send. Defaults to sending a User-Agent header containing the SQLPage version.
+ - `body`: The body of the request. If it is a JSON object, it will be sent as JSON. If it is a string, it will be sent as is. When omitted, no request body is sent.
  - `timeout_ms`: The maximum time to wait for the request, in milliseconds. Defaults to 5000.
- - `username`: Username for HTTP Basic Authentication. Introduced in version 0.33.0.
- - `password`: Password for HTTP Basic Authentication. Only used if username is provided. Introduced in version 0.33.0.
+ - `username`: Optional username for HTTP Basic Authentication. Introduced in version 0.33.0.
+ - `password`: Optional password for HTTP Basic Authentication. Only used if username is provided. Introduced in version 0.33.0.
 
 '
     );

src/webserver/database/sqlpage_functions/http_fetch_request.rs

@@ -4,20 +4,39 @@ use super::function_traits::BorrowFromStr;
 use std::borrow::Cow;
 
 type HeaderVec<'a> = Vec<(Cow<'a, str>, Cow<'a, str>)>;
+
+fn default_headers<'a>() -> HeaderVec<'a> {
+    vec![
+        (Cow::Borrowed("Accept"), Cow::Borrowed("*/*")),
+        (
+            Cow::Borrowed("User-Agent"),
+            Cow::Borrowed(concat!(
+                "SQLPage/v",
+                env!("CARGO_PKG_VERSION"),
+                " (+https://sql-page.com)"
+            )),
+        ),
+    ]
+}
+
 #[derive(serde::Deserialize, Debug)]
 #[serde(expecting = "an http request object, e.g. '{\"url\":\"http://example.com\"}'")]
 pub(super) struct HttpFetchRequest<'b> {
     #[serde(borrow)]
     pub url: Cow<'b, str>,
     #[serde(borrow)]
     pub method: Option<Cow<'b, str>>,
-    pub timeout_ms: Option<u64>,
-    #[serde(borrow, deserialize_with = "deserialize_map_to_vec_pairs")]
+    #[serde(
+        default = "default_headers",
+        borrow,
+        deserialize_with = "deserialize_map_to_vec_pairs"
+    )]
     pub headers: HeaderVec<'b>,
     pub username: Option<Cow<'b, str>>,
     pub password: Option<Cow<'b, str>>,
     #[serde(borrow)]
     pub body: Option<Cow<'b, serde_json::value::RawValue>>,
+    pub timeout_ms: Option<u64>,
 }
 
 fn deserialize_map_to_vec_pairs<'de, D: serde::Deserializer<'de>>(
@@ -53,7 +72,7 @@ impl<'a> BorrowFromStr<'a> for HttpFetchRequest<'a> {
             HttpFetchRequest {
                 url: s,
                 method: None,
-                headers: Vec::new(),
+                headers: default_headers(),
                 username: None,
                 password: None,
                 body: None,