Chapter 8. Railway-oriented processing

So far, we have focused on what you might call the happy path within our unified log. On the happy path, events successfully validate against their schemas, inputs are never accidentally null, and Java exceptions are so rare that we don’t mind them crashing our application.

The problem with focusing exclusively on the happy path is that failures do happen. More than this: if you implement a unified log across your department or company, failures will happen extremely frequently, because of the sheer volume of events flowing through, and the complexity of your event stream processing. Linus’s law states, “Given enough eyeballs, all bugs are shallow.”^[1] Adapting this, a law of unified log processing might be as follows:

¹Linus’s law is further explained at Wikipedia, https://en.wikipedia.org/wiki/Linus%27s_Law.

Given enough events, all bugs are inevitable.

If we can expect and design for inevitable failure inside our stream processing applications, we can build a much more robust unified log, one that hopefully won’t page us regularly at 2 a.m. because it crashed Yet Another NullPointerException (YANPE). This chapter, then, is all about designing for failure, using an overarching approach that we will call railway-oriented processing. We have been using this approach at Snowplow throughout our event pipeline since the start of 2013, so we know that it can enable the processing of billions of events daily with a minimum of disruption.

For reasons that should become clear as we delve deeper into this topic, this chapter will be the first one where we work predominantly in Scala. Scala is a strongly typed, hybrid object-oriented and functional language that runs on the Java virtual machine. Scala has great support for railway-oriented processing—capabilities that even Java 8 lacks.

So, all aboard the railway-oriented programming express, and let’s get started.

8.1. Leaving the happy path

Two roads diverged in a wood, and I—

I took the one less traveled by,

And that has made all the difference.

Robert Frost, “The Road Not Taken” (1916)

Before diving into railway-oriented processing, let’s look at how failure is handled in two distinct environments that many readers will be familiar with: Unix programs and Java. We’ll then follow this up with general thoughts on error logging as it is practiced today.

8.1.1. Failure and Unix programs

Unix is designed around the idea that failures will happen. Any process that runs in a Unix shell will return an exit code when it finishes. The convention is to return zero for success, and an integer value higher than zero in the case of failure.

This exit, or return, code isn’t the only communication channel available to a Unix program; each program also has access to three standard streams (aka I/O file descriptors): stdin, stdout, and stderr. Table 8.1 provides the properties of these three streams.

Putting the exit codes and the three standard streams together, we can represent a Unix program’s happy and failure paths, as shown in figure 8.1.

It’s only correct to note, however, that things are not always as clear-cut as figure 8.1 implies:

How composable is failure handling in Unix programs? By composable, we mean that can we combine multiple successes and failures, and the combined result will still make sense. Let’s see—if you have a Unix terminal handy, type in the following:

If you are not familiar with false and true, these are super-simple Unix programs that return exit codes of 1 (failure) and 0 (success), respectively. In this example, we are combining two false programs with a true program, using the vertical bar character | (also known as a pipe) to make a Unix pipeline.

As you can see, the first two failures do not cause the pipeline to fail, and the ultimate return code of the pipeline is the return code of the last program run.

In some Unix shells (ksh, zsh, bash), we can do a little better than this by using the built-in pipefail option:

The pipefail option sets the exit code to the exit code of the last program to exit nonzero, or returns 0 if all exited successfully. This is an improvement, but the s3 output shows that the pipeline is still not short-circuiting, or failing fast, after an individual component within it fails. This is because a Unix pipeline is chaining input and output streams together, not exit codes, as demonstrated in figure 8.2.

If we do want to fail fast, we have to put our commands in a shell script that uses the set –e option, which will terminate the script as soon as any command within the script returns a nonzero error code. If you run the code in the following listing, you will see the following output; notice that the second echo in the shell script is never reached:

In sum: Unix programs and the Unix pipeline have powerful yet easy-to-understand features for dealing with failure. But they are not as composable as we would like.

8.1.2. Failure and Java

Let’s take a look now at how Java deals with failure. Java depends heavily on exceptions for handling failures, making a distinction between two types of exceptions:

