charon_error/submit/

gitlab_error_report.rs

//! GitLab issue submission for error reports.
//!
//! Generates pre-filled GitLab issue URLs from [`ErrorReport`]s and
//! progressively trims content to stay within URL length limits.
//! Configure via [`GitLabERGlobalSettings`].

use crate::{
    ErrorFmt, ErrorFmtLoD, ErrorFmtSettings, ErrorReport, GlobalSettings, IndentationStyle,
    LinkDebugIde, ResultExt, StringError, SubmitErrorReport,
};
use colored::Colorize;
use std::sync::{OnceLock, RwLock, RwLockReadGuard};
use url::{Url, form_urlencoded};

/// GitLab implementation of [`SubmitErrorReport`].
///
/// Generates pre-filled GitLab issue URLs from error reports. Before use,
/// call [`GlobalSettings::set_global_settings`] once at application startup.
///
/// # Example
///
/// ```rust,no_run
/// use charon_error::prelude::*;
/// use charon_error::prelude::gitlab_er::*;
///
/// GitLabERGlobalSettings::set_global_settings(GitLabERGlobalSettings {
///     domain: "gitlab.com".to_owned(),
///     project_path: "my-group/my-project".to_owned(),
///     ..Default::default()
/// }).unwrap_error();
/// ```
///
/// Example Output:
/// ```text
/// PANIC: A panic occurred during execution.
/// * Message: 'Error: `Called `ResultExt::unwrap_error()` on an `Err` value`'
/// * Path: 'src/main.rs:72:21'
/// PANIC: The application encountered an error it could not recover from.
/// {
///   last_error: 'Error: `Called `ResultExt::unwrap_error()` on an `Err` value`',
///   unique_id: '1nVBRnzAXYpzYCgAUp1i',
///   frames: [
///     {
///       message: 'No such file or directory (os error 2)',
///       source_location: src/cli/config.rs:15:10,
///       span_trace: [
///         charon_demo::cli::config::read_config at (src/cli/config.rs:7:0),
///         charon_demo::cli::start_server at (src/cli.rs:82:0),
///         charon_demo::cli::start at (src/cli.rs:35:0),
///       ],
///       attachments: {},
///       date_time: 2026-03-01T00:11:13.137896643+00:00,
///     },
///     {
///       message: 'The config file failed to load correctly.',
///       source_location: src/cli/config.rs:15:10,
///       span_trace: [
///         charon_demo::cli::config::read_config at (src/cli/config.rs:7:0),
///         charon_demo::cli::start_server at (src/cli.rs:82:0),
///         charon_demo::cli::start at (src/cli.rs:35:0),
///       ],
///       attachments: {
///         file_path: '../config.toml',
///       },
///       date_time: 2026-03-01T00:11:13.137998242+00:00,
///     },
///     {
///       message: 'Error: `Called `ResultExt::unwrap_error()` on an `Err` value`',
///       source_location: src/main.rs:72:21,
///       span_trace: [],
///       attachments: {},
///       date_time: 2026-03-01T00:11:13.138030402+00:00,
///     },
///   ],
/// }
/// ┌──────────────────────────┐
/// │  Open/Submit Bug Report │
/// └──────────────────────────┘
/// ```
/// For release build see: [Panic Output in Release](docs/images/panic_output_release.png)
#[derive(Debug, Clone)]
pub struct GitLabErrorReport<'a> {
    /// Reference to the error report being submitted.
    pub error_report: &'a ErrorReport,
}

