feat: add download component

- Introduce a new download component to facilitate file downloads.
- Implement download handling in the header context, supporting data URLs.
- Add a test for the download functionality to ensure correct behavior.

see #996

Author: lovasoa

CHANGELOG.md

@@ -10,6 +10,7 @@
    - This allows you to trigger modals from any other component, including tables, maps, forms, lists and more.
    - Since modals have their own url inside the page, you can now link to a modal from another page, and if you refresh a page while the modal is open, the modal will stay open.
    - modals now have an `open` parameter to open the modal automatically when the page is loaded.
+ - New [download](https://sql-page.com/component.sql?component=download) component to let the user download files. The files may be stored as BLOBs in the database, local files on the server, or may be fetched from a different server.
 
 ## v0.36.1
  - Fix regression introduced in v0.36.0: PostgreSQL money values showed as 0.0

examples/official-site/sqlpage/migrations/24_read_file_as_data_url.sql

@@ -12,8 +12,9 @@ VALUES (
     'Returns a [data URL](https://developer.mozilla.org/en-US/docs/Web/HTTP/Basics_of_HTTP/Data_URIs)
 containing the contents of the given file.
 
-The file path is relative to the `web root` directory, which is the directory from which your website is served
-(not necessarily the directory SQLPage is launched from).
+The file path is relative to the `web root` directory, which is the directory from which your website is served.
+By default, this is the directory SQLPage is launched from, but you can change it
+with the `web_root` [configuration option](https://github.com/sqlpage/SQLPage/blob/main/configuration.md).
 
 If the given argument is null, the function will return null.
 

examples/official-site/sqlpage/migrations/65_download.sql

@@ -0,0 +1,120 @@
+-- Insert the download component into the component table
+INSERT INTO
+    component (name, description, icon, introduced_in_version)
+VALUES
+    (
+        'download',
+        '
+The *download* component lets a page immediately return a file to the visitor.
+
+Instead of showing a web page, it sends the file''s bytes as the whole response,
+so it should be used **at the very top of your SQL page** (before the shell or any other page contents).
+It is an error to use this component after another component that would display content.
+
+How it works in simple terms:
+- You provide the file content using a [data URL](https://developer.mozilla.org/en-US/docs/Web/HTTP/Basics_of_HTTP/Data_URIs).
+A data URL is just a text string that contains both the file type and the actual data.
+- Optionally, you provide a "filename" so the browser shows a proper Save As name.
+If you do not provide a filename, many browsers will try to display the file inline (for example images or JSON), depending on the content type.
+- You link to the page that uses the download component from another page, using the [button](/components?component=button) component for example.
+
+What is a data URL?
+- It looks like this: `data:[content-type][;base64],DATA`
+- Examples:
+  - Plain text (URL-encoded): `data:text/plain,Hello%20world`
+  - JSON (URL-encoded): `data:application/json,%7B%22message%22%3A%22Hi%22%7D`
+  - Binary data (Base64): `data:application/octet-stream;base64,SGVsbG8h`
+
+Tips:
+- Use URL encoding when you have textual data. You can use [`sqlpage.url_encode(source_text)`](/functions?function=url_encode) to encode the data.
+- Use Base64 when you have binary data (images, PDFs, or content that may include special characters).
+- Use [`sqlpage.read_file_as_data_url(file_path)`](/functions?function=read_file_as_data_url) to read a file from the server and return it as a data URL.
+
+> Keep in mind that large files are better served from disk or object storage. Data URLs are best for small to medium files.
+There is a big performance penalty for loading large files as data URLs, so it is not recommended.
+',
+        'download',
+        '0.37.0'
+    );
+
+-- Insert the parameters for the download component into the parameter table
+INSERT INTO
+    parameter (
+        component,
+        name,
+        description,
+        type,
+        top_level,
+        optional
+    )
+VALUES
+    (
+        'download',
+        'data_url',
+        'The file content to send, written as a data URL (for example: data:text/plain,Hello%20world or data:application/octet-stream;base64,SGVsbG8h). The part before the comma declares the content type and whether the data is base64-encoded. The part after the comma is the actual data.',
+        'TEXT',
+        TRUE,
+        FALSE
+    ),
+    (
+        'download',
+        'filename',
+        'The suggested name of the file to save (for example: report.csv). When set, the browser will download the file as an attachment with this name. When omitted, many browsers may try to display the file inline depending on its content type.',
+        'TEXT',
+        TRUE,
+        TRUE
+    );
+
+-- Insert usage examples of the download component into the example table
+INSERT INTO
+    example (component, description)
+VALUES
+    (
+        'download',
+        '
+## Simple plain text file
+Download a small text file. The content is URL-encoded (spaces become %20).
+
+```sql
+select
+    ''download'' as component,
+    ''data:text/plain,Hello%20SQLPage%20world!'' as data_url,
+    ''hello.txt'' as filename;
+```
+'
+    ),
+    (
+        'download',
+        '
+## Download a PDF file from the server
+
+Download a PDF file with the proper content type so PDF readers recognize it.
+Uses [`sqlpage.read_file_as_data_url(file_path)`](/functions?function=read_file_as_data_url) to read the file from the server.
+
+```sql
+select
+    ''download'' as component,
+    ''report.pdf'' as filename,
+    sqlpage.read_file_as_data_url(''report.pdf'') as data_url;
+```
+'
+    ),
+    (
+        'download',
+        '
+## Serve an image stored as a BLOB in the database
+
+In PostgreSQL, you can use the [encode(bytes, format)](https://www.postgresql.org/docs/current/functions-binarystring.html#FUNCTION-ENCODE) function to encode the file content as Base64.
+
+```sql
+select
+    ''download'' as component,
+    ''data:'' || doc.mime_type || '';base64,'' || encode(doc.content::bytea, ''base64'') as data_url
+from document as doc
+where doc.id = $doc_id;
+```
+
+ - In Microsoft SQL Server, you can use the [BASE64_ENCODE(bytes)](https://learn.microsoft.com/en-us/sql/t-sql/functions/base64-encode-transact-sql) function to encode the file content as Base64.
+ - In MySQL and MariaDB, you can use the [TO_BASE64(str)](https://mariadb.com/docs/server/reference/sql-functions/string-functions/to_base64) function.
+'
+    );

src/render.rs

@@ -118,6 +118,7 @@ impl HeaderContext {
             Some(HeaderComponent::Csv) => self.csv(&data).await,
             Some(HeaderComponent::Cookie) => self.add_cookie(&data).map(PageContext::Header),
             Some(HeaderComponent::Authentication) => self.authentication(data).await,
+            Some(HeaderComponent::Download) => self.download(&data),
             None => self.start_body(data).await,
         }
     }
@@ -327,6 +328,38 @@ impl HeaderContext {
         Ok(PageContext::Close(http_response))
     }
 
+    fn download(mut self, options: &JsonValue) -> anyhow::Result<PageContext> {
+        if let Some(filename) = get_object_str(options, "filename") {
+            self.response.insert_header((
+                header::CONTENT_DISPOSITION,
+                format!("attachment; filename=\"{filename}\""),
+            ));
+        }
+        let data_url = get_object_str(options, "data_url")
+            .with_context(|| "The download component requires a 'data_url' property")?;
+        let rest = data_url
+            .strip_prefix("data:")
+            .with_context(|| "Invalid data URL: missing 'data:' prefix")?;
+        let (mut content_type, data) = rest
+            .split_once(',')
+            .with_context(|| "Invalid data URL: missing comma")?;
+        let mut body_bytes: Cow<[u8]> = percent_encoding::percent_decode(data.as_bytes()).into();
+        if let Some(stripped) = content_type.strip_suffix(";base64") {
+            content_type = stripped;
+            body_bytes =
+                base64::Engine::decode(&base64::engine::general_purpose::STANDARD, &body_bytes)
+                    .with_context(|| "Invalid base64 data in data URL")?
+                    .into();
+        }
+        if !content_type.is_empty() {
+            self.response
+                .insert_header((header::CONTENT_TYPE, content_type));
+        }
+        Ok(PageContext::Close(
+            self.response.body(body_bytes.into_owned()),
+        ))
+    }
+
     async fn start_body(self, data: JsonValue) -> anyhow::Result<PageContext> {
         let html_renderer =
             HtmlRenderContext::new(self.app_state, self.request_context, self.writer, data)
@@ -1074,6 +1107,7 @@ enum HeaderComponent {
     Csv,
     Cookie,
     Authentication,
+    Download,
 }
 
 impl TryFrom<&str> for HeaderComponent {
@@ -1087,6 +1121,7 @@ impl TryFrom<&str> for HeaderComponent {
             "csv" => Ok(Self::Csv),
             "cookie" => Ok(Self::Cookie),
             "authentication" => Ok(Self::Authentication),
+            "download" => Ok(Self::Download),
             _ => Err(()),
         }
     }

tests/requests/mod.rs

@@ -77,6 +77,26 @@ async fn test_request_body_base64() -> actix_web::Result<()> {
     Ok(())
 }
 
+#[actix_web::test]
+async fn test_download_data_url() -> actix_web::Result<()> {
+    let req = get_request_to("/tests/requests/request_download_test.sql")
+        .await?
+        .to_srv_request();
+    let resp = main_handler(req).await?;
+
+    assert_eq!(resp.status(), StatusCode::OK);
+    let ct = resp.headers().get("content-type").unwrap();
+    assert_eq!(ct, "text/plain");
+    let content_disposition = resp.headers().get("content-disposition").unwrap();
+    assert_eq!(
+        content_disposition,
+        "attachment; filename=\"my text file.txt\""
+    );
+    let body = test::read_body(resp).await;
+    assert_eq!(&body, &b"Hello download!"[..]);
+    Ok(())
+}
+
 #[actix_web::test]
 async fn test_large_form_field_roundtrip() -> actix_web::Result<()> {
     let long_string = "a".repeat(123454);

tests/requests/request_download_test.sql

@@ -0,0 +1,6 @@
+select 'download' as component,
+       'data:text/plain;base64,SGVsbG8gZG93bmxvYWQh' as data_url,
+       'my text file.txt' as filename;
+
+
+

tests/sql_test_files/it_works_download_base64.sql

@@ -0,0 +1,2 @@
+-- "<!DOCTYPE html><body>It works !</body>" in base64
+select 'download' as component, 'data:text/html;base64,PCFET0NUWVBFIGh0bWw+PGJvZHk+SXQgd29ya3MgITwvYm9keT4K' as data_url;

tests/sql_test_files/it_works_download_raw.sql

@@ -0,0 +1,2 @@
+-- "<!DOCTYPE html><body>It works !</body>" percent encoded
+select 'download' as component, 'data:text/html,%3C!DOCTYPE%20html%3E%3Cbody%3EIt%20works%20!%3C%2Fbody%3E' as data_url;