Let’s look at the following HelloCalculator app, where we employ both unchecked and checked exceptions. The following listing contains the HelloCalculator.java code, annotated to show the use of both exception types.

Java’s built-in failure handling is broadly designed around two failure scenarios:

But what if we cannot recover from a failure but don’t want to terminate our overall program? This might sound counterintuitive: how can our program keep going with an unrecoverable failure? To be sure, many programs cannot—but some can, especially if they consist of processing many much smaller units of work, for example:

In each of these scenarios, the programmer may prefer to route the unrecoverable unit of work to a failure path rather than terminate the whole program, as shown in figure 8.3.

As with many other languages, Java does not have any built-in tools for routing failing units of work to a failure path. In situations like these, a Java programmer will often fall back to simply logging the failure as an error and skipping to the next unit of work. To demonstrate this, let’s imagine an updated version of the original HelloCalculator code: instead of summing all arguments together, our new version will increment (add 1 to) any numeric arguments, and log an error message for any arguments that are not numeric. This is illustrated in the following listing.

Copy the code from listing 8.3 and save it into a file, like so:

Next, we will compile our code and run it, supplying three valid and one invalid (non-numeric) argument:

See how our failure is buried in the middle of our successes? We have to look carefully at the program’s output to discern the failure output.

Worse, we have just outsourced this program’s failure path to our logging framework to handle. We can say that the failure path is now out-of-band: the failures are no longer present in the source code or influencing the program’s control flow. Incidentally, many experienced programmers criticize the concept of exceptions for a similar reason: they create a secondary control flow in a program, one that exists outside the standard imperative flow, and thus is difficult to reason about.^[2]

²Joel Spolsky’s essay on why exceptions are not always a good thing: https://www.joelonsoftware.com/2003/10/13/13/

Whatever the criticisms of exceptions, error logging is surely worse: it is not just outside the program’s main control flow, but also outside the program itself. The challenges of dealing with out-of-band error logging have fueled a whole software industry, which we will briefly look at next.

8.1.3. Failure and the log-industrial complex

A Java program, a Node.js program, and a Ruby program all walk into a bar. Each logs an error on the way in. The joke is on the barman, because they are all speaking different languages:

Amazingly, no common format exists for program logging: different languages and frameworks all have their own logging levels (error, warning, and so forth) and log message formats. Combine this with the fact that log messages are written using human language, and you are left with logs that can often be analyzed using only plain-text search.

Various logistical issues also are associated with outsourcing your failure path to a logging framework:

Collectively dealing with these issues around logging have spawned what we might call, only half-jokingly, the log-industrial complex, consisting of the following:

Even with all of this tooling, in a unified log context we still have another unsolved problem: how can we reprocess a failed unit of work (for example, an event) if and when the underlying issue that caused the failure is fixed?

In a unified log world, there has to be a better way of working with our failure path. We will explore this next.

8.2. Failure and the unified log

Reports that say that something hasn’t happened are always interesting to me, because as we know, there are known knowns; there are things we know we know. We also know there are known unknowns; that is to say, we know there are some things we do not know. But there are also unknown unknowns—the ones we don’t know we don’t know.

US Secretary of Defense Donald H. Rumsfeld (February 12, 2002)

In this section, we will set out a simple pattern for unified log processing that accounts for the failure path as well as the happy path. For our treatment of the failure path, we will borrow from the better ideas of section 8.1 and throw in some new ideas of our own.

8.2.1. A design for failure

How should we be handling failure in our unified log processing? First, let’s propose some rules governing program termination. We should terminate our job only if one of the following occurs:

A novel error means one that we haven’t seen before: a Rumsfeld-esque unknown unknown. Although it might be tempting to keep processing in this case to minimize disruption, terminating the job forces us to evaluate any novel error as soon as we encounter it. We can then determine how this new error should be handled in the future—for example, can it be recovered from without failing the unit of work?

Next, how do we handle an unrecoverable but not-unexpected error within a unit of work? Here there is no way around it—we have to move this unit of work into our failure path, but making sure to follow a few important rules:

Let’s make this a little more concrete with the example of a simple stream-processing job that is enriching individual events, as shown in figure 8.4.

Does the flow in figure 8.4 look familiar? It shares a lot in common with Unix’s concept of three standard streams: our stream processing app will read from one event stream, and write to two event streams, one for the happy path and the other for individual failures. At the same time, we have improved some of the failure-handling techniques of section 8.1:

This is a great start, but what do we mean when we say that our failures will end up as “well-structured entries” in an event stream? Let’s explore this next.

8.2.2. Modeling failures as events

How could we describe our stream processing job’s failure to enrich an event read from an input stream? Perhaps something like this:

At 12:24:07 in our production environment, SimpleEnrich v1 failed to enrich Inbound Event 428 because it failed JSON Schema validation.

Does this look familiar? It contains all the same grammatical components as the events we introduced in chapter 2:

We have another piece of context besides the timestamp: the environment in which the failure happened. Finally, we also have a prepositional object—namely, the reason that the enrichment failed. We call this prepositional because it is associated with the event via a prepositional phrase—in this case, “because of.” Figure 8.5 clarifies the relationship between our event’s constituent parts: subject, verb, direct object, prepositional object (the reason for the failure), and context.

It may seem a little strange to have the direct object of our failure event be an event—specifically, the inbound event that failed enrichment. But this “turtles all the way down” design is powerful: it means that our failure event contains within it all the information required to retry the failed processing in the future. Without this design, we would have to manually correlate the failure messages with the original input events if we wanted to attempt reprocessing of failed events in the future.

This might sound a little theoretical; after all, the events have failed processing with an unrecoverable error once. What makes us think that this error might be recoverable in the future? In fact, there are lots of reasons that we shouldn’t be binning this failed event just yet:

This last example is starting to hint at a key aspect of this design: its composability across multiple event streams within our unified log. We’ll look at this next.

8.2.3. Composing our happy path across jobs

If our stream processing jobs follow the simple architecture set out previously, we can create a happy path composed of multiple stream processing jobs: the happy path output of one job is fed in as the input of the next job. Figure 8.7 illustrates this process.

Figure 8.7 deliberately elides how we handle the failure paths of our individual jobs. How we handle the failure events emitted by a given job will depend on a few factors:

These kinds of questions may well have different answers for different stream-processing jobs. For example, a job auditing customer refunds might take individual failures much more seriously than a job providing vanity metrics for a display panel in reception. But by modeling our failures as events, we should be able to create highly reusable failure-handling jobs, because they speak our lingua franca of well-structured events.

8.3. Failure composition with Scalaz

If you fail to plan, you are planning to fail!

Benjamin Franklin

So far, we have looked at the concept of the failure path at an architectural level, but how do we implement these patterns inside our stream processing jobs? It’s time to add a new tag team to our unified log arsenal: Scala and Scalaz.

8.3.1. Planning for failure

Imagine that we are working at an online retailer that sells products in three currencies (euros, dollars, and pounds), but does all of this financial reporting in euros, its base currency. Our retailer already has all customer orders available in a stream in its unified log, so the managers want us to write a stream processing job that does the following:

The currency conversion will be done using the live (current) exchange rate, to keep things simple. Our job can look up the exchange rate by making an API call to a third-party service called Open Exchange Rates (https://openexchangerates.org/).

This sounds simple. What could go wrong with the operation of our job? In fact, a few things:

An interesting thing about these failures is that they are, as a management consultant might say, the opposite of mutually exclusive, collectively exhaustive (MECE):

Putting all this together, it is clear that our stream processing job will need to plan for failure: in addition to the output stream of orders in our base currency—our happy path—we will need a second output stream to report our currency conversion failures—our failure path. Figure 8.8 illustrates the overall job flow.

We are not particularly interested in the “plumbing” of this job; we have explored the mechanics of reading and writing to event streams in detail in previous chapters. This chapter is all about planning for failure—so the important thing is learning how to assemble the internal logic of this job in a way that can cope with all these possible failures.

For these purposes, we can work with a stripped-down Scala application—just a few functions, unit tests, and a simple command-line interface.

8.3.2. Setting up our Scala project

Let’s get started. We are going to create our Scala application by using Gradle. Scala Build Tool (SBT) is the more popular build tool for Scala, but we are familiar with Gradle and it works fine with Scala, so let’s stick with that.

First, create a directory called forex, and then switch to that directory and run the following:

As we did in chapter 3, we’ll now delete the stubbed Scala files that Gradle created:

The default build.gradle file in the project root isn’t quite what we need either, so replace it with the following code.

With that updated, let’s check that everything is still functional:

Okay, good—now let’s write some Scala code!

8.3.3. From Java to Scala

Remember that we need to check whether our customer order is one of our three supported currencies (euros, dollars, or pounds).

If we were still working in Java, we might write a function that threw a checked exception if the currency was not in one of our supported currencies. In the following listing, we have a function that parses the currency string:

One of the nice aspects of Scala for recovering Java programmers is that it’s possible to port existing Java code to Scala code (albeit unidiomatic Scala code) with only cosmetic syntactical changes. The following listing contains just such a direct, unidiomatic port of our existing CurrencyConverter class to a Scala object.

If you are completely new to Scala, here are a few immediate things to note about this code compared to Java:

There is an interesting difference in the behavior of our validateCurrency function too: our function now has the @throws annotation recording the exception that it may throw. Scala doesn’t distinguish between checked and unchecked exceptions, so this annotation is optional, and useful only if some Java code is going to call this function.

Another nice difference between Scala and Java is the interactive console, or read-eval-print loop (REPL), available with Scala. Let’s use this to put our new Scala code through its paces. From the project root, start up the REPL with this command:

The Scala prompt is waiting for you to type in a Scala statement to execute. Let’s try this one:

The second line shows you the output from the validateCurrency function: it’s returning a USD-flavored value from our Currency enumeration. Let’s check that the case-insensitivity is working too:

That seems to be working. Now let’s see what happens if we pass in an invalid value:

That looks correct. Trying to validate dogecoin as a currency is throwing an UnsupportedCurrencyException. We have ported our Java currency validator to Scala—but so far, we have only tweaked syntax; the semantics of our failure handling are the same. We can do better, as you’ll see in the next iteration.

8.3.4. Better failure handling through Scalaz

Let’s take a second pass at our currency validator. You can see the updated object, CurrencyValidator2, in the following listing. We haven’t changed our Currency enumeration, and are no longer using the UnsupportedCurrencyException, so these are left out.

Again, here are a few notes to make the following listing a little easier to digest:

Most important, in place of throwing exceptions, we have moved our failure path into the return value of our function: this complex-looking Validation type, provided by Scalaz. Let’s see how this Validation type behaves in the REPL; note that we have to quit and restart the console to force a recompile:

You can think of Validation as a kind of box, or context, that describes whether the value inside it is on our happy path (called Success in Scalaz) or our failure path (called Failure). Even neater, the value inside the Validation box can have a different type on the Success side versus on the Failure side:

The first type given, String, is the type that we will use for our failure path; the second type, Currency.Value, is the type that we will use for our success path. Figure 8.9 shows how Validation is working, using the metaphor of cardboard boxes and paths.

This switch from using exceptions to using Scalaz’s Validation to box either success or failure might not seem like a big change, but it’s going to be our key building block for working with failure in Scala.

8.3.5. Composing failures

We’re now happy with our function to validate that the incoming currency is one of our three supported currencies. But remember, another possible bug remains in our event stream:

Perhaps a hacker has managed to transact an order with a non-numeric order value, getting themselves a huge flat-screen TV for ¥l33t.

We can put a stop to this with an AmountValidator object containing another validation function: one that checks that the incoming stringly typed order amount can be parsed to a Scala Double. This is set out in the following listing.

By now, the pattern should be familiar: our function uses a Validation to represent our return value being either on the happy path (with a Success), or on the failure path (with a Failure). As before, we are returning different types of values inside our Success and our Failure: in this case, a Double or a String, respectively.

A quick check to make sure this is working in the Scala REPL:

Great! So we now have two validation functions:

Both functions would have to return a Success in order for us to assemble a valid order total. If we get a Failure, or indeed two Failures, then we will find ourselves squarely on the failure path. Let’s build a function now that attempts to construct an order total by running both of our validation functions. See the following listing for the code.

A lot of new things are certainly happening in a small amount of code, but don’t worry, we will go through this listing carefully in a short while. Before we do that, let’s return to the Scala REPL and see how this parse function performs, first if both the currency and amount are valid:

This result makes sense: because both validations passed, we are staying on the happy path, and our OrderTotal is boxed in a Success to reflect this. Now let’s see what happens if one or either of our validations fails:

In both cases, we end up with a Failure containing a NonEmptyList, which in turn contains our error message as a String. In fact, NonEmptyList is another Scalaz type. It’s similar to a standard Java or Scala List, except that a NonEmptyList (sometimes called a Nel, or NEL, for short) cannot be, well, empty. This suits our purposes well; if we have a Failure, we know at least one cause of it, and so our list of error messages will never be empty.

Why do we need a NEL on the Failure side in the first place? Hopefully, this next test should make the reason clear:

It’s a little bit long-winded, but you can see that the value returned from the parse function is now a Failure dutifully recording both error messages in String form; this approach is similar to the way you might see multiple validation errors (Phone Is Missing Country Code, and so forth) on a website form when you click the Submit button.

Now that you understand what the function does, let’s return to the code itself:

What exactly is going on here, and what is that mysterious |@| operator doing? The first thing to explain is the toValidationNel method calls. There is not much mystery here: this is a method available to any Scalaz Validation that will promote the Failure value into a NEL. Here’s a quick demonstration in the Scala REPL:

See how the error message is now inside a NEL? This happens only in the case of Failure. If we have a Success, the value inside is untouched, although the overall type of the Validation will still change:

Now onto the |@| operator. Unfortunately, there is no official Scalaz documentation about this, but if you dig into the code, you will find it referred to as follows:

[a] DSL for constructing Applicative expressions

The |@| operator is sometimes referred to as the Home Alone or chelsea bun operator, but we prefer to call it the Scream operator after the Munch painting. Regardless, this operator is doing something clever: it is composing our two input Validations into a new output Validation, intelligently determining whether the output Validation should be a Success or a Failure based on the inputs. Figure 8.10 shows the different options.

As you can see in figure 8.10, the Scream operator allows us to compose multiple Validation inputs into a single Validation output. The example uses two inputs just to keep things simple: we could just as easily compose nine or twenty Validation inputs into a single Validation output. If we composed twenty Validation inputs with the Scream operator, all of our twenty inputs must be a Success for us to end up with a Success output. On the other hand, if all of our twenty inputs were Failures containing a single error String, then our output would be a Failure containing a NonEmptyList of twenty error Strings.

You have seen how to handle failure inside a single processing step: we can perform multiple pieces of validation in parallel, and then compose the successes or failures into a single output. If this is failure processing in the small, how do we start to handle failures between different processing steps inside the same job? We’ll look at this next. Feel free to grab a cup of coffee before you apply what you’ve learned so far on our unified log.

8.4. Implementing railway-oriented processing

Everything has an end, and you get to it if you only keep all on.

E. Nesbit, The Railway Children

A common theme running through this chapter has been the idea of our code embarking on a happy path and dropping down to a failure path if something (or multiple things) goes wrong. We have looked at this pattern at a large scale, across multiple stream processing jobs, as well as at a small scale, at the level of composing multiple failures inside a single processing step. Now let’s look at the middle ground: handling failure across multiple processing steps inside a single job.

8.4.1. Introducing railway-oriented processing

In the preceding section, the Scream operator let us compose an output from separate pieces of processing into a single unified output. Specifically, we composed the Validation outputs from our currency and amount parsing into a single Validation output. Where do we go from here?

Remembering back to our original brief, we also need the current exchange rate between our order’s currency and our employer’s base currency. Again, this requirement could also take us onto the failure path: fetching the exchange rate could fail for various reasons. We have several processing steps now, so let’s sketch out an end-to-end happy path that incorporates all of this processing. Figure 8.11 presents two separate versions of this happy path:

The pragmatic happy path is so-called because looking up a currency from a third-party service’s API over HTTP is an expensive operation, whereas validating our order amount is relatively cheap. We could be performing this processing job for many millions of events, so even small unnecessary delays will add up; therefore, if we can fail fast and save ourselves some pointless currency lookups, we should.

Figure 8.11 shows us only the end-to-end happy path, resulting in a customer order successfully converted into the retailer’s base currency. Figure 8.12 provides the next level of detail, imagining our processing job as a railway line (or conveyor belt), with two tracks:

This is not my own metaphor: railway-oriented programming was coined by functional programmer Scott Wlaschin in his eponymous blog post (https://fsharpforfunandprofit.com/posts/recipe-part2/). Scott’s blog post uses the railway metaphor with happy and failure paths to introduce compositional failure handling in the F# programming language. Another functional language, F# enables a similar approach to failure processing to our Scala-plus-Scalaz combination. We strongly recommend reading Scott’s post after you have finished this chapter; in the meantime, here is railway-oriented programming in Scott’s own words:

What we want to do is connect the Success output of one to the input of the next, but somehow bypass the second function in case of a Failure output....There is a great analogy for doing this—something you are probably already familiar with. Railways! Railways have switches (“points” in the UK) for directing trains onto a different track. We can think of these “Success/Failure” functions as railway switches....We will have a series of black-box functions that appear to be straddling a two-track railway, each function processing data and passing it down the track to the next function....Note that once we get on the failure path, we never (normally) get back onto the happy path. We just bypass the rest of the functions until we reach the end.

The railway-oriented approach has important properties that might not be immediately obvious but affect how we use it:

Enough of the theory for now—let’s build our railway in Scala.

8.4.2. Building the railway

First, we need a function representing our exchange-rate lookup, which could fail. Because our focus in this chapter is on failure handling, our function will contain some hardcoded exchange rates plus some hardwired “random failure.” If you are interested in looking up real exchange rates in Open Exchange Rates, you can always check out Snowplow’s scala-forex project (https://github.com/snowplow/scala-forex/).

The code for our new function, lookup, is in the following listing. The function consists of a single pattern-match expression that returns the following:

If you haven’t seen a pattern match before, you can think of it as similar to a C- or Java-like switch statement, but much more powerful. We can match against specific cases such as Currency.Eur, and we can also perform wildcard matches using _. The if isUnlucky() is called a guard; it makes sure that we match this pattern only if the condition is met. As you can see from the definition of the isUnlucky function, we are simulating a network failure that should happen 20% of the time when we are looking up the exchange rate over the network.

An important point on the final _ wildcard match: we include this to ensure that our pattern match is exhaustive—that all possible patterns that could occur are handled. Without this final wildcard match, the code would still compile, but we are sitting on a potential problem if the following occur:

In this case, the pattern match would throw a runtime MatchError on every yen lookup, causing our stream processing job to crash. We want to avoid this, so our final _ wildcard match defends against this pre-bug, a bug that has not happened yet.

Let’s put our new function through its paces in the Scala REPL:

Great—that’s all working fine. Our network connection is also suitably unreliable; every so often when looking up a rate, you should see an error like this:

Now, remembering back to section 8.3, we have two functions that represent the two distinct steps in our processing, either of which could fail. Here are the signatures of both functions:

Note that the types on our failure track are not quite the same: a NonEmptyList of Strings, versus a singular String. In theory, this sounds like it breaks the rule that “every Failure must contain the same type,” but in practice it is easy to promote a single String to be a NonEmptyList of Strings.

Remember that we want to try to generate an order total first, and only then look up our exchange rate. Let’s create a new function, OrderTotalConverter1.convert, which captures all of the processing we need to do in this job. The signature of this function should look like this:

You haven’t seen ValidationNel[A, B] before. This is Scalaz shorthand for Validation[NonEmptyList[A], B]. Putting this all together: we will attempt to generate an OrderTotal in our base currency from an incoming raw currency and order total. If we somehow end up on the failure path, we will return a NonEmptyList of the error Strings that we encountered. Let’s see an implementation of this function in the following listing.

There is some interesting new syntax here; that for {} yield is clearly not your grandfather’s for loop! Before we dive into this, let’s fire up the Scala REPL one last time for this chapter and put this function through its paces. First let’s stick to the happy path (assuming our unreliable network lets us):

Now let’s see about the failure path:

You might have to repeat the second conversion a few times to see the Network Error Failure caused by the exchange rate lookup. Also, remember that you will see the network error only if the raw currency and amount are valid: if either is invalid, we have already failed fast, and the exchange rate will not be looked up.

So our convert() function is working, but how is it working? The key is to understand the for {} yield construct. Wherever you see the for keyword in Scala, you are looking at a Scala for comprehension, which is syntactic sugar over a set of Scala’s functional operations: foreach, map, flatMap, filter, or withFilter.^[3] This is modeled on the do notation found in Haskell, a pure functional language.

³More information on how the Scala yield keyword works can be found at https://docs.scala-lang.org/tutorials/FAQ/yield.html.

Scala will translate our for {} yield into a set of flatMap and map operations, as shown in listing 8.12. The code in OrderTotalConverter2 is functionally identical to our previous OrderTotalConverter1; you can test it at the Scala REPL if you like:

Putting them side by side, OrderTotalConverter1 is much more readable than OrderTotalConverter2, but this second version gives us a better starting point for understanding how we have implemented this fail-fast approach across multiple processing steps. This is the last piece of the railway-oriented processing puzzle.

Also note that OrderTotalConverter1 does work only when compiled against Scala 2.11, as Scala 2.12 has introduced enhanced type checking that made type inference inside for comprehensions more difficult to achieve.

flatMap and map are the last two pieces in our toolkit for this chapter, so we’ll go through these in some detail. We’ll start with map as it’s simpler to understand. Here is a simplified definition for the map method on a Validation[F, S] called self:

Because this is Scala, we are able to define map in terms of a single pattern-match expression. The way to read aFunc: S => T is as a function that takes an argument of type S and returns a value of type T. If our Validation is a Success, we apply the function supplied to map to the value contained inside the Success, resulting in a new value, possibly of a new type, but still safely wrapped in our Validation container. To put it another way: if we start with Success[S] and apply a function S => T to the value inside Success, we end up with Success[T]. On the other hand, if our Validation is a Failure, we leave this as is: a Failure[F] stays a Failure[F], containing the exact same value.

Mapping over a Validation is visualized in figure 8.13, for both a Success and a Failure.

Now let’s take a look at flatMap. Like map, flatMap takes a function, applies it to a Validation[F, S], and returns a Validation[F, T]. The difference is in the function that flatMap takes as its argument: the function has the type S => Validation[F, T]. In other words, flatMap expects a function that takes a value and produces a new value inside a new Validation container. You may be thinking, hang on a moment—why does a flatMap, like a map, return this

and not this:

The answer to this question lies in the flat in the name: flatMap flattens the two Validation containers into one. flatMap is the secret sauce of our railway-oriented approach: it allows us to chain multiple processing steps together into one stream processing job without accumulating another layer of Validation boxing at every stage. Figure 8.14 depicts the unworkable alternative.

The simplified definition for flatMap on a Validation[F, S] called self should look familiar after map:

The two differences from map are as follows:

Putting this all together, figure 8.15 attempts to visualize how our convert function is working.

The key point to understand here is that flatMap and map support our railway-oriented processing approach across multiple work steps:

This completes our look at failure handling in the unified log. If we take a moment’s breath and look back over the previous three sections, we see an interesting pattern emerging, one that you could call the compose, fail-fast, compose sandwich (or burger, if you prefer). To explain myself:

Summary