impl<'a> SubmitErrorReport<'a> for GitLabErrorReport<'a> {
    fn new(error: &'a ErrorReport) -> Self {
        GitLabErrorReport {
            error_report: error,
        }
    }

    fn get_error_report(&self) -> &ErrorReport {
        self.error_report
    }

    fn get_title(&self) -> String {
        self.error_report.get_last_error_title()
    }

    fn create_message(&self) -> Result<String, ErrorReport> {
        let step1 = "Step 1".yellow();
        let step2 = "Step 2".yellow();
        let bug_report_stdout = {
            let settings = GitLabERGlobalSettings::get_global_settings()?;
            let display_parts = ReportPartEnabled::display_report();
            let format_settings = settings.release_format_settings_stderr;

            self.create_new_bug_report(&settings, &display_parts, &format_settings)
        }?;
        Ok(format!(
            "Panic Info:\n{}\n\
            Please report this error. Issue title: `{}`\n\
            \t- {step1}: Check if error report already exists: {}\n\
            \t- {step2}: Report issue (if it does not already exists):\n\
            \t- Open Pre-created Report Link: \n---\n{}\n----\n",
            bug_report_stdout,
            self.get_title().cyan().bold(),
            self.check_existing_reports()?.to_string().green(),
            self.create_submit_url()?.to_string().green(),
        ))
    }

    fn create_bug_report(&self) -> Result<String, ErrorReport> {
        let settings = GitLabERGlobalSettings::get_global_settings()?;
        let display_parts = ReportPartEnabled::display_report();
        let format_settings = ErrorFmtSettings {
            level_of_detail: ErrorFmtLoD::SubmitReport,
            frame_limit: None,
            enable_color: false,
            link_format: LinkDebugIde::NoLink,
            indentation_style: IndentationStyle::Tab,
            skip_first_indentations: 2,
            ..Default::default()
        };

        self.create_new_bug_report(&settings, &display_parts, &format_settings)
    }

    fn create_submit_url_limited(&self, max_length: usize) -> Result<Url, ErrorReport> {
        let settings = GitLabERGlobalSettings::get_global_settings()?;
        let url_char_limit = std::cmp::min(max_length, settings.url_char_limit);

        // Get size of smallest report.
        let minimal_link_parts = ReportPartEnabled::disable_all();
        let minimal_url = self.create_new_submit_url(&settings, &minimal_link_parts)?;
        if minimal_url.to_string().len() > url_char_limit {
            tracing::warn!(
                limit = url_char_limit,
                size = minimal_url.to_string().len(),
                "Minimal URL is already bigger then URL Limit",
            );
            return Ok(minimal_url);
        }

        // Start with all parts enabled (and remove if to long)
        let mut link_parts = ReportPartEnabled::default();

        // Section 1: All
        let mut url = self.create_new_submit_url(&settings, &link_parts)?;
        if url.to_string().len() <= url_char_limit {
            return Ok(url);
        } else {
            // Remove part of message
            tracing::trace!(
                url_length = url.to_string().len(),
                limit = url_char_limit,
                "URL to Long, Removing 'Steps' from Error Report URL."
            );
            link_parts.add_steps = false;
        }

        // Section 2: All - Steps
        url = self.create_new_submit_url(&settings, &link_parts)?;
        if url.to_string().len() <= url_char_limit {
            return Ok(url);
        } else {
            // Remove part of message
            tracing::trace!(
                url_length = url.to_string().len(),
                limit = url_char_limit,
                "URL to Long, Removing 'Backtrace' from Error Report URL."
            );
            link_parts.add_backtrace = false;
        }

        // Section 3: All - Steps - Backtrace
        url = self.create_new_submit_url(&settings, &link_parts)?;
        if url.to_string().len() <= url_char_limit {
            return Ok(url);
        }

        // Section 4: All - Steps - Backtrace - Remove Some ErrorFrames
        let mut error_frame_count = std::cmp::min(20, self.error_report.frames.len() - 1);
        while error_frame_count > 0 && url.to_string().len() > url_char_limit {
            link_parts.frame_limit = Some(error_frame_count);
            url = self.create_new_submit_url(&settings, &link_parts)?;
            tracing::trace!(
                url_length = url.to_string().len(),
                limit = url_char_limit,
                error_frame_count = error_frame_count,
                "URL to Long, Removing Some ErrorFrames from Error Report URL."
            );
            // URL is small enough
            if url.to_string().len() <= url_char_limit {
                return Ok(url);
            }
            error_frame_count -= 1;
        }

        // Section 5: Just display 1 Frame.
        link_parts.frame_limit = Some(1);
        let url = self.create_new_submit_url(&settings, &link_parts)?;
        if url.to_string().len() > url_char_limit {
            tracing::error!(
                url_length = url.to_string().len(),
                limit = url_char_limit,
                "ErrorReport even adding 1 ErrorFrame to URL will go over URL Limit."
            );
        }
        Ok(url)
    }

    fn create_submit_url(&self) -> Result<Url, ErrorReport> {
        self.create_submit_url_limited(usize::MAX)
    }

    fn check_existing_reports(&self) -> Result<Url, ErrorReport> {
        let settings = GitLabERGlobalSettings::get_global_settings()?;
        let search_title: String = form_urlencoded::Serializer::new(String::new())
            .append_pair(
                "search",
                &Self::truncate_string(self.get_title(), settings.title_char_limit),
            )
            .finish();
        Ok(Url::parse(&format!(
            "https://{domain}/{project_path}/-/issues/?sort=created_date&state=all&in=TITLE&{search_title}",
            domain = settings.domain,
            project_path = settings.project_path,
            search_title = search_title,
        ))?)
    }

    fn validate_settings(&self) -> Result<(), ErrorReport> {
        if !GitLabERGlobalSettings::is_set() {
            Err(StringError::new(
                "GitLabERGlobalSettings has not been set, this could create runtime issues.",
            )
            .into())
        } else {
            Ok(())
        }
    }
}

