error handling: improve visual presentation of error messages

- Updated error messages to be more user-friendly and visually appealing in the browser.
- Introduced a new method for retrieving static files from the cache.
- Improved error reporting for invalid UTF-8 encoding in SQL files.

Author: lovasoa

CHANGELOG.md

@@ -21,6 +21,7 @@
      from users;
      ```
  - When a sql file is saved with the wrong character encoding (not UTF8), SQLPage now displays a helpful error messages that points to exactly where in the file the problem is.
+ - More visual error messages: errors that occured before (such as file access issues) used to generate plain text messages that looked scary to non-technical users. All errors are now displayed nicely in the browser.
 
 ## v0.36.1
  - Fix regression introduced in v0.36.0: PostgreSQL money values showed as 0.0

sqlpage/templates/error.handlebars

@@ -13,9 +13,11 @@
         <div class="text-muted">
             <p>We are sorry, but an error occurred while generating this page. You should contact the site's
                 administrator.</p>
+            {{~#if description~}}
             <pre class="mt-2"><code class="sqlpage-error-description">{{description}}</code></pre>
+            {{~/if~}}
             {{#if backtrace}}
-            <details class="mt-2">
+            <details class="mt-2" open>
                 <summary>Backtrace</summary>
                 {{~#each backtrace~}}
                 <pre class="fs-6 mt-1 p-1 my-1"><code>{{this}}</code></pre>

src/file_cache.rs

@@ -108,6 +108,13 @@ impl<T: AsyncFromStrWithState> FileCache<T> {
         self.get_with_privilege(app_state, path, true).await
     }
 
+    pub fn get_static(&self, path: &Path) -> anyhow::Result<Arc<T>> {
+        self.static_files
+            .get(path)
+            .map(|cached| Arc::clone(&cached.content))
+            .ok_or_else(|| anyhow::anyhow!("File {} not found in static files", path.display()))
+    }
+
     /// Gets a file from the cache, or loads it from the file system if it's not there
     /// The privileged parameter is used to determine whether the access should be denied
     /// if the file is in the sqlpage/ config directory

src/filesystem.rs

@@ -78,8 +78,9 @@ impl FileSystem {
 
             let display_path = path.display();
             anyhow::format_err!(
-                "SQLPage expects all sql files to be encoded in UTF-8. \
-                The file \"{display_path}\" contains the following invalid UTF-8 byte sequence around line {line_num} character {bad_char_idx}: \"{bad_seq}\". \
+                "SQLPage expects all sql files to be encoded in UTF-8. \n\
+                In \"{display_path}\", around line {line_num} character {bad_char_idx}, the following invalid UTF-8 byte sequence was found: \n\
+                \"{bad_seq}\". \n\
                 Please convert the file to UTF-8.",
             )
         })

src/render.rs

@@ -131,7 +131,7 @@ impl HeaderContext {
         let data = json!({
             "component": "error",
             "description": err.to_string(),
-            "backtrace": get_backtrace(&err),
+            "backtrace": get_backtrace_as_strings(&err),
         });
         self.start_body(data).await
     }
@@ -391,16 +391,6 @@ async fn verify_password_async(
     .await?
 }
 
-fn get_backtrace(error: &anyhow::Error) -> Vec<String> {
-    let mut backtrace = vec![];
-    let mut source = error.source();
-    while let Some(s) = source {
-        backtrace.push(format!("{s}"));
-        source = s.source();
-    }
-    backtrace
-}
-
 fn get_object_str<'a>(json: &'a JsonValue, key: &str) -> Option<&'a str> {
     json.as_object()
         .and_then(|obj| obj.get(key))
@@ -781,7 +771,7 @@ impl<W: std::io::Write> HtmlRenderContext<W> {
             json!({
                 "query_number": self.current_statement,
                 "description": error.to_string(),
-                "backtrace": get_backtrace(error),
+                "backtrace": get_backtrace_as_strings(error),
                 "note": "You can hide error messages like this one from your users by setting the 'environment' configuration option to 'production'."
             })
         };
@@ -895,6 +885,16 @@ impl<W: std::io::Write> HtmlRenderContext<W> {
     }
 }
 
+pub(super) fn get_backtrace_as_strings(error: &anyhow::Error) -> Vec<String> {
+    let mut backtrace = vec![];
+    let mut source = error.source();
+    while let Some(s) = source {
+        backtrace.push(format!("{s}"));
+        source = s.source();
+    }
+    backtrace
+}
+
 struct HandlebarWriterOutput<W: std::io::Write>(W);
 
 impl<W: std::io::Write> handlebars::Output for HandlebarWriterOutput<W> {

src/templates.rs

@@ -110,24 +110,33 @@ impl AllTemplates {
         Ok(())
     }
 
+    fn template_path(name: &str) -> PathBuf {
+        let mut path: PathBuf =
+            PathBuf::with_capacity(TEMPLATES_DIR.len() + 1 + name.len() + ".handlebars".len());
+        path.push(TEMPLATES_DIR);
+        path.push(name);
+        path.set_extension("handlebars");
+        path
+    }
+
     pub async fn get_template(
         &self,
         app_state: &AppState,
         name: &str,
     ) -> anyhow::Result<Arc<SplitTemplate>> {
         use anyhow::Context;
-        let mut path: PathBuf =
-            PathBuf::with_capacity(TEMPLATES_DIR.len() + 1 + name.len() + ".handlebars".len());
-        path.push(TEMPLATES_DIR);
-        path.push(name);
-        path.set_extension("handlebars");
+        let path = Self::template_path(name);
         self.split_templates
             .get(app_state, &path)
             .await
             .with_context(|| format!("Unable to get the component '{name}'"))
     }
-}
 
+    pub fn get_static_template(&self, name: &str) -> anyhow::Result<Arc<SplitTemplate>> {
+        let path = Self::template_path(name);
+        self.split_templates.get_static(&path)
+    }
+}
 #[test]
 fn test_split_template() {
     let template = Template::compile(

src/webserver/error.rs

@@ -2,49 +2,93 @@
 
 use std::path::PathBuf;
 
+use crate::render::get_backtrace_as_strings;
 use crate::webserver::ErrorWithStatus;
 use crate::AppState;
 use actix_web::error::UrlencodedError;
 use actix_web::http::{header, StatusCode};
 use actix_web::{HttpRequest, HttpResponse};
 use actix_web::{HttpResponseBuilder, ResponseError};
+use handlebars::{Renderable, StringOutput};
+use serde_json::json;
+
+fn error_to_html_string(app_state: &AppState, err: &anyhow::Error) -> anyhow::Result<String> {
+    let mut out = StringOutput::new();
+    let shell_template = app_state.all_templates.get_static_template("shell")?;
+    let error_template = app_state.all_templates.get_static_template("error")?;
+    let registry = &app_state.all_templates.handlebars;
+    let shell_ctx = handlebars::Context::null();
+    let data = if app_state.config.environment.is_prod() {
+        json!(null)
+    } else {
+        json!({
+            "description": err.to_string(),
+            "backtrace": get_backtrace_as_strings(err),
+            "note": "You can hide error messages like this one from your users by setting the 'environment' configuration option to 'production'.",
+        })
+    };
+    let err_ctx = handlebars::Context::wraps(data)?;
+    let rc = &mut handlebars::RenderContext::new(None);
+
+    // Open the shell component
+    shell_template
+        .before_list
+        .render(registry, &shell_ctx, rc, &mut out)?;
+
+    // Open the error component
+    error_template
+        .before_list
+        .render(registry, &err_ctx, rc, &mut out)?;
+    // Close the error component
+    error_template
+        .after_list
+        .render(registry, &err_ctx, rc, &mut out)?;
+
+    // Close the shell component
+    shell_template
+        .after_list
+        .render(registry, &shell_ctx, rc, &mut out)?;
+
+    Ok(out.into_string()?)
+}
 
 fn anyhow_err_to_actix_resp(e: &anyhow::Error, state: &AppState) -> HttpResponse {
     let mut resp = HttpResponseBuilder::new(StatusCode::INTERNAL_SERVER_ERROR);
-    let mut body = "Sorry, but we were not able to process your request.\n\n".to_owned();
-    let env = state.config.environment;
-    if env.is_prod() {
-        body.push_str("Contact the administrator for more information. A detailed error message has been logged.");
-        log::error!("{e:#}");
-    } else {
-        use std::fmt::Write;
-        write!(
-            body,
-            "Below are detailed debugging information which may contain sensitive data. \n\
-        Set environment to \"production\" in the configuration file to hide this information. \n\n\
-        {e:?}"
-        )
-        .unwrap();
-    }
     resp.insert_header((
         header::CONTENT_TYPE,
         header::HeaderValue::from_static("text/plain; charset=utf-8"),
     ));
 
     if let Some(status_err @ &ErrorWithStatus { .. }) = e.downcast_ref() {
-        status_err
-            .error_response()
-            .set_body(actix_web::body::BoxBody::new(body))
+        status_err.error_response()
     } else if let Some(sqlx::Error::PoolTimedOut) = e.downcast_ref() {
         use rand::Rng;
         resp.status(StatusCode::TOO_MANY_REQUESTS)
             .insert_header((
                 header::RETRY_AFTER,
                 header::HeaderValue::from(rand::rng().random_range(1..=15)),
             ))
-            .body("The database is currently too busy to handle your request. Please try again later.\n\n".to_owned() + &body)
+            .body("The database is currently too busy to handle your request. Please try again later.".to_owned())
     } else {
-        resp.body(body)
+        match error_to_html_string(state, e) {
+            Ok(body) => {
+                resp.insert_header((
+                    header::CONTENT_TYPE,
+                    header::HeaderValue::from_static("text/html; charset=utf-8"),
+                ));
+                resp.body(body)
+            }
+            Err(second_err) => {
+                log::error!("Unable to render error: {e:#}");
+                resp.body(format!(
+                    "A second error occurred while rendering the error page: \n\n\
+                Initial error: \n\
+                {e:#}\n\n\
+                Second error: \n\
+                {second_err:#}"
+                ))
+            }
+        }
     }
 }
 

src/webserver/http.rs

@@ -275,7 +275,7 @@ async fn process_sql_request(
         .sql_file_cache
         .get_with_privilege(app_state, &sql_path, false)
         .await
-        .with_context(|| format!("Unable to get SQL file \"{}\"", sql_path.display()))
+        .with_context(|| format!("Unable to read SQL file \"{}\"", sql_path.display()))
         .map_err(|e| anyhow_err_to_actix(e, app_state))?;
     render_sql(req, sql_file).await
 }