Report a Failure in the Body

• The canonical response envelope.

A handler reached the service layer and the service reached a decision: the row is missing, the version conflicts, a business rule denies the write, or the store threw. Every one of those is a legitimate answer to a well-formed request.

How does a service report what it decided, when "denied" and "failed" and "succeeded" are all normal outcomes of a request it handled?

• A refusal is about the caller's right to ask; a decision is about the request itself, and the caller must be able to tell them apart.
• A caller needs enough structure to branch, not a prose message to parse.
• An exception from the store is a real fault and must not read as a business rule declining.
• The same envelope must serve every entity, so a new entity invents nothing.

Answer with the response type, whose `result` carries the outcome:

auto response = svc.update(*req);      // fills result.outcome / code / message
reply(nats_, msg, response);

// An exception from the store is not a decision: report it as a failure.
catch (const std::exception& e) {
    UpdateResponse failure;
    failure.result.outcome = ores::utility::domain::outcome::failed;
    failure.result.code = "internal_error";
    failure.result.message = e.what();
    reply(nats_, msg, failure);
}

The outcome is a closed set, so a caller can be exhaustive:

Two rules:

• The handler decides nothing. It proves the request, checks the permission, decodes the payload, calls the service and carries the answer back. The outcome the caller reads is the service's, so the two cannot disagree.
• A thrown exception becomes failed, never a business outcome. A store error is not "denied"; collapsing the two hides an outage inside normal answers.

• A failed outcome for a refusal. An authorization failure is reported as failed, and the caller diagnoses the payload.
• A prose message with no code. The caller cannot branch, so it either ignores the failure or parses text.
• An empty message on failure. The log has the outcome and nothing about which field or rule produced it.
• A new outcome value at one call site. The set is closed so callers can be exhaustive; a fresh string breaks that.

Benefits

One reply shape for every entity, and a caller that can branch on a closed set.

Liabilities

"Denied" and "failed" can be confused by a careless handler.

`ores::utility::domain::result` carries `outcome`, `code`, `message` and `fields`; every generated handler replies with the response type and maps an exception to internal_error with outcome failed. See NATS entity protocol specification.

• Report a Refusal Off the Body — the report for what was not handled.
• Never Let an Exception Cross the Bus — where the failure report is produced.

• NATS entity protocol specification — the response envelope and its outcome set.
• NATS documentation, Request-Reply — the reply mechanism the answer travels on.

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