module Athena::Framework::Exceptions

Exception handling in Athena is similar to exception handling in any Crystal program, with the addition of a new unique exception type, ATH::Exceptions::HTTPException.

When an exception is raised, Athena emits the ATH::Events::Exception event to allow an opportunity for it to be handled. If the exception goes unhandled, i.e. no listener set an ATH::Response on the event, then the request is finished and the exception is reraised. Otherwise, that response is returned, setting the status and merging the headers on the exceptions if it is an ATH::Exceptions::HTTPException. See ATH::Listeners::Error and ATH::ErrorRendererInterface for more information on how exceptions are handled by default.

To provide the best response to the client, non ATH::Exceptions::HTTPException should be rescued and converted into a corresponding ATH::Exceptions::HTTPException. Custom HTTP errors can also be defined by inheriting from ATH::Exceptions::HTTPException or a child type. A use case for this could be allowing for additional data/context to be included within the exception that ultimately could be used in a ATH::Events::Exception listener.