runique 3.0.2

//! `RuniqueForm` trait: common interface for all Runique forms.
use crate::context::Request;
pub use crate::forms::{
    base::FormField, form::Forms, renderer::FormRenderer, validator::ValidationError,
};
use crate::utils::{
    aliases::{ADb, ATera, StrMap},
    trad::t,
};

use async_trait::async_trait;
use axum::http::Method;
use sea_orm::{DatabaseTransaction, DbErr, TransactionTrait};

/// Context passed to `before_save` and `after_save` hooks.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum SaveContext {
    Create,
    Update,
    Delete,
}
dyn_clone::clone_trait_object!(FormField);

/// Common logic for all `cleaned_*` — whitelist + priority: POST > path > query.
fn cleaned_value(form: &Forms, name: &str) -> Option<String> {
    if !form.fields.contains_key(name) {
        return None;
    }
    if let Some(val) = form.fields.get(name).map(|f| f.value())
        && !val.is_empty()
    {
        return Some(val.to_string().trim().to_string());
    }
    form.path_params
        .get(name)
        .or_else(|| form.query_params.get(name))
        .map(|s| s.to_string())
}

/// Coerce a whitelisted value to `T`. Logs (field, raw, error) at `forms.field` level
/// when a value is present but fails to parse — instead of silently returning `None`.
/// An absent/empty value is not an error (returns `None` without logging).
fn coerce<T>(form: &Forms, name: &str) -> Option<T>
where
    T: std::str::FromStr,
    T::Err: std::fmt::Display,
{
    let raw = cleaned_value(form, name)?;
    let parsed = raw.parse::<T>();
    log_coerce(name, &raw, parsed)
}

/// Logs (field, raw, error) at `forms.field` level when a present value fails to parse,
/// then returns `None`. Shared by `coerce` and the format-based `cleaned_*` helpers.
fn log_coerce<T, E: std::fmt::Display>(name: &str, raw: &str, res: Result<T, E>) -> Option<T> {
    match res {
        Ok(v) => Some(v),
        Err(e) => {
            if let Some(level) = crate::utils::config::runique_log::get_log()
                .forms
                .as_ref()
                .and_then(|f| f.field)
            {
                crate::runique_log!(
                    level,
                    field = %name,
                    raw = %raw,
                    error = %e,
                    "cleaned coercion failed"
                );
            }
            None
        }
    }
}

/// Rolls back a transaction and logs the rollback error instead of swallowing it.
/// A failed rollback leaves the DB in an undefined state — it must never be silent,
/// even though the caller returns the original business error.
async fn rollback_traced(txn: DatabaseTransaction) {
    if let Err(rb) = txn.rollback().await {
        tracing::warn!(error = %rb, "transaction rollback failed");
    }
}

/// Main trait for typed forms with validation and saving
///
#[doc = include_str!("../../doc-tests/form/form_proc_macro.md")]
///
#[doc = include_str!("../../doc-tests/form/form_clean_save.md")]
#[async_trait]
pub trait RuniqueForm: Sized + Send + Sync {
    fn register_fields(form: &mut Forms);
    fn from_form(form: Forms) -> Self;
    fn get_form(&self) -> &Forms;
    fn get_form_mut(&mut self) -> &mut Forms;

    /// Hook to tweak the generated fields (label, placeholder, required, attrs…)
    /// right after they are registered. Default: no-op. Override it in your
    /// `impl RuniqueForm` block to customize a macro-generated form.
    fn customize(_form: &mut Forms) {}

    // ── Whitelisted access to values (POST > path param > query param) ──────────

