#include <userver/server/handlers/exceptions.hpp>

Detailed Description

The generic base class for handler exceptions. Thrown exceptions should typically derive from ExceptionWithCode instead.

Definition at line 195 of file exceptions.hpp.

Inheritance diagram for server::handlers::CustomHandlerException:

Public Types
using	HandlerErrorCode = handlers::HandlerErrorCode

using	ServiceErrorCode = handlers::ServiceErrorCode

using	InternalMessage = handlers::InternalMessage

using	ExternalBody = handlers::ExternalBody

using	ExtraHeaders = handlers::ExtraHeaders

Public Member Functions
template<typename... Args>
	CustomHandlerException (HandlerErrorCode handler_code, Args &&... args)
	Construct manually from a set of (mostly optional) arguments, which describe the error details.

	CustomHandlerException (HandlerErrorCode handler_code)
	This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

	CustomHandlerException (ServiceErrorCode service_code, ExternalBody external_body, InternalMessage internal_message, HandlerErrorCode handler_code, ExtraHeaders headers={}, formats::json::Value details={})

template<typename MessageBuilder> requires impl::IsMessageBuilder<MessageBuilder>
	CustomHandlerException (MessageBuilder &&builder, HandlerErrorCode handler_code)

HandlerErrorCode	GetCode () const

const std::string &	GetServiceCode () const

bool	IsExternalErrorBodyFormatted () const

const std::string &	GetExternalErrorBody () const

const formats::json::Value &	GetDetails () const

const Headers &	GetExtraHeaders () const

Member Typedef Documentation

◆ ExternalBody

using server::handlers::CustomHandlerException::ExternalBody = handlers::ExternalBody

Definition at line 201 of file exceptions.hpp.

◆ ExtraHeaders

using server::handlers::CustomHandlerException::ExtraHeaders = handlers::ExtraHeaders

Definition at line 202 of file exceptions.hpp.

◆ HandlerErrorCode

using server::handlers::CustomHandlerException::HandlerErrorCode = handlers::HandlerErrorCode

Definition at line 198 of file exceptions.hpp.

◆ InternalMessage

using server::handlers::CustomHandlerException::InternalMessage = handlers::InternalMessage

Definition at line 200 of file exceptions.hpp.

◆ ServiceErrorCode

using server::handlers::CustomHandlerException::ServiceErrorCode = handlers::ServiceErrorCode

Definition at line 199 of file exceptions.hpp.

Constructor & Destructor Documentation

◆ CustomHandlerException() [1/4]

template<typename... Args>

server::handlers::CustomHandlerException::CustomHandlerException	(	HandlerErrorCode	handler_code,
		Args &&...	args )

inline

Construct manually from a set of (mostly optional) arguments, which describe the error details.

Allowed arguments

HandlerErrorCode - defaults for other fields are derived from it
ServiceErrorCode - used e.g. in JSON error format
http::HttpStatus
InternalMessage - for logs
ExternalBody
ExtraHeaders
formats::json::Value - details for JSON error format
a message builder, see below

Example:

TEST(CustomHandlerException, DirectSample) {
    auto exc = server::handlers::ClientError(
        server::handlers::InternalMessage{
            "Spam detected, criterion: too many "
            "repetitions (42, we only allow 10)"
        },
        server::handlers::ExternalBody{"Failed to post: spam detected"}
    );
 
    EXPECT_EQ(exc.GetCode(), server::handlers::HandlerErrorCode::kClientError);
    EXPECT_EQ(server::http::GetHttpStatus(exc), server::http::HttpStatus::kBadRequest);
    EXPECT_THAT(exc.GetExternalErrorBody(), testing::HasSubstr("Failed to post: spam detected"));
    EXPECT_THAT(exc.what(), testing::HasSubstr("42, we only allow 10"));
}

Message builders

A message builder is a class that satisfies the following requirements:

provides a GetExternalBody() const function to form an external body
has an optional kIsExternalBodyFormatted set to true to forbid changing the external body
has an optional GetServiceCode() const function to return machine readable error code
has an optional GetInternalMessage() const function to form an message for logging an error

