Could Error Values be considered as "privileged" DTOs?

[emedina]

In software architecture, Data Flow refers to the way in which data is passed between the different components or layers of the software architecture. It defines how data is transformed, stored, and accessed. Brought to the scope of the Hexagonal Architecture (HexArch), these flows can be managed and controlled in a more efficient and explicit way. HexArch's approach of separating the core business logic and data flow from external systems allows for clear boundaries and interfaces between different components, making it easier to understand and manage the different flows within the system.

Using a Data Transfer Object (DTO) to hand data over to the outer layers is generally recommended, thus bringing back the benefits of clear separation of concerns, loose coupling, and more flexibility and testability. That means that we must choose upfront from one of the different strategies to map data between boundaries based on the affordable level of acceptance with respect to coupling; mainly I see three:

• No mapping strategy -> uses the Domain Model everywhere (even as Data Entities for an ORM).
• Two-way mapping strategy -> Input/Output Adapters have their own model, but inside the "hexagon", i.e. Input/Output Ports + Application Layer + Domain Layer uses the Domain Model.
• Full mapping strategy -> Input/Output Adapters have their own model, Input/Output Ports use Commands/DTOs, and Application + Domain Layers use the Domain Model

Needless to say, the 3rd strategy is the preferred one in terms of coupling.