/// Controls which sections are included in a GitLab issue report.
///
/// Used internally to progressively strip content when the URL exceeds
/// length limits.
#[derive(Debug, Clone)]
pub struct ReportPartEnabled {
    /// Include "Steps to reproduce" section.
    pub add_steps: bool,
    /// Include the backtrace section.
    pub add_backtrace: bool,
    /// Include the error summary section.
    pub add_summary: bool,
    /// Limit the number of error frames (None = unlimited).
    pub frame_limit: Option<usize>,
    /// Wrap content in GitLab-specific HTML (details/summary tags, comments).
    pub enable_gitlab_syntax: bool,
}

impl ReportPartEnabled {
    fn disable_all() -> Self {
        Self {
            add_steps: false,
            add_backtrace: false,
            add_summary: false,
            frame_limit: Some(0),
            enable_gitlab_syntax: true,
        }
    }

    fn display_report() -> Self {
        Self {
            add_steps: false,
            add_backtrace: true,
            add_summary: true,
            frame_limit: None,
            enable_gitlab_syntax: false,
        }
    }
}

impl Default for ReportPartEnabled {
    fn default() -> Self {
        Self {
            add_steps: true,
            add_backtrace: true,
            add_summary: true,
            frame_limit: None,
            enable_gitlab_syntax: true,
        }
    }
}

impl<'a> GitLabErrorReport<'a> {
    fn gitlab_syntax<S: Into<String> + Default>(text: S, enabled_parts: &ReportPartEnabled) -> S {
        if enabled_parts.enable_gitlab_syntax {
            text
        } else {
            S::default()
        }
    }

    fn create_new_bug_report(
        &self,
        settings: &RwLockReadGuard<'static, GitLabERGlobalSettings>,
        enabled_parts: &ReportPartEnabled,
        format_settings: &ErrorFmtSettings,
    ) -> Result<String, ErrorReport> {
        let reproduce = if enabled_parts.add_steps {
            "## Reproduce:\n\
            Steps to recreate this issue:\n\
            1. ...\n\
            2. ...\n\n"
        } else {
            ""
        };
        let backtrace = if enabled_parts.add_backtrace {
            let backtrace_string = self
                .error_report
                .frames
                .last()
                .unwrap_error()
                .create_backtrace_string();
            format!(
                "### Backtrace:\n\
                {start_summary}\
                ```\n\
                {backtrace}\n\
                ```\n\n\
                {end_summary}",
                start_summary = Self::gitlab_syntax(
                    "<details><summary markdown=\"span\">Backtrace</summary>\n\n",
                    enabled_parts
                ),
                end_summary = Self::gitlab_syntax("</details>\n\n", enabled_parts),
                backtrace = backtrace_string,
            )
        } else {
            "".to_owned()
        };

        let summary = if enabled_parts.add_summary {
            let mut format_settings = *format_settings;
            format_settings.frame_limit = enabled_parts.frame_limit;
            format!(
                "```hcl\n\
                {message}\n\
                ```\n\n",
                message = self.error_report.stringify(format_settings)?
            )
        } else {
            "".to_owned()
        };

        Ok(format!(
            "{header}\
            ## Summary:\n\
            {summary}\
            {reproduce}\
            ## Debug info:\n\
            {backtrace}\
            ### System:\n\
            * Application version: {version}\n\
            * System: {os} {arch}\n\
            {start_footer}\
            {labels}",
            header = Self::gitlab_syntax(
                "<!-- Please check above for similar title.\n\
                Someone might have already reported this.-->\n",
                enabled_parts
            ),
            summary = summary,
            reproduce = reproduce,
            backtrace = backtrace,
            version = env!("CARGO_PKG_VERSION"),
            arch = std::env::consts::ARCH,
            os = std::env::consts::OS,
            start_footer = Self::gitlab_syntax("<!-- Leave below untouched! -->\n", enabled_parts),
            labels = Self::gitlab_syntax(self.get_labels(settings), enabled_parts),
        ))
    }

