error.hpp

Go to the documentation of this file.

#pragma once
 
// ============================================================================
//  aria/error.hpp
// ----------------------------------------------------------------------------
//  Unified error model for the Aria framework. Per docs/error-model.md,
//  every observable error face in Aria reports through `aria::Error`:
//
//    - reactive graph cycles      -> ErrorKind::GraphCycle
//    - validator rule failures    -> ErrorKind::Validation        + ValidationKey
//    - async command body failure -> ErrorKind::AsyncFailure
//    - async cancellation         -> ErrorKind::Cancellation
//    - async with_timeout         -> ErrorKind::Timeout
//    - view binding setter failed -> ErrorKind::BindingFailure
//    - bad user argument          -> ErrorKind::UserError
//    - internal contract broken   -> ErrorKind::InvariantViolation
//
//  Properties of the type:
//
//    * Value-typed: copyable, equality-comparable. Designed to be the
//      `T` of `Property<std::optional<Error>>`.
//
//    * Embedded ValidationKey: a ValidationError no longer needs its
//      own struct -- it is just an `Error` with `kind = Validation`
//      and a populated `key`. This keeps a single observable surface
//      (`vector<Error>`) instead of fragmenting per error family.
//
//    * Optional `source` string: a stable, free-form locator for "who
//      produced this" (e.g. "AsyncCommand", "AsyncResource", "Validator",
//      "BindingEngine"). Renderers can group / filter on it.
//
//    * Optional `inner` exception_ptr: an escape hatch for callers that
//      want full stack-trace context. Most consumers never touch it;
//      `message` carries the human-facing text already.
//
//    * `Error::from_exception(...)`: canonical mapping from a thrown
//      exception_ptr to a typed Error. Framework-specific sentinels are
//      classified at their owning subsystem's error boundary first.
//
//  Per docs/api-style.md S-1 the type lives in `aria::` and never
//  forces the caller to qualify into an implementation namespace.
// ============================================================================
 
#include "aria/validation_key.hpp"
 
#include <cstdint>
#include <exception>
#include <optional>
#include <ostream>
#include <stdexcept>
#include <string>
#include <string_view>
#include <utility>
 
namespace aria {
 
// ---------------------------------------------------------------------------
//  ErrorKind
// ---------------------------------------------------------------------------

enum class ErrorKind : std::uint8_t {
    UserError = 0,

    Validation = 1,

    AsyncFailure = 2,

    Cancellation = 3,

    Timeout = 4,

    BindingFailure = 5,

    GraphCycle = 6,

    InvariantViolation = 7,
};
 
[[nodiscard]] inline std::string_view to_string(ErrorKind k) noexcept {
    switch (k) {
        case ErrorKind::UserError:          return "UserError";
        case ErrorKind::Validation:         return "Validation";
        case ErrorKind::AsyncFailure:       return "AsyncFailure";
        case ErrorKind::Cancellation:       return "Cancellation";
        case ErrorKind::Timeout:            return "Timeout";
        case ErrorKind::BindingFailure:     return "BindingFailure";
        case ErrorKind::GraphCycle:         return "GraphCycle";
        case ErrorKind::InvariantViolation: return "InvariantViolation";
    }
    return "ErrorKind?";
}
 
[[nodiscard]] inline std::string_view to_string(Severity s) noexcept {
    return s == Severity::Error ? "Error" : "Warning";
}
 
// ---------------------------------------------------------------------------
//  Error
// ---------------------------------------------------------------------------

struct Error {
    ErrorKind                       kind     = ErrorKind::AsyncFailure;
    Severity                        severity = Severity::Error;
    std::string                     message;
    std::string                     source;
    ValidationKey                   key;
    std::exception_ptr              inner;
 
    [[nodiscard]] bool is_error()   const noexcept { return severity == Severity::Error; }
    [[nodiscard]] bool is_warning() const noexcept { return severity == Severity::Warning; }
 
    [[nodiscard]] bool is_cancellation() const noexcept {
        return kind == ErrorKind::Cancellation;
    }

    [[nodiscard]] std::string to_string() const {
        std::string out;
        out.append(::aria::to_string(kind));
        if (!source.empty()) { out.push_back(':'); out.append(source); }
        if (!key.empty())    { out.push_back(':'); out.append(key.to_string()); }
        out.append(": ");
        out.append(message);
        return out;
    }
 
    // ── Factories ─────────────────────────────────────────────────────

    [[nodiscard]] static Error validation(ValidationKey k, std::string msg) {
        return Error{ErrorKind::Validation, Severity::Error,
                     std::move(msg), "Validator", std::move(k), {}};
    }

    [[nodiscard]] static Error validation_warning(ValidationKey k, std::string msg) {
        return Error{ErrorKind::Validation, Severity::Warning,
                     std::move(msg), "Validator", std::move(k), {}};
    }

    [[nodiscard]] static Error async_failure(std::string msg,
                                             std::string source_tag = "AsyncCommand",
                                             std::exception_ptr inner = {}) {
        return Error{ErrorKind::AsyncFailure, Severity::Error,
                     std::move(msg), std::move(source_tag), {}, std::move(inner)};
    }

    [[nodiscard]] static Error cancellation(std::string source_tag = "AsyncCommand") {
        return Error{ErrorKind::Cancellation, Severity::Error,
                     "operation cancelled", std::move(source_tag), {}, {}};
    }

    [[nodiscard]] static Error timeout(std::string source_tag = "AsyncCommand") {
        return Error{ErrorKind::Timeout, Severity::Error,
                     "operation timed out", std::move(source_tag), {}, {}};
    }

    [[nodiscard]] static Error user_error(std::string msg, std::string source_tag = {}) {
        return Error{ErrorKind::UserError, Severity::Error,
                     std::move(msg), std::move(source_tag), {}, {}};
    }

    [[nodiscard]] static Error graph_cycle(std::string msg,
                                           std::exception_ptr inner = {}) {
        return Error{ErrorKind::GraphCycle, Severity::Error,
                     std::move(msg), "Graph", {}, std::move(inner)};
    }

    [[nodiscard]] static Error from_exception(std::exception_ptr ex,
                                              std::string source_tag) {
        if (!ex) {
            return Error::async_failure("unknown error",
                                        std::move(source_tag), {});
        }
        try {
            std::rethrow_exception(ex);
        } catch (const std::invalid_argument& e) {
            return Error{ErrorKind::UserError, Severity::Error, e.what(),
                         std::move(source_tag), {}, ex};
        } catch (const std::out_of_range& e) {
            return Error{ErrorKind::UserError, Severity::Error, e.what(),
                         std::move(source_tag), {}, ex};
        } catch (const std::exception& e) {
            return Error::async_failure(e.what(), std::move(source_tag), ex);
        } catch (...) {
            return Error::async_failure("unknown error",
                                        std::move(source_tag), ex);
        }
    }
};
 
// Equality intentionally ignores `inner` (exception_ptr identity is
// not a useful equivalence) so that re-emitting the same logical
// failure does NOT trigger Property::on_changed when wrapped in
// `Property<std::optional<Error>>`.
inline bool operator==(const Error& a, const Error& b) noexcept {
    return a.kind     == b.kind
        && a.severity == b.severity
        && a.message  == b.message
        && a.source   == b.source
        && a.key      == b.key;
}
inline bool operator!=(const Error& a, const Error& b) noexcept {
    return !(a == b);
}
 
inline std::ostream& operator<<(std::ostream& os, const Error& e) {
    return os << e.to_string();
}
 
}  // namespace aria