Result & Status Reference

Every message handler returns its response wrapped in IBenzeneResult<T> (or IBenzeneResult for handlers with no payload). The result carries a status — success, not found, validation error, and so on — alongside the payload or error. Transports map that status onto their native response (HTTP status codes, etc.), so your handler expresses intent once and it's translated everywhere.

You build results with the static BenzeneResult factory (in Benzene.Results). For the conceptual introduction, see Message Results.

public Task<IBenzeneResult<OrderDto>> HandleAsync(GetOrderRequest request)
{
    var order = _repository.Find(request.Id);
    return order is null
        ? Task.FromResult(BenzeneResult.NotFound<OrderDto>())
        : Task.FromResult(BenzeneResult.Ok(order));
}

Statuses

The status strings are defined as constants on BenzeneResultStatus (Benzene.Results). This table lists every status, the factory method that produces it, whether it counts as success, and the HTTP status code HTTP transports map it to (via DefaultHttpStatusCodeMapper).

Success statuses

Failure statuses

A null status falls back to HTTP 500. A status not in the map (an application-defined status) falls back to HTTP 200 when the result's IsSuccessful is true, else 500 — see Using an application-defined status.

Payload vs. no-payload overloads

Each factory has two forms:

• IBenzeneResult<T> — carries a typed payload. On success you pass the value (BenzeneResult.Ok(order)); on failure you specify the type parameter (BenzeneResult.NotFound<OrderDto>()) since there's no payload.
• IBenzeneResult — no payload, for handlers declared as IMessageHandler<TMessage>.

BenzeneResult.Ok(new OrderDto { /* … */ });   // IBenzeneResult<OrderDto>
BenzeneResult.NotFound<OrderDto>();            // IBenzeneResult<OrderDto>, no payload
BenzeneResult.Accepted();                      // IBenzeneResult, no payload

Failure factories that describe an error (BadRequest, ValidationError, UnexpectedError, …) accept an optional message:

BenzeneResult.ValidationError<OrderDto>("Name is required");
BenzeneResult.BadRequest("Invalid request");

Helpers and lower-level building

Classifying statuses

BenzeneResultStatus is the single owner of what each status means — the transport mappers, clients, and IsSuccessful all derive from it:

IsSuccessful on a result built with BenzeneResult.Set(status) / Set<T>(status, payload) is derived from the status class: known failure statuses produce IsSuccessful == false; success statuses produce IsSuccessful == true. An application-defined status isn't in either class, so these overloads throw ArgumentException for one rather than silently guessing — use Set<T>(status, isSuccessful) / Set<T>(status, payload, isSuccessful) to state it explicitly.

Retrying: RetryBenzeneMessageClient (Benzene.Clients) retries service-unavailable and too-many-requests by default. timeout is transient but not retried by default — a timed-out operation may have been applied, so blind retries are only safe for idempotent calls; opt in via its shouldRetry constructor parameter (e.g. r => BenzeneResultStatus.IsTransient(r.Status)).

Using an application-defined status

Applications may use their own status strings (BenzeneResult.Set("quarantined", payload, true)), with caveats:

• An application-defined status has no known success class, so Set<T>(status, payload) throws — use Set<T>(status, payload, isSuccessful) to state it explicitly. There is no silent default.
• Transports honor IsSuccessful for an unmapped status by default: HTTP maps to 200, gRPC to OK, when IsSuccessful is true — 500/Internal (a thrown RpcException for gRPC) otherwise. To map your status to something more specific, replace IHttpStatusCodeMapper (Benzene.Http) / IGrpcStatusCodeMapper (Benzene.Grpc). Both are registered with TryAdd, so a registration in ConfigureServices wins.
• Custom validation statuses: FluentValidation's per-rule .WithStatus(...), the handler-level [ValidationStatus] attribute, and the replaceable IValidationStatusMapper set the status on validation failures; IDefaultStatuses replaces the framework's own defaults.
• Benzene clients round-trip custom statuses, IsSuccessful included: the response envelope carries an explicit isSuccessful field (wire-contracts.md §1.2) that a receiving client reads directly. A sender that predates this field is still classified from the status text, so a custom status from one arrives as unexpected-error.
• The overload trap is now [Obsolete]: Set<T>(status, params string[] errors) — the overload a single string argument could silently bind to instead of the payload overload — is obsoleted in favor of SetFailed<T>(status, errors) (errors case) and Set<T>(status, payload, isSuccessful: true) (string payload case).

Problem-type registry

Every failed result is served on the wire as an RFC 9457 problem document (Benzene.Results.ProblemDetails). The document's type/title come from Benzene.Results.ProblemTypes, a static registry keyed by the same status vocabulary as the tables above — one row per failure status, plus a fallback for an application-defined one:

ProblemTypes.TypeFor(status) / .TitleFor(status) / .HttpStatusFor(status) expose this table in code; ProblemTypes.From(result) is the factory that builds a full ProblemDetails document from an ordinary result — DefaultResponsePayloadMapper calls it for every failed result automatically, so application code rarely calls it directly. Treat type as an opaque identifier: compare it by string equality, never dereference it as a URL. See Message Results — Problem documents for the full document shape, an example, BenzeneResult.Problem(...) (a handler returning its own rich problem), and GetProblem() (reading one back).

Mapping in both directions

• Outbound (handler → transport): DefaultHttpStatusCodeMapper (Benzene.Http) converts a result status to an HTTP status code using the table above. Non-HTTP transports apply their own conventions.
• Inbound (transport → result): when a Benzene client calls another service over HTTP, BenzeneResultHttpMapper (Benzene.Clients) converts the received HTTP status code back into a BenzeneResult status, so calling code sees the same result model regardless of transport.

See also

• Message Results — the conceptual introduction, including problem documents, BenzeneResult.Problem(...), and GetProblem().
• Message Handlers — where results are returned.
• Fluent Validation / Data Annotations — produce validation-error results automatically.

Edit this page on GitHub