    fn create_new_submit_url(
        &self,
        settings: &RwLockReadGuard<'static, GitLabERGlobalSettings>,
        enabled_parts: &ReportPartEnabled,
    ) -> Result<Url, ErrorReport> {
        let format_settings = ErrorFmtSettings {
            level_of_detail: ErrorFmtLoD::SubmitReport,
            frame_limit: None,
            enable_color: false,
            link_format: LinkDebugIde::NoLink,
            indentation_style: IndentationStyle::Tab,
            skip_first_indentations: 2,
            ..Default::default()
        };
        let description = self.create_new_bug_report(settings, enabled_parts, &format_settings)?;

        let encoded: String = form_urlencoded::Serializer::new(String::new())
            .append_pair(
                "issue[title]",
                &Self::truncate_string(self.get_title(), settings.title_char_limit),
            )
            .append_pair(
                "issue[description]",
                &Self::truncate_string(description, settings.description_char_limit),
            )
            .finish();

        // Create URL from encoded message
        Ok(Url::parse(&format!(
            "https://{domain}/{project_path}/issues/new?{encoded_message}",
            domain = settings.domain,
            project_path = settings.project_path,
            encoded_message = encoded,
        ))?)
    }

    fn get_labels(&self, settings: &RwLockReadGuard<'static, GitLabERGlobalSettings>) -> String {
        let mut labels_string = "/label".to_owned();
        for label in &settings.labels {
            labels_string = format!("{labels_string} ~\"{label}\"");
        }
        labels_string
    }
}

/// Global configuration for GitLab issue submission.
///
/// Set once at application startup via
/// [`GlobalSettings::set_global_settings`].
#[derive(Debug, Clone)]
pub struct GitLabERGlobalSettings {
    /// GitLab domain (e.g. `"gitlab.com"` or `"gitlab.example.com"`).
    pub domain: String,
    /// Project path (e.g. `"my-group/my-project"`).
    pub project_path: String,
    /// Labels to apply to created issues.
    pub labels: Vec<String>,
    /// Limit that will disable parts of the report in order to stay under this limit (if possible)
    /// Default: 2085
    pub url_char_limit: usize,
    /// Hard limit for title, title will be cut off on or before this limit.
    /// This limit takes into account character boundaries.
    /// Default: 1024
    pub title_char_limit: usize,
    /// Hard limit for description, description will be cut off on or before this limit.
    /// This limit takes into account character boundaries.
    /// Default: 1_048_576 (1MB)
    pub description_char_limit: usize,
    /// Formatter for bug report printed to terminal in stderr
    /// This is the exact same message as is included in reporting link (before reducing because of char_limit).
    ///
    /// Because it is printed to standard error it can contain color or be otherwise easier to read.
    /// These settings do not apply to output in debug builds or to the output in the link.
    ///
    /// Default settings is same as format in Link
    pub release_format_settings_stderr: ErrorFmtSettings,
}

impl GlobalSettings for GitLabERGlobalSettings {
    type Setting = GitLabERGlobalSettings;

    fn once_lock() -> &'static OnceLock<RwLock<Self::Setting>> {
        &GITLAB_SUBMIT_REPORT_GLOBAL_CONFIG
    }
    fn get_setting_object_name() -> &'static str {
        "GITLAB_SUBMIT_REPORT_GLOBAL_CONFIG"
    }
}

static GITLAB_SUBMIT_REPORT_GLOBAL_CONFIG: OnceLock<RwLock<GitLabERGlobalSettings>> =
    OnceLock::new();

impl Default for GitLabERGlobalSettings {
    fn default() -> Self {
        Self {
            domain: "gitlab.com".to_owned(),
            project_path: "<not set>".to_owned(),
            labels: vec!["Auto Generated Issue".to_owned()],
            url_char_limit: 2085,
            title_char_limit: 1024,
            description_char_limit: 1_048_576, // 1MB
            release_format_settings_stderr: ErrorFmtSettings {
                level_of_detail: ErrorFmtLoD::SubmitReport,
                frame_limit: None,
                enable_color: false,
                link_format: LinkDebugIde::NoLink,
                indentation_style: IndentationStyle::Tab,
                skip_first_indentations: 2,
                ..Default::default()
            },
        }
    }
}