    /// `String` — `None` if the field is unknown or empty.
    fn cleaned_string(&self, name: &str) -> Option<String> {
        cleaned_value(self.get_form(), name)
    }
    /// `i32` — `None` if unknown, empty, or not parseable.
    fn cleaned_i8(&self, name: &str) -> Option<i8> {
        coerce(self.get_form(), name)
    }
    fn cleaned_i16(&self, name: &str) -> Option<i16> {
        coerce(self.get_form(), name)
    }
    fn cleaned_i32(&self, name: &str) -> Option<i32> {
        coerce(self.get_form(), name)
    }
    /// `i64` — `None` if unknown, empty, or not parseable.
    fn cleaned_i64(&self, name: &str) -> Option<i64> {
        coerce(self.get_form(), name)
    }
    /// `u32` — `None` if unknown, empty, or not parseable.
    fn cleaned_u32(&self, name: &str) -> Option<u32> {
        coerce(self.get_form(), name)
    }
    /// `u64` — `None` if unknown, empty, or not parseable.
    fn cleaned_u64(&self, name: &str) -> Option<u64> {
        coerce(self.get_form(), name)
    }
    /// `f32`, read like `NumericField::float` reads it (`,` or `.`, exponent
    /// allowed). `None` if unknown, empty, or not parseable.
    fn cleaned_f32(&self, name: &str) -> Option<f32> {
        let raw = cleaned_value(self.get_form(), name)?;
        log_coerce(name, &raw, raw.replace(',', ".").parse::<f32>()).filter(|v| v.is_finite())
    }
    /// `f64`, read like `NumericField::float` reads it (`,` or `.`, exponent
    /// allowed). `None` if unknown, empty, or not parseable.
    fn cleaned_f64(&self, name: &str) -> Option<f64> {
        let raw = cleaned_value(self.get_form(), name)?;
        log_coerce(name, &raw, raw.replace(',', ".").parse::<f64>()).filter(|v| v.is_finite())
    }
    /// `Decimal`, read like `NumericField::decimal` reads it: exact, no
    /// exponent. `None` if unknown, empty, or not parseable.
    fn cleaned_decimal(&self, name: &str) -> Option<rust_decimal::Decimal> {
        let raw = cleaned_value(self.get_form(), name)?;
        log_coerce(
            name,
            &raw,
            rust_decimal::Decimal::from_str_exact(&raw.replace(',', ".")),
        )
    }
    /// `bool` — `true` for `"true"`, `"1"`, `"on"` (case-insensitive).
    /// Returns `None` if the field does not exist in the form.
    /// Note: `fill()` normalizes unchecked checkboxes/radios to `"false"`,
    /// so this method always returns `Some(_)` for a submitted boolean field.
    fn cleaned_bool(&self, name: &str) -> Option<bool> {
        let v = cleaned_value(self.get_form(), name)?;
        Some(matches!(v.to_lowercase().as_str(), "true" | "1" | "on"))
    }

    /// `Uuid` — `None` if unknown, empty, or not parseable.
    fn cleaned_uuid(&self, name: &str) -> Option<uuid::Uuid> {
        coerce(self.get_form(), name)
    }

    /// `NaiveDate` — `None` if unknown, empty, or not parseable.
    fn cleaned_naive_date(&self, name: &str) -> Option<chrono::NaiveDate> {
        let raw = cleaned_value(self.get_form(), name)?;
        log_coerce(
            name,
            &raw,
            chrono::NaiveDate::parse_from_str(&raw, "%Y-%m-%d"),
        )
    }

    /// `NaiveTime`, `HH:MM` or `HH:MM:SS` like `TimeField`. `None` if
    /// unknown, empty, or not parseable.
    fn cleaned_naive_time(&self, name: &str) -> Option<chrono::NaiveTime> {
        let raw = cleaned_value(self.get_form(), name)?;
        log_coerce(
            name,
            &raw,
            chrono::NaiveTime::parse_from_str(&raw, "%H:%M")
                .or_else(|_| chrono::NaiveTime::parse_from_str(&raw, "%H:%M:%S")),
        )
    }

    /// `NaiveDateTime`: whatever `DateTimeField` accepts — what a
    /// `datetime-local` input sends, with or without seconds, or RFC 3339
    /// (taken in UTC). `None` if unknown, empty, or not parseable.
    fn cleaned_naive_datetime(&self, name: &str) -> Option<chrono::NaiveDateTime> {
        let raw = cleaned_value(self.get_form(), name)?;
        log_coerce(
            name,
            &raw,
            crate::forms::fields::datetime::parse_datetime_local(&raw).ok_or("not a date-time"),
        )
    }

    /// `DateTime<Utc>`, for a `timestamp_tz`: RFC 3339 keeps its offset, a
    /// `datetime-local` value (no offset) is taken as UTC — the way the
    /// generated code saves it. `None` if unknown, empty, or not parseable.
    fn cleaned_datetime_utc(&self, name: &str) -> Option<chrono::DateTime<chrono::Utc>> {
        let raw = cleaned_value(self.get_form(), name)?;
        log_coerce(
            name,
            &raw,
            crate::forms::fields::parse_utc_datetime(&raw).ok_or("not a date-time"),
        )
    }

    /// Bytes of a `BinaryField`. Available once the form is valid (`is_valid`
    /// runs `finalize`, which reads the upload) — `None` inside `clean()`.
    fn cleaned_bytes(&self, name: &str) -> Option<Vec<u8>> {
        let raw = cleaned_value(self.get_form(), name)?;
        crate::forms::fields::decode_binary(&raw)
    }

    /// An enum of `model!{}` (text or integer) — `None` if unknown, empty, or
    /// not a valid variant.
    fn cleaned_enum<T: std::str::FromStr>(&self, name: &str) -> Option<T> {
        let raw = cleaned_value(self.get_form(), name)?;
        log_coerce(name, &raw, T::from_str(&raw).map_err(|_| "not a variant"))
    }

