The methods proton::messaging_handler::on_connection_close(), on_connection_error(), and on_transport_error() are not well documented. Customers often expect these methods to be called in circumstances where they are not. For example, if the server to which a client is connected fails, neither on_connection_close() nor on_connection_error() is called, although on_transport_error() might be.

Customers are sometimes not aware that Proton offers built-in failover and reconnection logic. If they were, they would probably not try to use messaging_handler methods to implement this logic themselves. At present, little in the documentation suggests that this is not an appropriate approach to development.