validatoremail.h

/*
 * SPDX-FileCopyrightText: (C) 2017-2025 Matthias Fehring <mf@huessenbergnetz.de>
 * SPDX-License-Identifier: BSD-3-Clause
 */
#ifndef CUTELYSTVALIDATOREMAIL_H
#define CUTELYSTVALIDATOREMAIL_H

#include "validatorrule.h"

namespace Cutelyst {

class ValidatorEmailPrivate;

class CUTELYST_PLUGIN_UTILS_VALIDATOR_EXPORT ValidatorEmail : public ValidatorRule
{
    Q_GADGET
public:
    enum Diagnose : int {
        // Address is valid
        ValidAddress =
            0, 
        // Address is valid but there are warnings about the DNS
        DnsWarnNoMxRecord =
            4, 
        // Address is valid but a DNS check was not successful
        DnsMxDisabled = 5, 
        DnsNoRecordFound =
            6,               
        DnsErrorTimeout = 7, 
        DnsError =
            8, 
        // Address is valid for SMTP but has unusual Elements
        RFC5321TLD = 9, 
        RFC5321TLDNumeric =
            10, 
        RFC5321QuotedString   = 11, 
        RFC5321AddressLiteral = 12, 
        RFC5321IPv6Deprecated =
            13, 
        // Address is valid within the message but cannot be used unmodified for the envelope
        CFWSComment = 17, 
        CFWSFWS     = 18, 
        // Address contains deprecated elements but may still be valid in restricted contexts
        DeprecatedLocalpart = 33, 
        DeprecatedFWS       = 34, 
        DeprecatedQText     = 35, 
        DeprecatedQP        = 36, 
        DeprecatedComment = 37, 
        DeprecatedCText   = 38, 
        DeprecatedCFWSNearAt =
            49, 
        // The address in only valid according to the broad definition of RFC 5322. It is otherwise
        // invalid
        RFC5322Domain =
            65, 
        RFC5322TooLong       = 66, 
        RFC5322LocalTooLong  = 67, 
        RFC5322DomainTooLong = 68, 
        RFC5322LabelTooLong  = 69, 
        RFC5322DomainLiteral =
            70,                     
        RFC5322DomLitOBSDText = 71, 
        RFC5322IPv6GroupCount =
            72, 
        RFC5322IPv62x2xColon = 73, 
        RFC5322IPv6BadChar   = 74, 
        RFC5322IPv6MaxGroups = 75, 
        RFC5322IPv6ColonStart = 76, 
        RFC5322IPv6ColonEnd   = 77, 
        // Address is invalid for any purpose
        ErrorExpectingDText =
            129, 
        ErrorNoLocalPart     = 130, 
        ErrorNoDomain        = 131, 
        ErrorConsecutiveDots = 132, 
        ErrorATextAfterCFWS =
            133, 
        ErrorATextAfterQS = 134, 
        ErrorATextAfterDomLit =
            135, 
        ErrorExpectingQpair =
            136, 
        ErrorExpectingAText = 137, 
        ErrorExpectingQText = 138, 
        ErrorExpectingCText = 139, 
        ErrorBackslashEnd   = 140, 
        ErrorDotStart       = 141, 
        ErrorDotEnd         = 142, 
        ErrorDomainHyphenStart  = 143, 
        ErrorDomainHyphenEnd    = 144, 
        ErrorUnclosedQuotedStr  = 145, 
        ErrorUnclosedComment    = 146, 
        ErrorUnclosedDomLiteral = 147, 
        ErrorFWSCRLFx2  = 148, 
        ErrorFWSCRLFEnd = 149, 
        ErrorCRnoLF =
            150, 
        ErrorFatal = 254 
    };
    Q_ENUM(Diagnose)

    
    enum Category : int {
        Valid = 1, 
        DNSWarn =
            DnsMxDisabled, 
        DNSFailed =
            RFC5321TLD, 
        RFC5321 = CFWSComment,      
        CFWS = DeprecatedLocalpart, 
        Deprecated = RFC5322Domain, 
        RFC5322 = ErrorExpectingDText, 
        Error = 255 
    };
    Q_ENUM(Category)

    enum Option : quint8 {
        NoOption = 0,  
        CheckDNS = 1,  
        UTF8Local = 2, 
        AllowIDN  = 4, 
        AllowUTF8 = UTF8Local | AllowIDN 
    };
    Q_DECLARE_FLAGS(Options, Option)

    
    explicit ValidatorEmail(const QString &field,
                            Category threshold                = RFC5321,
                            Options options                   = NoOption,
                            const ValidatorMessages &messages = {},
                            const QString &defValKey          = {});

    ~ValidatorEmail() override;

    static QString diagnoseString(const Context *c, Diagnose diagnose, const QString &label = {});

    static QString categoryString(const Context *c, Category category, const QString &label = {});

    static Category category(Diagnose diagnose);

    static QString categoryString(const Context *c, Diagnose diagnose, const QString &label = {});

    static bool validate(const QString &email,
                         Category threshold         = RFC5321,
                         Options options            = NoOption,
                         QList<Diagnose> *diagnoses = nullptr);

    static void validateCb(
        const QString &email,
        Category threshold,
        Options options,
        std::function<
            void(bool isValid, const QString &cleanedEmail, const QList<Diagnose> &diagnoses)> cb);

protected:
    ValidatorReturnType validate(Context *c, const ParamsMultiMap &params) const override;

    void validateCb(Context *c, const ParamsMultiMap &params, ValidatorRtFn cb) const override;

    QString genericValidationError(Context *c,
                                   const QVariant &errorData = QVariant()) const override;

private:
    Q_DECLARE_PRIVATE(ValidatorEmail) // NOLINT(cppcoreguidelines-pro-type-reinterpret-cast)
    Q_DISABLE_COPY(ValidatorEmail)
};

} // namespace Cutelyst

Q_DECLARE_OPERATORS_FOR_FLAGS(Cutelyst::ValidatorEmail::Options)

#endif // CUTELYSTVALIDATOREMAIL_H