    /// The values of a list field (`checkbox` / `multichoice`), in the order
    /// submitted; empty if the field is unknown or nothing was chosen. A value
    /// that isn't a variant is left out (and logged).
    fn cleaned_enums<T: std::str::FromStr>(&self, name: &str) -> Vec<T> {
        let Some(raw) = cleaned_value(self.get_form(), name) else {
            return Vec::new();
        };
        raw.split(',')
            .map(str::trim)
            .filter(|v| !v.is_empty())
            .filter_map(|v| log_coerce(name, v, T::from_str(v).map_err(|_| "not a variant")))
            .collect()
    }

    // ── Field value overrides ───────────────────────────────────────────────

    /// Forces a value on a field, bypassing `fill()`. Useful for skipped fields (e.g. passwords).
    fn add_value(&mut self, name: &str, value: &str) -> &mut Self {
        self.get_form_mut().add_value(name, value);
        self
    }

    // ── Field display overrides ──────────────────────────────────────────────

    fn label(&mut self, name: &str, label: &str) -> &mut Self {
        self.get_form_mut().field_label(name, label);
        self
    }

    fn placeholder(&mut self, name: &str, placeholder: &str) -> &mut Self {
        self.get_form_mut().field_placeholder(name, placeholder);
        self
    }

    fn required(&mut self, name: &str, required: bool) -> &mut Self {
        self.get_form_mut().field_required(name, required);
        self
    }

    fn readonly(&mut self, name: &str, readonly: bool) -> &mut Self {
        self.get_form_mut().field_readonly(name, readonly);
        self
    }

    fn disabled(&mut self, name: &str, disabled: bool) -> &mut Self {
        self.get_form_mut().field_disabled(name, disabled);
        self
    }

    fn attr(&mut self, name: &str, key: &str, value: &str) -> &mut Self {
        self.get_form_mut().field_attr(name, key, value);
        self
    }

    /// Overrides max_size for a file field. Returns Err if it exceeds the model ceiling.
    fn max_size(
        &mut self,
        name: &str,
        size: crate::forms::fields::FileSize,
    ) -> Result<&mut Self, String> {
        self.get_form_mut().field_max_size(name, size)?;
        Ok(self)
    }

    /// Clears all form values (except CSRF).
    fn clear(&mut self) {
        self.get_form_mut().clear_values();
    }

    // Business validation hook for individual fields
    async fn clean_field(&mut self, name: &str) -> bool {
        self.get_form().fields.contains_key(name)
    }

    // Business validation hook for the entire form
    async fn clean(&mut self) -> Result<(), StrMap> {
        Ok(())
    }

    /// Hook to add fields that depend on the request (e.g. choices loaded from
    /// the DB) after extraction but before validation. Default: no-op.
    /// Called by [`ValidationForm::try_new`](crate::forms::ValidationForm::try_new)
    /// before dispatching to `allow_get`/`allow_post`.
    async fn register_dynamic_fields(&mut self, _request: &Request) {}

    /// Whether this form has been submitted — `true` unconditionally once a
    /// POST-class request is reached, `true` for a GET-class request only
    /// once its fields actually carry data (thin wrapper over
    /// `Forms::is_submitted()`, exposed here so external forms never need to
    /// reach into `Forms` directly to opt into `allow_get`, below).
    fn is_submitted(&self) -> bool {
        self.get_form().is_submitted()
    }

    /// Whether [`ValidationForm`](crate::forms::ValidationForm) should attempt
    /// validation on a GET-class request (GET, HEAD, OPTIONS, TRACE). Default:
    /// **`false`**, unconditionally.
    ///
    /// GET/HEAD are the only methods CSRF-exempt (`csrf_required()`), so a form
    /// that auto-validated on GET by default would let its `is_valid()`-gated
    /// side effects (DB write, login, email) run from a plain crafted link —
    /// `?field=value` query params, no CSRF token needed. Defaulting to `false`
    /// means every form is safe unless it deliberately opts in.
    ///
    /// A read-only GET search/filter form is the one legitimate case that
    /// *should* auto-validate — override explicitly:
    /// ```ignore
    /// fn allow_get(&self, _request: &Request) -> bool {
    ///     self.is_submitted()
    /// }
    /// ```
    fn allow_get(&self, _request: &Request) -> bool {
        false
    }

    /// Whether [`ValidationForm`](crate::forms::ValidationForm) should attempt
    /// validation on a POST-class request (POST, PUT, PATCH, DELETE, CONNECT).
    /// Default: reuses [`is_submitted`](Self::is_submitted) — effectively
    /// always `true`, since these methods are always submissions regardless
    /// of field content.
    fn allow_post(&self, _request: &Request) -> bool {
        self.is_submitted()
    }