Some message builder data can be overridden by explicitly passed args, if these args go after the message builder.

Example:

class CustomErrorBuilder {
public:
    static constexpr bool kIsExternalBodyFormatted = true;
 
    CustomErrorBuilder(std::string status, std::string msg) {
        formats::json::ValueBuilder error;
        error["code"] = std::move(status);
        error["message"] = std::move(msg);
        json_error_body_ = formats::json::ToString(error.ExtractValue());
    }
 
    std::string GetExternalBody() const { return json_error_body_; }
 
private:
    std::string json_error_body_;
};
 
TEST(CustomHandlerException, BuilderSample) {
    auto exc = server::handlers::ClientError(CustomErrorBuilder{"Bad Request", "Something went wrong"});
 
    EXPECT_EQ(exc.GetCode(), server::handlers::HandlerErrorCode::kClientError);
    EXPECT_EQ(exc.what(), std::string{"Client error"}) << "Log message";
 
    auto json = formats::json::FromString(R"({"code":"Bad Request","message":"Something went wrong"})");
    EXPECT_EQ(formats::json::FromString(exc.GetExternalErrorBody()), json);
}

Definition at line 238 of file exceptions.hpp.

◆ CustomHandlerException() [2/4]

server::handlers::CustomHandlerException::CustomHandlerException ( HandlerErrorCode handler_code )

inlineexplicit

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

Definition at line 243 of file exceptions.hpp.

◆ CustomHandlerException() [3/4]

server::handlers::CustomHandlerException::CustomHandlerException	(	ServiceErrorCode	service_code,
		ExternalBody	external_body,
		InternalMessage	internal_message,
		HandlerErrorCode	handler_code,
		ExtraHeaders	headers = {},
		formats::json::Value	details = {} )

inline

Deprecated: Use the variadic constructor above instead.

Definition at line 248 of file exceptions.hpp.

◆ CustomHandlerException() [4/4]

template<typename MessageBuilder>
requires impl::IsMessageBuilder<MessageBuilder>

server::handlers::CustomHandlerException::CustomHandlerException	(	MessageBuilder &&	builder,
		HandlerErrorCode	handler_code )

inline

Deprecated: Use the variadic constructor above instead.

Definition at line 269 of file exceptions.hpp.

Member Function Documentation

◆ GetCode()

HandlerErrorCode server::handlers::CustomHandlerException::GetCode ( ) const

inline

Definition at line 287 of file exceptions.hpp.

◆ GetDetails()

const formats::json::Value & server::handlers::CustomHandlerException::GetDetails ( ) const

inline

Definition at line 295 of file exceptions.hpp.

◆ GetExternalErrorBody()

const std::string & server::handlers::CustomHandlerException::GetExternalErrorBody ( ) const

inline

Definition at line 293 of file exceptions.hpp.

◆ GetExtraHeaders()

const Headers & server::handlers::CustomHandlerException::GetExtraHeaders ( ) const

inline

Definition at line 297 of file exceptions.hpp.

◆ GetServiceCode()

const std::string & server::handlers::CustomHandlerException::GetServiceCode ( ) const

inline

Definition at line 289 of file exceptions.hpp.

◆ IsExternalErrorBodyFormatted()

bool server::handlers::CustomHandlerException::IsExternalErrorBodyFormatted ( ) const

inline

Definition at line 291 of file exceptions.hpp.

The documentation for this class was generated from the following file:

userver/server/handlers/exceptions.hpp

Detailed Description

Public Types

Public Member Functions

Member Typedef Documentation

◆ ExternalBody

◆ ExtraHeaders

◆ HandlerErrorCode

◆ InternalMessage

◆ ServiceErrorCode

Constructor & Destructor Documentation

◆ CustomHandlerException() [1/4]

Allowed arguments

Message builders

◆ CustomHandlerException() [2/4]

◆ CustomHandlerException() [3/4]

◆ CustomHandlerException() [4/4]

Member Function Documentation

◆ GetCode()

◆ GetDetails()

◆ GetExternalErrorBody()

◆ GetExtraHeaders()

◆ GetServiceCode()

◆ IsExternalErrorBodyFormatted()