Accordingly, I was wondering if Error Values (when we don't want to work with Exceptions to control our flow) can be considered DTOs in the sense that:

1. They could either be Validation, Business, or Technical errors (e.g. an Adapter that uses a REST client to connect to a 3rd-party API that is not available).
2. They must be used in Output Ports as part of the interface contract (together with other DTOs) that we define for future implementations in Adapters.
3. They should avoid leaking error details about the technology used in the implementation, as already discussed here -> Leaking implementation details #100).
4. They need to be propagated from "right to left", as an outcome for the Input Ports, so that, for example, a REST Adapter later can translate them to HTTP status codes with meaningful error messages.

However, whilst Error Values seem to have the same responsibilities as DTOs, they differ in terms of the origin of their definition:

• DTOs are defined and mapped around by the Application Layer, as a defensive mechanism to avoid coupling with the Domain Model.
• (Some) Error Values, i.e. business ones, are defined by the Domain Layer, although then allowed to be exposed beyond the boundaries of the hexagon, both to the left and to the right.

If all this reasoning makes sense, then that's why I consider them "privileged" DTOs and I was wondering what your take is on this matter.

Notice that I intentionally want to avoid throwing Exceptions (I may be ok with using Exceptions as Error Values, though) to drive the flow of my application and instead, I want to use monadic types such as Try, Either, or Validation from vavr.io (for me in Java).

[Sairyss]

Yes, errors as "privileged" DTOs make sense. I used this approach in production for some time (returning errors everywhere instead of throwing). It sounds great in theory, but in practice has serious downsides. Here is what I've learned:

Languages like TypeScript (and Java, in your case), don't have native support for this. Meaning that:

1. it won't force you to do something with returned error. For example, imagine that you need to insert something to the database, but you don't care about the return value. For example in the event handler, when a user is created you want to create a wallet for him:

    async handle(event: UserCreatedDomainEvent): Promise<any> {
    const wallet = WalletEntity.create({
      userId: event.aggregateId,
    });
    await this.walletRepo.insert(wallet);
  }

If this method throws an exception, you will see it in your logs. But if this is a Result object returned, and you forgot to do something with it (at least unwrap it), the error will be invisible, it just won't show up in your logs because it's not handled. Your compiler/IDE won't tell you that you have to assign it to a variable and do something with it. You may spend days fixing this because you won't know where the error is. I've seen this a lot in production. People forget that they need to handle the error, probably because they are too used to exceptions that log the error regardless, or they let the exception propagate and be handled up the stack. Or they just lack discipline to handle this kind of errors properly. I've spent weeks fixing invisible errors like these just because people ignore them and do not handle/unwrap results, hoping it will be propagated and handled by your framework like a regular exception (especially new devs) and language does not do anything to warn you about it.

2. Your language also won't force you to match all the possible errors that may be returned in a Result object. For example, imagine you want to find a user:

  const user = await this.repo.findUser(userId);
  if (user.isErr) {
     return new UserNotFoundError();
  }

The snippet of code above is what I've seen a lot in production apps. Because 99% of the errors in findUser method is Not Found, people just ignore all the other errors. But what if the error is about malformed SQL statement? Or lost connection? Or anything else? All you'll see is "Not found" returned to the user, real error will be ignored. You need to handle all the possible errors here, but it's not forced by the language. And even if you do handle all the possible returned errors in the consumer of the method, it's not guaranteed that the method return type includes all of them. Your repository interface can have this:

 findUser(userId: string): Result<User, NotFoundError>;

Indicating that findUser method only returns NotFoundError, but ignoring other errors that may happen. Or worse, people get lazy and just indicate that your method returns a generic Error. And your compiler will ignore it. If method is updated with new errors, your IDE won't tell you that you need to update all consumers of that method.

3. There's no way to propagate returned errors, like in rust for example by using ? operator, so you'll end up with error checking boilerplate code everywhere.

4. Every library that you use will still throw. So you will have 2 different ways of handling errors. You'll need to wrap every library call into try/catch and return it as a monad, which is more boilerplate. And again, if you do this and then the error is not unwrapped by the consumer, it will be invisible.

In Java you at least have checked exceptions that give you some guarantees and IDE support to prevent issues described above, but with Result objects / Either monads you lose it all and open endless possibilities to shoot yourself in the foot. For these reasons I stopped using Results to return errors in most places, I only use them for business logic in my aggregates, because aggregates return expected business errors, while repositories for example may throw unexpected exceptions that absolutely need to be logged even if a developer forgets to handle them.

In conclusion: be careful when using monads to return your errors in languages that don't support it natively, you may shoot your self in the foot in the long run.

[emedina]

Thanks so much for the detailed response, really appreciated!

I fully understand your concerns, but here are some comments worth mentioning in that regard:

1. All my methods have a similar signature:
   Either<Error, Object> someMethod(SomeDTO... dtos);
   In this particular case, my Output Port's contract would establish that either an error value from those available (more on this next in comment 2.) or the expected result must be returned. Later, the implementor is responsible for fulfilling as much as possible the contract, ideally following a common approach with monads:
   Try.of(() -> myOutputPort.someMethod(dtos)).toEither().mapLeft(ex -> mapExceptionToErrorValue(ex))...
   As with everything in software architecture, this is a trade-off, but if you make it explicit in your definition of the architecture, i.e. clearly setting your Architecture Decision Records (ADR) at the beginning of each development, then you consolidate a development culture where people understand what we're trying to achieve here and, eventually, the error values do arrive to your client Adapter, as I will comment next in 3,
2. For this I leverage the new Algebraic Data Types (ADT) support from Java 14, mainly sealed, record, and pattern matching. Here is an example:

public sealed interface Error permits Error.ValidationErrors, Error.BusinessError, Error.TechnicalError {

    record ValidationErrors(List<ValidationError> errors) implements Error {
    }

    /**
     * Specific business errors.
     */
    public sealed interface BusinessError extends Error {

        /**
         * Describes the error when a publication reference is not found.
         *
         * @param reference the publication reference that was not found
         */
        record PublicationReferenceNotFound(String reference) implements BusinessError {
        }

    }

    /**
     * Specific technical errors.
     */
    public sealed interface TechnicalError extends Error {

        /**
         * The idea behind this (apparently) useless error is to have a way to represent a technical error that is not
         * within the scope of the application. For example, a database connection error or a network error when
         * implementing secondary/driven Adapters.
         * <p>Notice that, while other types of errors above do not carry a message, but the value that caused
         * the problem, this error requires a specific message, which may also include the value or whatever
         * information may be required to make the error clear to consumers.</p>
         *
         * @param message the error message, as provided by the underlying technology
         * @param cause   the cause of the error, as provided by the underlying technology
         */
        record SomethingWentWrong(String message, Throwable cause) implements TechnicalError {
        }

    }

}

public sealed interface ValidationError {

    record InvalidCountry(String countryCode) implements ValidationError {
    }

    record InvalidDocument(String documentNumber) implements ValidationError {
    }

    record InvalidKind(String kindCode) implements ValidationError {
    }

}

3. My HexArch establishes that all method's signatures (with the exception of validation methods that return Validation<ValidationError, Object>) must return a Either<Error, Object>, so eventually the Error will be propagated to the Input Ports, and available to the REST adapter, for example, to deal with it. And because I'm using ADTs with pattern matching, magic happens, as the compiler will not let me build without taking care of each error subtype (validation, business, technical):

   private String createFromValidationError(ValidationError validationError) {
        return switch (validationError) {
            case ValidationError.InvalidCountry countryError ->
                    "Invalid country code provided [%s]".formatted(countryError.countryCode());
            case ValidationError.InvalidKind kindError -> "Invalid kind provided [%s]".formatted(kindError.kindCode());
            case ValidationError.InvalidDocument documentError ->
                    "Invalid document number provided [%s]".formatted(documentError.documentNumber());
        };
    }

    private ApiResponse.Failure createFromBusinessError(Error.BusinessError businessError) {
        log.atTrace().setMessage("Business error received").log();
        return switch (businessError) {
            case Error.BusinessError.PublicationReferenceNotFound publicationReferenceNotFoundError ->
                    new ApiResponse.Failure(HttpStatus.NOT_FOUND.value(), List.of("Publication reference not found for [%s]".formatted(publicationReferenceNotFoundError.reference())));
        };
    }

    private ApiResponse.Failure createFromTechnicalError(Error.TechnicalError technicalError) {
        log.atTrace().setMessage("Technical error received").log();
        return switch (technicalError) {
            case Error.TechnicalError.SomethingWentWrong somethingWentWrongError ->
                    new ApiResponse.Failure(HttpStatus.INTERNAL_SERVER_ERROR.value(), List.of("Internal server error [%s]".formatted(somethingWentWrongError.message())));
        };
    }

4. Yes, but that's why, again, my architecture establishes a common pattern for the implementation of Output Ports, based on the Try monad that is converted into a Either, and "forces" the mapping into my error values.

Obviously, a developer can simply ignore (intentionally) the established ADRs, but that's unavoidable. As architects, our role is to set clear boundaries, patterns, and best practices to design clean and robust software, but unless we conduct detailed code reviews, things can escape our control. Tools such as ArchUnit can help out here, though.

[Sairyss]

I used to do it mostly in TypeScript (and also Scala, but Scala has first class support for these things so no issues here), never tried it in Java. I guess Java has better tooling to make these kind of things more secure than TypeScript, especially with things like better support for ADTs and pattern matching in Java 14+. And Project Valhalla will make it even better, so yeah.
If you end up doing it, I'd like to hear about your experience and how it ended up working for you :)

[emedina]

Sure, "quid pro quo"!