    async fn is_valid(&mut self) -> bool {
        // If the form has no submitted data (e.g. first GET with no params), return false
        // without setting any field errors. This prevents showing validation errors on the
        // initial page load, and lets GET search forms fall through to their else branch
        // cleanly. Note: Forms::is_valid() (sync) does not have this guard.
        if !self.is_submitted() {
            return false;
        }

        let mut fields_valid = match self.get_form_mut().is_valid().await {
            Ok(valid) => valid,
            Err(ValidationError::StackOverflow) => {
                self.get_form_mut()
                    .errors
                    .push(t("forms.validation_overflow").into_owned());
                return false;
            }
            Err(_) => return false,
        };

        let names: Vec<String> = self.get_form().fields.keys().cloned().collect();
        for name in names {
            if !self.clean_field(&name).await {
                fields_valid = false;
            }
        }

        if !fields_valid {
            return false;
        }

        match self.clean().await {
            Ok(_) => {
                if let Err(e) = self.get_form_mut().finalize().await {
                    self.get_form_mut().errors.push(e);
                    return false;
                }
                true
            }
            Err(business_errors) => {
                let form = self.get_form_mut();
                for (name, msg) in business_errors {
                    if let Some(field) = form.fields.get_mut(&name) {
                        field.set_error(msg);
                    } else {
                        form.errors.push(msg);
                    }
                }
                false
            }
        }
    }

    /// Default atomic wrapper: opens a transaction and calls `on_save`.
    ///
    /// - if `on_save` returns Err -> automatic rollback
    /// - otherwise -> commit
    async fn on_save(&mut self, _txn: &DatabaseTransaction) -> Result<(), DbErr> {
        Ok(())
    }

    /// Hook called inside the transaction, before `on_save`. Default: no-op.
    async fn before_save(
        &mut self,
        _ctx: SaveContext,
        _txn: &DatabaseTransaction,
    ) -> Result<(), DbErr> {
        Ok(())
    }

    /// Hook called inside the transaction, after `on_save`. Default: no-op.
    async fn after_save(
        &mut self,
        _ctx: SaveContext,
        _txn: &DatabaseTransaction,
    ) -> Result<(), DbErr> {
        Ok(())
    }

    /// Atomic wrapper: explicit transaction (avoids the 'static futures trap)
    async fn save(&mut self, db: &ADb) -> Result<(), DbErr> {
        if !self.get_form().is_save_allowed() {
            return Err(DbErr::Custom(
                "save() requires a successful is_valid() call — form not validated or invalid"
                    .to_string(),
            ));
        }
        let txn = db.begin().await?;

        match self.on_save(&txn).await {
            Ok(()) => {
                txn.commit().await?;
                Ok(())
            }
            Err(e) => {
                // Try rollback, but return the original business/DB error.
                rollback_traced(txn).await;
                Err(e)
            }
        }
    }

    /// Like `save`, but with explicit context for hooks.
    /// Order: `before_save` → `on_save` → `after_save` → commit.
    /// Any failure triggers rollback and returns the original error.
    async fn save_as(&mut self, ctx: SaveContext, db: &ADb) -> Result<(), DbErr> {
        if !self.get_form().is_save_allowed() {
            return Err(DbErr::Custom(
                "save_as() requires a successful is_valid() call — form not validated or invalid"
                    .to_string(),
            ));
        }
        let txn = db.begin().await?;

        if let Err(e) = self.before_save(ctx, &txn).await {
            rollback_traced(txn).await;
            return Err(e);
        }
        if let Err(e) = self.on_save(&txn).await {
            rollback_traced(txn).await;
            return Err(e);
        }
        if let Err(e) = self.after_save(ctx, &txn).await {
            rollback_traced(txn).await;
            return Err(e);
        }

        txn.commit().await
    }

    fn database_error(&mut self, err: &DbErr) {
        self.get_form_mut().database_error(err);
    }

    fn build(tera: ATera, csrf_token: &str) -> Self {
        let mut form = Forms::new(csrf_token);
        let renderer = FormRenderer::new(tera);
        form.set_renderer(renderer);
        Self::register_fields(&mut form);
        Self::from_form(form)
    }

    async fn build_with_data(
        raw_data: &StrMap,
        tera: ATera,
        csrf_token: &str,
        method: Method,
    ) -> Self {
        let mut form = Forms::new(csrf_token);

        let renderer = FormRenderer::new(tera);
        form.set_renderer(renderer);

        Self::register_fields(&mut form);
        form.fill(raw_data, method);
        Self::from_form(form)
    }
}