Never Let an Exception Cross the Bus

• The callback boundary; the C-frame rule.

Every subscription is delivered by one callback that the NATS client library invokes on its own thread. In C++, that callback is invoked across a C frame, and the library knows nothing of exceptions.

What happens to an exception that leaves a message handler?

• An exception crossing a C frame is undefined behaviour and in practice calls `std::terminate`, killing the process.
• The process death leaves no line in the service's log, so the cause is invisible.
• A handler does real work — decoding, a database call — and all of that can throw.
• A message that kills its consumer also takes every other subscription with it.

The handler reports and returns; nothing escapes. The transport provides the outermost catch, and each handler provides its own inner one:

// The transport's callback: the last line of defence, on a library thread.
void on_msg(natsConnection*, natsSubscription*, natsMsg* msg, void* ud) {
    // read the subject first, cheaply, so the catch below can name it
    try {
        cl->handler(extract_message(msg));
    } catch (const std::exception& e) {
        BOOST_LOG_SEV(lg(), error)
            << "Unhandled exception in handler for '" << subject << "': " << e.what();
    } catch (...) {
        BOOST_LOG_SEV(lg(), error) << "Unknown exception in handler for '" << subject << "'";
    }
}

Three rules:

• A handler reports a failure, it does not throw. An exception from the service layer becomes a failed answer in the body; see Report a Failure in the Body.
• A caught exception is never simply swallowed. The handler replies with the failure, or — where there is no reply subject — logs it as the whole account of what happened.
• A durable handler must not acknowledge by escaping. Under an auto-ack subscription, returning normally acknowledges the message; see Acknowledge What Was Handled.

• An exception escaping a handler. The service dies with no log line for the cause, taking every other subscription with it.
• Catching and returning silently. The caller waits out its deadline and the log says nothing.
• A catch that acknowledges. On a durable subscription, a caught failure that returns normally is acknowledged as done.
• Reading the message after destroying it. State read in the catch must be captured before the message is freed.

Benefits

One bad message costs one message, not the whole service.

Liabilities

The handler must be written so every path either replies or deliberately does not.

The callback in `ores.nats` destroys the cnats message before invoking the handler and catches every exception, logging the subject and the text. Every generated handler wraps the service call in its own try/catch and replies with a failed body. Hand-written handlers follow the same shape.

• Report a Failure in the Body — what the handler replies instead of throwing.
• Announce Every Handled Message — the log line that replaces a silent crash.
• Acknowledge What Was Handled — why a caught failure must not be acknowledged.

• NATS documentation, Events and callbacks — a message callback runs on a library thread.

• NATS service patterns — the structure note that orders this pattern language, and where to read this page in it.