Files

CHANGELOG.md

@@ -1,6 +1,28 @@
 # CHANGELOG.md
 
-## 0.16.1
+## unreleased
+
+### Uploads
+
+This release is all about a long awaited feature: file uploads.
+Your SQLPage website can now accept file uploads from users, store them either in a directory or directly in a database table.
+
+#### New functions
+
+##### Handle uploaded files
+
+ - [`sqlpage.uploaded_file_path`](https://sql.ophir.dev/functions.sql?function=uploaded_file_path#function) to get the temprary local path of a file uploaded by the user. This path will be valid until the end of the current request, and will be located in a temporary directory (customizable with `TMPDIR`). You can use [`sqlpage.exec`](https://sql.ophir.dev/functions.sql?function=exec#function) to operate on the file, for instance to move it to a permanent location.
+ - [`sqlpage.uploaded_file_mime_type`](https://sql.ophir.dev/functions.sql?function=uploaded_file_name#function) to get the type of file uploaded by the user. This is the MIME type of the file, such as `image/png` or `text/csv`. You can use this to easily check that the file is of the expected type before storing it.
+
+##### Read files
+
+These new functions are useful to read the content of a file uploaded by the user,
+but can also be used to read any file on the server.
+
+ - [`sqlpage.read_file_as_text`](https://sql.ophir.dev/functions.sql?function=read_file#function) reads the contents of a file on the server and returns a text string.
+ - [`sqlpage.read_file_as_data_url`](https://sql.ophir.dev/functions.sql?function=read_file#function) reads the contents of a file on the server and returns a [data URL](https://developer.mozilla.org/en-US/docs/Web/HTTP/Basics_of_HTTP/Data_URIs). This is useful to embed images directly in web pages, or make link
+
+## 0.16.1 (2023-11-22)
 
  - fix a bug where setting a variable to a non-string value would always set it to null
  - clearer debug logs (https://github.com/wooorm/markdown-rs/pull/92)

Cargo.toml

@@ -45,6 +45,8 @@ password-hash = "0.5.0"
 argon2 = "0.5.0"
 actix-web-httpauth = "0.8.0"
 rand = "0.8.5"
+actix-multipart = "0.6.1"
+base64 = "0.21.5"
 
 [build-dependencies]
 awc = { version = "3", features = ["rustls"] }

configuration.md

@@ -16,6 +16,7 @@ on a [JSON](https://en.wikipedia.org/wiki/JSON) file placed in `sqlpage/sqlpage.
 | `sqlite_extensions`                        |                              | An array of SQLite extensions to load, such as `mod_spatialite`          |
 | `web_root`                                | `.`                      | The root directory of the web server, where the `index.sql` file is located.          |
 | `allow_exec` | false | Allow usage of the `sqlpage.exec` function. Do this only if all users with write access to sqlpage query files and to the optional `sqlpage_files` table on the database are trusted. |
+| `max_uploaded_file_size` | 10485760 | Maximum size of uploaded files in bytes. Defaults to 10 MiB. |
 
 You can find an example configuration file in [`sqlpage/sqlpage.json`](./sqlpage/sqlpage.json).
 
@@ -28,6 +29,9 @@ but in uppercase.
 
 The environment variable name can optionally be prefixed with `SQLPAGE_`.
 
+Additionnally, when troubleshooting, you can set the [`RUST_LOG`](https://docs.rs/env_logger/latest/env_logger/#enabling-logging)
+environment variable to `sqlpage=debug` to get more detailed logs and see exactly what SQLPage is doing.
+
 ### Example
 
 ```bash

examples/official-site/examples/handle_picture_upload.sql

@@ -0,0 +1,5 @@
+select 'card' as component;
+select 'Your picture' as title;
+
+select 'debug' as component;
+select :my_file as file;

examples/official-site/sqlpage/migrations/01_documentation.sql

@@ -378,6 +378,22 @@ if your website has authenticated users that can perform sensitive actions throu
     {"name": "password", "label": "Password", "type": "password", "width": 6},
     {"name": "password_confirmation", "label": "Password confirmation", "type": "password", "width": 6},
     {"name": "terms", "label": "I accept the terms and conditions", "type": "checkbox", "required": true}
+    ]')),
+    ('form', '
+## File upload
+
+You can use the `file` type to allow the user to upload a file.
+The file will be uploaded to the server, and you will be able to access it using the
+[`sqlpage.uploaded_file_path`](functions.sql?function=uploaded_file_path#function) function.
+
+Here is how you could save the uploaded file to a table in the database:
+
+```sql
+INSERT INTO uploaded_file(name, data) VALUES(:filename, sqlpage.uploaded_file_data_url(:filename))
+```
+',
+    json('[{"component":"form", "title": "Upload a picture", "validate": "Upload", "action": "examples/handle_picture_upload.sql"}, 
+    {"name": "my_file", "type": "file", "accept": "image/png, image/jpeg",  "label": "Picture", "description": "Upload a nice picture", "required": true}
     ]'))
 ;
 

examples/official-site/sqlpage/migrations/23_uploaded_file_functions.sql

@@ -0,0 +1,99 @@
+-- Insert the 'variables' function into sqlpage_functions table
+INSERT INTO sqlpage_functions (
+    "name",
+    "introduced_in_version",
+    "icon",
+    "description_md"
+)
+VALUES (
+    'uploaded_file_path',
+    '0.17.0',
+    'upload',
+    'Returns the path to a temporary file containing the contents of an uploaded file.
+
+## Example: handling a picture upload
+
+### Making a form
+
+```sql
+select ''form'' as component, ''handle_picture_upload.sql'' as action;
+select ''myfile'' as name, ''file'' as type, ''Picture'' as label;
+select ''title'' as name, ''text'' as type, ''Title'' as label;
+```
+
+### Handling the form response
+
+In `handle_picture_upload.sql`, one can process the form results like this:
+
+```sql
+insert into pictures (title, path) values (:title, sqlpage.read_file_as_data_url(sqlpage.uploaded_file_path(''myfile'')));
+```
+'
+),
+(
+    'uploaded_file_mime_type',
+    '0.17.0',
+    'file-settings',
+    'Returns the MIME type of an uploaded file.
+
+## Example: handling a picture upload
+
+When letting the user upload a picture, you may want to check that the uploaded file is indeed an image.
+
+```sql
+select ''redirect'' as component, 
+       ''invalid_file.sql'' as link
+where sqlpage.uploaded_file_mime_type(''myfile'') not like ''image/%'';
+```
+
+In `invalid_file.sql`, you can display an error message to the user:
+
+```sql
+select ''alert'' as component, ''Error'' as title,
+    ''Invalid file type'' as description,
+    ''alert-circle'' as icon, ''red'' as color;
+```
+
+## Example: white-listing file types
+
+You could have a database table containing the allowed MIME types, and check that the uploaded file is of one of those types:
+
+```sql
+select ''redirect'' as component, 
+       ''invalid_file.sql'' as link
+where sqlpage.uploaded_file_mime_type(''myfile'') not in (select mime_type from allowed_mime_types);
+```
+'
+);
+
+INSERT INTO sqlpage_function_parameters (
+    "function",
+    "index",
+    "name",
+    "description_md",
+    "type"
+)
+VALUES (
+    'uploaded_file_path',
+    1,
+    'name',
+    'Name of the file input field in the form.',
+    'TEXT'
+), 
+(
+    'uploaded_file_path',
+    2,
+    'allowed_mime_type',
+    'Makes the function return NULL if the uploaded file is not of the specified MIME type.
+    If omitted, any MIME type is allowed.
+    This makes it possible to restrict the function to only accept certain file types.',
+    'TEXT'
+),
+(
+    'uploaded_file_mime_type',
+    1,
+    'name',
+    'Name of the file input field in the form.',
+    'TEXT'
+)
+;