ploeh blog https://blog.ploeh.dk danish software design en-us Mark Seemann Mon, 30 Mar 2020 08:05:56 UTC Mon, 30 Mar 2020 08:05:56 UTC Repeatable execution in Haskell https://blog.ploeh.dk/2020/03/30/repeatable-execution-in-haskell/ Mon, 30 Mar 2020 08:02:00 UTC <div id="post"> <p> <em>A way to figure out what to log, and what not to log, using Haskell.</em> </p> <p> This article is part of <a href="/2020/03/23/repeatable-execution">a series of articles about repeatable execution</a>. The previous article argued that if you've logged the impure actions that a system made, you have enough information to reproduce what happened. </p> <p> In most languages, <a href="/2020/02/24/discerning-and-maintaining-purity">it's difficult to discriminate between pure functions and impure actions</a>, but <a href="https://www.haskell.org">Haskell</a> explicitly makes that distinction. I often use it for proof of concepts for that reason. I'll do that here as well. </p> <p> This proof of concept is mostly to verify what a decade of functional programming has already taught me. For the functionality that the previous article introduced, the impure actions involve a database and the system clock. </p> <p> The code shown in this article is <a href="https://github.com/ploeh/reservation-api-slice-haskell">available on GitHub</a>. </p> <h3 id="1c5f6ac50111450c8cf9b6d064977bcc"> Pure interactions <a href="#1c5f6ac50111450c8cf9b6d064977bcc" title="permalink">#</a> </h3> <p> I'll use <a href="/2017/07/10/pure-interactions">free monads to model impure interactions as pure functions</a>. For this particular example code base, an <a href="/2020/03/02/impureim-sandwich">impureim sandwich</a> would have been sufficient. I do, however, get the impression that many readers find it hard to extrapolate from impureim sandwiches to a general architecture. For the benefit of those readers, the example uses free monads. </p> <p> The system clock interaction is the simplest: </p> <p> <pre><span style="color:blue;">newtype</span>&nbsp;ClockInstruction&nbsp;next&nbsp;=&nbsp;CurrentTime&nbsp;(LocalTime&nbsp;-&gt;&nbsp;next)&nbsp;<span style="color:blue;">deriving</span>&nbsp;Functor</pre> </p> <p> There's only one instruction. It takes no input, but returns the current time and date. </p> <p> For database interactions, I went through a few iterations and arrived at this set of instructions: </p> <p> <pre><span style="color:blue;">data</span>&nbsp;ReservationsInstruction&nbsp;next&nbsp;= &nbsp;&nbsp;&nbsp;&nbsp;ReadReservation&nbsp;UUID&nbsp;(Maybe&nbsp;Reservation&nbsp;-&gt;&nbsp;next) &nbsp;&nbsp;|&nbsp;ReadReservations&nbsp;LocalTime&nbsp;([Reservation]&nbsp;-&gt;&nbsp;next) &nbsp;&nbsp;|&nbsp;CreateReservation&nbsp;Reservation&nbsp;next &nbsp;&nbsp;<span style="color:blue;">deriving</span>&nbsp;Functor</pre> </p> <p> There's two queries and a command. The intent with the <code>CreateReservation</code> command is to create a new reservation row in the database. The two queries fetch a single reservation based on ID, or a set of reservations based on a date. A central type for this instruction set is <code>Reservation</code>: </p> <p> <pre><span style="color:blue;">data</span>&nbsp;Reservation&nbsp;=&nbsp;Reservation &nbsp;&nbsp;{&nbsp;reservationId&nbsp;::&nbsp;UUID &nbsp;&nbsp;,&nbsp;reservationDate&nbsp;::&nbsp;LocalTime &nbsp;&nbsp;,&nbsp;reservationName&nbsp;::&nbsp;String &nbsp;&nbsp;,&nbsp;reservationEmail&nbsp;::&nbsp;String &nbsp;&nbsp;,&nbsp;reservationQuantity&nbsp;::&nbsp;Int &nbsp;&nbsp;}&nbsp;<span style="color:blue;">deriving</span>&nbsp;(<span style="color:#2b91af;">Eq</span>,&nbsp;<span style="color:#2b91af;">Show</span>,&nbsp;<span style="color:#2b91af;">Read</span>,&nbsp;<span style="color:#2b91af;">Generic</span>)</pre> </p> <p> The program has to interact both with the system clock and the database, so ultimately it turned out to be useful to combine these two instruction sets into one: </p> <p> <pre><span style="color:blue;">type</span>&nbsp;ReservationsProgram&nbsp;=&nbsp;Free&nbsp;(Sum&nbsp;ReservationsInstruction&nbsp;ClockInstruction)</pre> </p> <p> I used the <code>Sum</code> functor to combine the two instruction sets, and then turned them into a <code>Free</code> monad. </p> <p> With free monads, I find that my code becomes more readable if I define helper functions for each instruction: </p> <p> <pre><span style="color:#2b91af;">readReservation</span>&nbsp;::&nbsp;<span style="color:blue;">UUID</span>&nbsp;<span style="color:blue;">-&gt;</span>&nbsp;<span style="color:blue;">ReservationsProgram</span>&nbsp;(<span style="color:#2b91af;">Maybe</span>&nbsp;<span style="color:blue;">Reservation</span>) readReservation&nbsp;rid&nbsp;=&nbsp;liftF&nbsp;$&nbsp;InL&nbsp;$&nbsp;ReadReservation&nbsp;rid&nbsp;<span style="color:blue;">id</span> <span style="color:#2b91af;">readReservations</span>&nbsp;::&nbsp;<span style="color:blue;">LocalTime</span>&nbsp;<span style="color:blue;">-&gt;</span>&nbsp;<span style="color:blue;">ReservationsProgram</span>&nbsp;[<span style="color:blue;">Reservation</span>] readReservations&nbsp;t&nbsp;=&nbsp;liftF&nbsp;$&nbsp;InL&nbsp;$&nbsp;ReadReservations&nbsp;t&nbsp;<span style="color:blue;">id</span> <span style="color:#2b91af;">createReservation</span>&nbsp;::&nbsp;<span style="color:blue;">Reservation</span>&nbsp;<span style="color:blue;">-&gt;</span>&nbsp;<span style="color:blue;">ReservationsProgram</span>&nbsp;() createReservation&nbsp;r&nbsp;=&nbsp;liftF&nbsp;$&nbsp;InL&nbsp;$&nbsp;CreateReservation&nbsp;r&nbsp;<span style="color:blue;">()</span> <span style="color:#2b91af;">currentTime</span>&nbsp;::&nbsp;<span style="color:blue;">ReservationsProgram</span>&nbsp;<span style="color:blue;">LocalTime</span> currentTime&nbsp;=&nbsp;liftF&nbsp;$&nbsp;InR&nbsp;$&nbsp;CurrentTime&nbsp;<span style="color:blue;">id</span></pre> </p> <p> There's much else going on in the code base, but that's how I model feature-specific impure actions. </p> <h3 id="46812b6dc4594937b0697ca09134af83"> Receive a reservation <a href="#46812b6dc4594937b0697ca09134af83" title="permalink">#</a> </h3> <p> The central feature of the service is to receive and handle an HTTP POST request, as described in the introductory article. When a document arrives it triggers a series of non-trivial work: <ol> <li>The service validates the input data. Among other things, it checks that the reservation is in the future. It uses <code>currentTime</code> for this.</li> <li>It queries the database for existing reservations. It uses <code>readReservations</code> for this.</li> <li>It uses complex business logic to determine whether to accept the reservation. This essentially implements the <a href="/2020/01/27/the-maitre-d-kata">Ma&icirc;tre d' kata</a>.</li> <li>If it accepts the reservation, it stores it. It uses <code>createReservation</code> for this.</li> </ol> These steps manifest as this function: </p> <p> <pre><span style="color:#2b91af;">tryAccept</span>&nbsp;::&nbsp;<span style="color:blue;">NominalDiffTime</span> &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">-&gt;</span>&nbsp;[<span style="color:blue;">Table</span>] &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">-&gt;</span>&nbsp;<span style="color:blue;">Reservation</span> &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">-&gt;</span>&nbsp;<span style="color:blue;">ExceptT</span>&nbsp;(<span style="color:blue;">APIError</span>&nbsp;<span style="color:blue;">ByteString</span>)&nbsp;<span style="color:blue;">ReservationsProgram</span>&nbsp;() tryAccept&nbsp;seatingDuration&nbsp;tables&nbsp;r&nbsp;=&nbsp;<span style="color:blue;">do</span> &nbsp;&nbsp;now&nbsp;&lt;-&nbsp;lift&nbsp;currentTime &nbsp;&nbsp;_&nbsp;&lt;-&nbsp;liftEither&nbsp;$&nbsp;validateReservation&nbsp;now&nbsp;r &nbsp;&nbsp;reservations&nbsp;&lt;- &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">fmap</span>&nbsp;(removeNonOverlappingReservations&nbsp;seatingDuration&nbsp;r)&nbsp;&lt;$&gt; &nbsp;&nbsp;&nbsp;&nbsp;lift&nbsp;$&nbsp;readReservations&nbsp;$&nbsp;reservationDate&nbsp;r &nbsp;&nbsp;_&nbsp;&lt;-&nbsp;liftEither&nbsp;$&nbsp;canAccommodateReservation&nbsp;tables&nbsp;reservations&nbsp;r &nbsp;&nbsp;lift&nbsp;$&nbsp;createReservation&nbsp;r</pre> </p> <p> If you're interested in details, the code is available on GitHub. I may later write other articles about interesting details. </p> <p> In the context of repeatable execution and logging, the key is that this is a <a href="https://en.wikipedia.org/wiki/Pure_function">pure function</a>. It does, however, return a <code>ReservationsProgram</code> (free monad), so it's not going to <em>do</em> anything until interpreted. The interpreters are impure, so this is where logging has to take place. </p> <h3 id="3cc3141ffcc644c78618f117c53f66ba"> HTTP API <a href="#3cc3141ffcc644c78618f117c53f66ba" title="permalink">#</a> </h3> <p> The above <code>tryAccept</code> function is decoupled from boundary concerns. It has little HTTP-specific functionality. </p> <p> I've written the actual HTTP API using <a href="https://www.servant.dev">Servant</a>. The following function translates the above Domain Model to an HTTP API: </p> <p> <pre><span style="color:blue;">type</span>&nbsp;ReservationsProgramT&nbsp;=&nbsp;FreeT&nbsp;(Sum&nbsp;ReservationsInstruction&nbsp;ClockInstruction) <span style="color:#2b91af;">reservationServer</span>&nbsp;::&nbsp;<span style="color:blue;">NominalDiffTime</span> &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">-&gt;</span>&nbsp;[<span style="color:blue;">Table</span>] &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">-&gt;</span>&nbsp;<span style="color:blue;">ServerT</span>&nbsp;<span style="color:blue;">ReservationAPI</span>&nbsp;(<span style="color:blue;">ReservationsProgramT</span>&nbsp;<span style="color:blue;">Handler</span>) reservationServer&nbsp;seatingDuration&nbsp;tables&nbsp;=&nbsp;getReservation&nbsp;:&lt;|&gt;&nbsp;postReservation &nbsp;&nbsp;<span style="color:blue;">where</span> &nbsp;&nbsp;&nbsp;&nbsp;getReservation&nbsp;rid&nbsp;=&nbsp;<span style="color:blue;">do</span> &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;mr&nbsp;&lt;-&nbsp;toFreeT&nbsp;$&nbsp;readReservation&nbsp;rid &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">case</span>&nbsp;mr&nbsp;<span style="color:blue;">of</span> &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;Just&nbsp;r&nbsp;-&gt;&nbsp;<span style="color:blue;">return</span>&nbsp;r &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;Nothing&nbsp;-&gt;&nbsp;throwError&nbsp;err404 &nbsp;&nbsp;&nbsp;&nbsp;postReservation&nbsp;r&nbsp;=&nbsp;<span style="color:blue;">do</span> &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;e&nbsp;&lt;-&nbsp;toFreeT&nbsp;$&nbsp;runExceptT&nbsp;$&nbsp;tryAccept&nbsp;seatingDuration&nbsp;tables&nbsp;r &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">case</span>&nbsp;e&nbsp;<span style="color:blue;">of</span> &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;Right&nbsp;<span style="color:blue;">()</span>&nbsp;-&gt;&nbsp;<span style="color:blue;">return</span>&nbsp;<span style="color:blue;">()</span> &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;Left&nbsp;(ValidationError&nbsp;err)&nbsp;-&gt;&nbsp;throwError&nbsp;$&nbsp;err400&nbsp;{&nbsp;errBody&nbsp;=&nbsp;err&nbsp;} &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;Left&nbsp;&nbsp;(ExecutionError&nbsp;err)&nbsp;-&gt;&nbsp;throwError&nbsp;$&nbsp;err500&nbsp;{&nbsp;errBody&nbsp;=&nbsp;err&nbsp;}</pre> </p> <p> This API also exposes a reservation as a resource you can query with a <code>GET</code> request, but I'm not going to comment much on that. It uses the above <code>readReservation</code> helper function, but there's little logic involved in the implementation. </p> <p> The above <code>reservationServer</code> function implements, by the way, only a <em>partial</em> API. It defines the <code>/reservations</code> resource, as explained in the overview article. Its type is defined as: </p> <p> <pre><span style="color:blue;">type</span>&nbsp;ReservationAPI&nbsp;= &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;Capture&nbsp;<span style="color:#a31515;">&quot;reservationId&quot;</span>&nbsp;UUID&nbsp;:&gt;&nbsp;Get&nbsp;&#39;[JSON]&nbsp;Reservation &nbsp;&nbsp;:&lt;|&gt;&nbsp;ReqBody&nbsp;&#39;[JSON]&nbsp;Reservation&nbsp;:&gt;&nbsp;Post&nbsp;&#39;[JSON]&nbsp;<span style="color:blue;">()</span></pre> </p> <p> That's just one resource. <em>Servant</em> enables you define many resources and combine them into a larger API. For this example, the <code>/reservations</code> resource is all there is, so I define the entire API like this: </p> <p> <pre><span style="color:blue;">type</span>&nbsp;API&nbsp;=&nbsp;<span style="color:#a31515;">&quot;reservations&quot;</span>&nbsp;:&gt;&nbsp;ReservationAPI</pre> </p> <p> You can also define your complete <code>server</code> from several partial services, but in this example, I only have one: </p> <p> <pre>server&nbsp;=&nbsp;reservationServer</pre> </p> <p> Had I had more resources, I could have combined several values with a combinator, but now that I have only <code>reservationServer</code> it seems redundant, I admit. </p> <h3 id="678638fe747f41c491994dc43be49d7b"> Hosting the API <a href="#678638fe747f41c491994dc43be49d7b" title="permalink">#</a> </h3> <p> The <code>reservationServer</code> function, and thereby also <code>server</code>, returns a <code>ServerT</code> value. <em>Servant</em> ultimately demands a <code>Server</code> value to <code>serve</code> it. We need to transform the <code>ServerT</code> value into a <code>Server</code> value, which we can do with <code>hoistServer</code>: </p> <p> <pre><span style="color:#2b91af;">runApp</span>&nbsp;::&nbsp;<span style="color:#2b91af;">String</span>&nbsp;<span style="color:blue;">-&gt;</span>&nbsp;<span style="color:#2b91af;">Int</span>&nbsp;<span style="color:blue;">-&gt;</span>&nbsp;<span style="color:#2b91af;">IO</span>&nbsp;() runApp&nbsp;connStr&nbsp;port&nbsp;=&nbsp;<span style="color:blue;">do</span> &nbsp;&nbsp;<span style="color:blue;">putStrLn</span>&nbsp;$&nbsp;<span style="color:#a31515;">&quot;Starting&nbsp;server&nbsp;on&nbsp;port&nbsp;&quot;</span>&nbsp;++&nbsp;<span style="color:blue;">show</span>&nbsp;port&nbsp;++&nbsp;<span style="color:#a31515;">&quot;.&quot;</span> &nbsp;&nbsp;<span style="color:blue;">putStrLn</span>&nbsp;<span style="color:#a31515;">&quot;Press&nbsp;Ctrl&nbsp;+&nbsp;C&nbsp;to&nbsp;stop&nbsp;the&nbsp;server.&quot;</span> &nbsp;&nbsp;ls&nbsp;&lt;-&nbsp;loggerSet &nbsp;&nbsp;<span style="color:blue;">let</span>&nbsp;logLn&nbsp;s&nbsp;=&nbsp;pushLogStrLn&nbsp;ls&nbsp;$&nbsp;toLogStr&nbsp;s &nbsp;&nbsp;<span style="color:blue;">let</span>&nbsp;hoistSQL&nbsp;=&nbsp;hoistServer&nbsp;api&nbsp;$&nbsp;runInSQLServerAndOnSystemClock&nbsp;logLn&nbsp;$&nbsp;pack&nbsp;connStr &nbsp;&nbsp;(seatingDuration,&nbsp;tables)&nbsp;&lt;-&nbsp;readConfig &nbsp;&nbsp;logHttp&nbsp;&lt;-&nbsp;logHttpMiddleware&nbsp;ls &nbsp;&nbsp;run&nbsp;port&nbsp;$&nbsp;logHttp&nbsp;$&nbsp;serve&nbsp;api&nbsp;$&nbsp;hoistSQL&nbsp;$&nbsp;server&nbsp;seatingDuration&nbsp;tables</pre> </p> <p> The <code>hoistServer</code> function enables you to translate a <code>ServerT api m</code> into a <code>ServerT api n</code> value. Since <code>Server</code> is a type alias for <code>ServerT api Handler</code>, we need to translate the complicated monad returned from <code>server</code> into a <code>Handler</code>. The <code>runInSQLServerAndOnSystemClock</code> function does most of the heavy lifting. </p> <p> You'll also notice that the <code>runApp</code> function configures some logging. Apart from some HTTP-level middleware, the <code>logLn</code> function logs a line to a text file. The <code>runApp</code> function passes it as an argument to the <code>runInSQLServerAndOnSystemClock</code> function. We'll return to logging later in this article, but first I find it instructive to outline what happens in <code>runInSQLServerAndOnSystemClock</code>. </p> <p> As the name implies, two major actions take place. The function interprets database interactions by executing impure actions against SQL Server. It also interprets clock interactions by querying the system clock. </p> <h3 id="05b701cca27f44479c4c3bc1d169d935"> Using the system clock <a href="#05b701cca27f44479c4c3bc1d169d935" title="permalink">#</a> </h3> <p> The system-clock-based interpreter is the simplest of the two interpreters. It interprets <code>ClockInstruction</code> values by querying the system clock for the current time: </p> <p> <pre><span style="color:#2b91af;">runOnSystemClock</span>&nbsp;::&nbsp;<span style="color:blue;">MonadIO</span>&nbsp;m&nbsp;<span style="color:blue;">=&gt;</span>&nbsp;<span style="color:blue;">ClockInstruction</span>&nbsp;(m&nbsp;a)&nbsp;<span style="color:blue;">-&gt;</span>&nbsp;m&nbsp;a runOnSystemClock&nbsp;(CurrentTime&nbsp;next)&nbsp;=&nbsp;liftIO&nbsp;(zonedTimeToLocalTime&nbsp;&lt;$&gt;&nbsp;getZonedTime)&nbsp;&gt;&gt;=&nbsp;next</pre> </p> <p> This function translates a <code>ClockInstruction (m a)</code> to an <code>m a</code> value by executing the impure <code>getZonedTime</code> function. From the returned <code>ZonedTime</code> value, it then extracts the local time, which it passes to <code>next</code>. </p> <p> You may have two questions: <ul> <li>Why map <code>ClockInstruction (m a)</code> instead of <code>ClockInstruction a</code>?</li> <li>Why <code>MonadIO</code>?</li> </ul> I'll address each in turn. </p> <p> My ultimate goal with each of these interpreters is to compose them into <code>runInSQLServerAndOnSystemClock</code>. As described above, this function transforms <code>ServerT API (ReservationsProgramT Handler)</code> into a <code>ServerT API Handler</code> (also known as <code>Server API</code>). Another way to put this is that we need to collapse <code>ReservationsProgramT Handler</code> to <code>Handler</code> by, so to speak, removing <code>ReservationsProgramT</code>. </p> <p> Recall that a type like <code>ReservationsProgramT Handler</code> is really in 'curried' form. This is actually the parametrically polymorphic type <code>ReservationsProgramT Handler a</code>. Likewise, <code>Handler</code> is also parametrically polymorphic: <code>Handler a</code>. What we need, then, is a function with the type <code>ReservationsProgramT Handler a -&gt; Handler a</code> or, more generally, <code>FreeT f m a -&gt; m a</code>. This follows because <code>ReservationsProgramT</code> is an alias for <code>FreeT ...</code>, and <code>Handler</code> is <a href="https://bartoszmilewski.com/2014/01/14/functors-are-containers">a container</a> of <code>a</code> values. </p> <p> There's a function for that in <a href="http://hackage.haskell.org/package/free/docs/Control-Monad-Trans-Free.html">Control.Monad.Trans.Free</a> called <code>iterT</code>: </p> <p> <pre><span style="color:#2b91af;">iterT</span>&nbsp;::&nbsp;(<span style="color:blue;">Functor</span>&nbsp;f,&nbsp;<span style="color:blue;">Monad</span>&nbsp;m)&nbsp;<span style="color:blue;">=&gt;</span>&nbsp;(f&nbsp;(m&nbsp;a)&nbsp;<span style="color:blue;">-&gt;</span>&nbsp;m&nbsp;a)&nbsp;<span style="color:blue;">-&gt;</span>&nbsp;<span style="color:blue;">FreeT</span>&nbsp;f&nbsp;m&nbsp;a&nbsp;<span style="color:blue;">-&gt;</span>&nbsp;m&nbsp;a</pre> </p> <p> This fits our need. For each of the functors in <code>ReservationsProgramT</code>, then, we need a function <code>f (m a) -&gt; m a</code>. Specifically, for <code>ClockInstruction</code>, we need to define a function with the type <code>ClockInstruction (Handler a) -&gt; Handler a</code>. Consider, however, the definition of <code>Handler</code>. It's a <code>newtype</code> over a <code>newtype</code>, so much wrapping is required. If I specifically wanted to return that explicit type, I'd have to take the <code>IO</code> vale produced by <code>getZonedTime</code> and wrap it in <code>Handler</code>, which would require me to first wrap it in <code>ExceptT</code>, which again would require me to wrap it in <code>Either</code>. That's a lot of bother, but <code>Handler</code> is also a <code>MonadIO</code> instance, and that elegantly sidesteps the issue. By implementing <code>runOnSystemClock</code> with <code>liftIO</code>, it works for all <code>MonadIO</code> instances, including <code>Handler</code>. </p> <p> Hopefully, that explains why <code>runOnSystemClock</code> has the type that it has. </p> <h3 id="9f530f57c49549b6823c45859ee5890c"> Using the database <a href="#9f530f57c49549b6823c45859ee5890c" title="permalink">#</a> </h3> <p> The database interpreter is more complex than <code>runOnSystemClock</code>, but it follows the same principles. The reasoning outlined above also apply here. </p> <p> <pre><span style="color:#2b91af;">runInSQLServer</span>&nbsp;::&nbsp;<span style="color:blue;">MonadIO</span>&nbsp;m&nbsp;<span style="color:blue;">=&gt;</span>&nbsp;<span style="color:blue;">Text</span>&nbsp;<span style="color:blue;">-&gt;</span>&nbsp;<span style="color:blue;">ReservationsInstruction</span>&nbsp;(m&nbsp;a)&nbsp;<span style="color:blue;">-&gt;</span>&nbsp;m&nbsp;a runInSQLServer&nbsp;connStr&nbsp;(ReadReservation&nbsp;rid&nbsp;next)&nbsp;= &nbsp;&nbsp;liftIO&nbsp;(readReservation&nbsp;connStr&nbsp;rid)&nbsp;&gt;&gt;=&nbsp;next runInSQLServer&nbsp;connStr&nbsp;(ReadReservations&nbsp;t&nbsp;next)&nbsp;= &nbsp;&nbsp;liftIO&nbsp;(readReservations&nbsp;connStr&nbsp;t)&nbsp;&gt;&gt;=&nbsp;next runInSQLServer&nbsp;connStr&nbsp;(CreateReservation&nbsp;r&nbsp;next)&nbsp;= &nbsp;&nbsp;liftIO&nbsp;(insertReservation&nbsp;connStr&nbsp;r)&nbsp;&gt;&gt;&nbsp;next</pre> </p> <p> Since <code>ReservationsInstruction</code> is a sum type with three cases, the <code>runInSQLServer</code> action has to handle all three. Each case calls a dedicated helper function. I'll only show one of these to give you a sense for how they look. </p> <p> <pre><span style="color:#2b91af;">readReservations</span>&nbsp;::&nbsp;<span style="color:blue;">Text</span>&nbsp;<span style="color:blue;">-&gt;</span>&nbsp;<span style="color:blue;">LocalTime</span>&nbsp;<span style="color:blue;">-&gt;</span>&nbsp;<span style="color:#2b91af;">IO</span>&nbsp;[<span style="color:blue;">Reservation</span>] readReservations&nbsp;connStr&nbsp;(LocalTime&nbsp;d&nbsp;_)&nbsp;= &nbsp;&nbsp;<span style="color:blue;">let</span>&nbsp;sql&nbsp;= &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:#a31515;">&quot;SELECT&nbsp;[Guid],&nbsp;[Date],&nbsp;[Name],&nbsp;[Email],&nbsp;[Quantity]\ &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;\FROM&nbsp;[dbo].[Reservations]\ &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;\WHERE&nbsp;CONVERT(DATE,&nbsp;[Date])&nbsp;=&nbsp;&quot;</span>&nbsp;&lt;&gt;&nbsp;toSql&nbsp;d &nbsp;&nbsp;<span style="color:blue;">in</span>&nbsp;withConnection&nbsp;connStr&nbsp;$&nbsp;\conn&nbsp;-&gt;&nbsp;<span style="color:blue;">fmap</span>&nbsp;unDbReservation&nbsp;&lt;$&gt;&nbsp;query&nbsp;conn&nbsp;sql</pre> </p> <p> You can see all the details about <code>withConnection</code>, <code>unDbReservation</code>, etcetera in the Git repository. The principal point is that these are just normal <code>IO</code> actions. </p> <h3 id="7dd30abf99b24ec6b13a1c22d0f6f150"> Basic composition <a href="#7dd30abf99b24ec6b13a1c22d0f6f150" title="permalink">#</a> </h3> <p> The two interpreters are all we need to compose a working system: </p> <p> <pre><span style="color:#2b91af;">runInSQLServerAndOnSystemClock</span>&nbsp;::&nbsp;<span style="color:blue;">MonadIO</span>&nbsp;m&nbsp;<span style="color:blue;">=&gt;</span>&nbsp;<span style="color:blue;">Text</span>&nbsp;<span style="color:blue;">-&gt;</span>&nbsp;<span style="color:blue;">ReservationsProgramT</span>&nbsp;m&nbsp;a&nbsp;<span style="color:blue;">-&gt;</span>&nbsp;m&nbsp;a runInSQLServerAndOnSystemClock&nbsp;connStr&nbsp;=&nbsp;iterT&nbsp;go &nbsp;&nbsp;<span style="color:blue;">where</span>&nbsp;go&nbsp;(InL&nbsp;rins)&nbsp;=&nbsp;DB.runInSQLServer&nbsp;connStr&nbsp;rins &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;go&nbsp;(InR&nbsp;cins)&nbsp;=&nbsp;runOnSystemClock&nbsp;cins</pre> </p> <p> The <code>iterT</code> function enables you to interpret a <code>FreeT</code> value, of which <code>ReservationsProgramT</code> is an alias. The <code>go</code> function just pattern-matches on the two cases of the <code>Sum</code> functor, and delegates to the corresponding interpreter. </p> <p> This composition enables the system to run and do the intended work. You can start the server and make <code>GET</code> and <code>POST</code> requests against the <code>/reservations</code> resource, as outlined in the first article in this small series. </p> <p> This verifies what I already hypothesized. This feature set requires two distinct sets of impure interactions: <ul> <li>Getting the current time</li> <li>Querying and writing to a database</li> </ul> Once you've worked with Haskell for some time, you'll get good at predicting which actions are impure, and which functionality can be kept pure. The current result isn't surprising. </p> <p> It does make it clear what ought to be logged. All the pure functionality can be reproduced if you have the inputs. You only need to log the impure interactions, and now you know what they are. </p> <h3 id="f29d957fcfe644e9a9efaf70bf58ad74"> Compose with logging <a href="#f29d957fcfe644e9a9efaf70bf58ad74" title="permalink">#</a> </h3> <p> You need to log the impure operations, and you know that they're interacting with the system clock and the database. As usual, starting with the system clock is most accessible. You can write what's essentially a <a href="https://en.wikipedia.org/wiki/Decorator_pattern">Decorator</a> of any <code>ClockInstruction</code> interpreter: </p> <p> <pre><span style="color:#2b91af;">logClock</span>&nbsp;::&nbsp;<span style="color:blue;">MonadIO</span>&nbsp;m &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">=&gt;</span>&nbsp;(<span style="color:#2b91af;">String</span>&nbsp;<span style="color:blue;">-&gt;</span>&nbsp;<span style="color:#2b91af;">IO</span>&nbsp;()) &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">-&gt;</span>&nbsp;(forall&nbsp;x.&nbsp;<span style="color:blue;">ClockInstruction</span>&nbsp;(m&nbsp;x)&nbsp;<span style="color:blue;">-&gt;</span>&nbsp;m&nbsp;x) &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">-&gt;</span>&nbsp;<span style="color:blue;">ClockInstruction</span>&nbsp;(m&nbsp;a)&nbsp;<span style="color:blue;">-&gt;</span>&nbsp;m&nbsp;a logClock&nbsp;logLn&nbsp;inner&nbsp;(CurrentTime&nbsp;next)&nbsp;=&nbsp;<span style="color:blue;">do</span> &nbsp;&nbsp;output&nbsp;&lt;-&nbsp;inner&nbsp;$&nbsp;CurrentTime&nbsp;<span style="color:blue;">return</span> &nbsp;&nbsp;liftIO&nbsp;$&nbsp;writeLogEntry&nbsp;logLn&nbsp;<span style="color:#a31515;">&quot;CurrentTime&quot;</span>&nbsp;<span style="color:blue;">()</span>&nbsp;output &nbsp;&nbsp;next&nbsp;output</pre> </p> <p> The <code>logClock</code> action decorates any <code>inner</code> interpreter with the logging action <code>logLn</code>. It returns an action of the same type as it decorates. </p> <p> It relies on a helper function called <code>writeLogEntry</code>, which handles some of the formalities of formatting and time-stamping each log entry. </p> <p> You can decorate any database interpreter in the same way: </p> <p> <pre><span style="color:#2b91af;">logReservations</span>&nbsp;::&nbsp;<span style="color:blue;">MonadIO</span>&nbsp;m &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">=&gt;</span>&nbsp;(<span style="color:#2b91af;">String</span>&nbsp;<span style="color:blue;">-&gt;</span>&nbsp;<span style="color:#2b91af;">IO</span>&nbsp;()) &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">-&gt;</span>&nbsp;(forall&nbsp;x.&nbsp;<span style="color:blue;">ReservationsInstruction</span>&nbsp;(m&nbsp;x)&nbsp;<span style="color:blue;">-&gt;</span>&nbsp;m&nbsp;x) &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">-&gt;</span>&nbsp;<span style="color:blue;">ReservationsInstruction</span>&nbsp;(m&nbsp;a)&nbsp;<span style="color:blue;">-&gt;</span>&nbsp;m&nbsp;a logReservations&nbsp;logLn&nbsp;inner&nbsp;(ReadReservation&nbsp;rid&nbsp;next)&nbsp;=&nbsp;<span style="color:blue;">do</span> &nbsp;&nbsp;output&nbsp;&lt;-&nbsp;inner&nbsp;$&nbsp;ReadReservation&nbsp;rid&nbsp;<span style="color:blue;">return</span> &nbsp;&nbsp;liftIO&nbsp;$&nbsp;writeLogEntry&nbsp;logLn&nbsp;<span style="color:#a31515;">&quot;ReadReservation&quot;</span>&nbsp;rid&nbsp;output &nbsp;&nbsp;next&nbsp;output logReservations&nbsp;logLn&nbsp;inner&nbsp;(ReadReservations&nbsp;t&nbsp;next)&nbsp;=&nbsp;<span style="color:blue;">do</span> &nbsp;&nbsp;output&nbsp;&lt;-&nbsp;inner&nbsp;$&nbsp;ReadReservations&nbsp;t&nbsp;<span style="color:blue;">return</span> &nbsp;&nbsp;liftIO&nbsp;$&nbsp;writeLogEntry&nbsp;logLn&nbsp;<span style="color:#a31515;">&quot;ReadReservations&quot;</span>&nbsp;t&nbsp;output &nbsp;&nbsp;next&nbsp;output logReservations&nbsp;logLn&nbsp;inner&nbsp;(CreateReservation&nbsp;r&nbsp;next)&nbsp;=&nbsp;<span style="color:blue;">do</span> &nbsp;&nbsp;output&nbsp;&lt;-&nbsp;inner&nbsp;$&nbsp;CreateReservation&nbsp;r&nbsp;(<span style="color:blue;">return</span>&nbsp;<span style="color:blue;">()</span>) &nbsp;&nbsp;liftIO&nbsp;$&nbsp;writeLogEntry&nbsp;logLn&nbsp;<span style="color:#a31515;">&quot;CreateReservation&quot;</span>&nbsp;r&nbsp;output &nbsp;&nbsp;next</pre> </p> <p> The <code>logReservations</code> action follows the same template as <code>logClock</code>; only it has more lines of code because <code>ReservationsInstruction</code> is a discriminated union with three cases. </p> <p> With these Decorator actions you can change the application composition so that it logs all impure inputs and outputs: </p> <p> <pre><span style="color:#2b91af;">runInSQLServerAndOnSystemClock</span>&nbsp;::&nbsp;<span style="color:blue;">MonadIO</span>&nbsp;m &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">=&gt;</span>&nbsp;(<span style="color:#2b91af;">String</span>&nbsp;<span style="color:blue;">-&gt;</span>&nbsp;<span style="color:#2b91af;">IO</span>&nbsp;()) &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">-&gt;</span>&nbsp;<span style="color:blue;">Text</span> &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">-&gt;</span>&nbsp;<span style="color:blue;">ReservationsProgramT</span>&nbsp;m&nbsp;a&nbsp;<span style="color:blue;">-&gt;</span>&nbsp;m&nbsp;a runInSQLServerAndOnSystemClock&nbsp;logLn&nbsp;connStr&nbsp;=&nbsp;iterT&nbsp;go &nbsp;&nbsp;<span style="color:blue;">where</span>&nbsp;go&nbsp;(InL&nbsp;rins)&nbsp;=&nbsp;logReservations&nbsp;logLn&nbsp;(DB.runInSQLServer&nbsp;connStr)&nbsp;rins &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;go&nbsp;(InR&nbsp;cins)&nbsp;=&nbsp;logClock&nbsp;logLn&nbsp;runOnSystemClock&nbsp;cins</pre> </p> <p> This not only implements the desired functionality, but also <em>Goldilogs:</em> not too little, not too much, but just what you need. Notice that I didn't have to change any of my Domain Model or HTTP-specific code to enable logging. This cross-cutting concern is enabled entirely via composition. </p> <h3 id="3d37879949774c10a002ad7ff93ad571"> Repeatability <a href="#3d37879949774c10a002ad7ff93ad571" title="permalink">#</a> </h3> <p> An HTTP request like this: </p> <p> <pre>POST /reservations/ HTTP/1.1 Content-Type: application/json { &nbsp;&nbsp;<span style="color:#2e75b6;">&quot;id&quot;</span>:&nbsp;<span style="color:#a31515;">&quot;c3cbfbc7-6d64-4ead-84ef-7f89de5b7e1c&quot;</span>, &nbsp;&nbsp;<span style="color:#2e75b6;">&quot;date&quot;</span>:&nbsp;<span style="color:#a31515;">&quot;2020-03-20&nbsp;19:00:00&quot;</span>, &nbsp;&nbsp;<span style="color:#2e75b6;">&quot;name&quot;</span>:&nbsp;<span style="color:#a31515;">&quot;Elissa&nbsp;Megan&nbsp;Powers&quot;</span>, &nbsp;&nbsp;<span style="color:#2e75b6;">&quot;email&quot;</span>:&nbsp;<span style="color:#a31515;">&quot;emp@example.com&quot;</span>, &nbsp;&nbsp;<span style="color:#2e75b6;">&quot;quantity&quot;</span>:&nbsp;3 }</pre> </p> <p> produces a series of log entries like these: </p> <p> <pre>LogEntry {logTime = 2019-12-29 20:21:53.0029235 UTC, logOperation = "CurrentTime", logInput = "()", logOutput = "2019-12-29 21:21:53.0029235"} LogEntry {logTime = 2019-12-29 20:21:54.0532677 UTC, logOperation = "ReadReservations", logInput = "2020-03-20 19:00:00", logOutput = "[]"} LogEntry {logTime = 2019-12-29 20:21:54.0809254 UTC, logOperation = "CreateReservation", logInput = "Reservation {reservationId = c3cbfbc7-6d64-4ead-84ef-7f89de5b7e1c, reservationDate = 2020-03-20 19:00:00, reservationName = \"Elissa Megan Powers\", reservationEmail = \"emp@example.com\", reservationQuantity = 3}", logOutput = "()"} LogEntry {logTime = 2019-12-29 20:21:54 UTC, logOperation = "PostReservation", logInput = "\"{ \\\"id\\\": \\\"c3cbfbc7-6d64-4ead-84ef-7f89de5b7e1c\\\", \\\"date\\\": \\\"2020-03-20 19:00:00\\\", \\\"name\\\": \\\"Elissa Megan Powers\\\", \\\"email\\\": \\\"emp@example.com\\\", \\\"quantity\\\": 3 }\"", logOutput = "()"}</pre> </p> <p> This is only a prototype to demonstrate what's possible. In an attempt to make things simple for myself, I decided to just log data by using the <code>Show</code> instance of each value being logged. In order to reproduce behaviour, I'll rely on the corresponding <code>Read</code> instance for the type. This was probably naive, and not a decision I would employ in a production system, but it's good enough for a prototype. </p> <p> For example, the above log entry states that the <code>CurrentTime</code> instruction was evaluated and that the output was <code>2019-12-29 21:21:53.0029235</code>. Second, the <code>ReadReservations</code> instruction was evaluated with the input <code>2020-03-20 19:00:00</code> and the output was the empty list (<code>[]</code>). The third line records that the <code>CreateReservation</code> instruction was evaluated with a particular input, and that the output was <code>()</code>. </p> <p> The fourth and final record is the the actual values observed at the HTTP boundary. </p> <p> You can load and parse the logged data into a unit test or an interactive session: </p> <p> <pre>λ&gt; l &lt;- lines &lt;$&gt; readFile "the/path/to/the/log.txt" λ&gt; replayData = readReplayData l λ&gt; replayData ReplayData { &nbsp;&nbsp;observationsOfPostReservation = &nbsp;&nbsp;&nbsp;&nbsp;[Reservation { &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;reservationId = c3cbfbc7-6d64-4ead-84ef-7f89de5b7e1c, &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;reservationDate = 2020-03-20 19:00:00, &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;reservationName = "Elissa Megan Powers", &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;reservationEmail = "emp@example.com", &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;reservationQuantity = 3}], &nbsp;&nbsp;observationsOfRead = fromList [], &nbsp;&nbsp;observationsOfReads = fromList [(2020-03-20 19:00:00,[[]])], &nbsp;&nbsp;observationsOfCurrentTime = [2019-12-29 21:21:53.0029235]} λ&gt; r = head $ observationsOfPostReservation replayData λ&gt; r Reservation { &nbsp;&nbsp;reservationId = c3cbfbc7-6d64-4ead-84ef-7f89de5b7e1c, &nbsp;&nbsp;reservationDate = 2020-03-20 19:00:00, &nbsp;&nbsp;reservationName = "Elissa Megan Powers", &nbsp;&nbsp;reservationEmail = "emp@example.com", &nbsp;&nbsp;reservationQuantity = 3}</pre> </p> <p> (I've added line breaks and indentation to some of the output to make it more readable, compared to what GHCi produces.) </p> <p> The most important thing to notice is the <code>readReplayData</code> function that parses the log file into Haskell data. I've also written a prototype of a function that can <code>replay</code> the actions as they happened: </p> <p> <pre>λ&gt; (seatingDuration, tables) &lt;- readConfig λ&gt; replay replayData $ tryAccept seatingDuration tables r Right ()</pre> </p> <p> The original HTTP request returned <code>200 OK</code> and that's exactly how <code>reservationServer</code> translates a <code>Right ()</code> result. So the above interaction is a faithful reproduction of what actually happened. </p> <h3 id="5d94afef4145456abe86ae6f2dd9445a"> Replay <a href="#5d94afef4145456abe86ae6f2dd9445a" title="permalink">#</a> </h3> <p> You may have noticed that I used a <code>replay</code> function above. This is only a prototype to get the point across. It's just another interpreter of <code>ReservationsProgram</code> (or, rather an <code>ExceptT</code> wrapper of <code>ReservationsProgram</code>): </p> <p> <pre><span style="color:#2b91af;">replay</span>&nbsp;::&nbsp;<span style="color:blue;">ReplayData</span>&nbsp;<span style="color:blue;">-&gt;</span>&nbsp;<span style="color:blue;">ExceptT</span>&nbsp;e&nbsp;<span style="color:blue;">ReservationsProgram</span>&nbsp;a&nbsp;<span style="color:blue;">-&gt;</span>&nbsp;<span style="color:#2b91af;">Either</span>&nbsp;e&nbsp;a replay&nbsp;d&nbsp;=&nbsp;replayImp&nbsp;d&nbsp;.&nbsp;runExceptT &nbsp;&nbsp;<span style="color:blue;">where</span> &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:#2b91af;">replayImp</span>&nbsp;::&nbsp;<span style="color:blue;">ReplayData</span>&nbsp;<span style="color:blue;">-&gt;</span>&nbsp;<span style="color:blue;">ReservationsProgram</span>&nbsp;a&nbsp;<span style="color:blue;">-&gt;</span>&nbsp;a &nbsp;&nbsp;&nbsp;&nbsp;replayImp&nbsp;rd&nbsp;p&nbsp;=&nbsp;State.evalState&nbsp;(iterM&nbsp;go&nbsp;p)&nbsp;rd &nbsp;&nbsp;&nbsp;&nbsp;go&nbsp;(InL&nbsp;(ReadReservation&nbsp;rid&nbsp;next))&nbsp;=&nbsp;replayReadReservation&nbsp;rid&nbsp;&gt;&gt;=&nbsp;next &nbsp;&nbsp;&nbsp;&nbsp;go&nbsp;(InL&nbsp;(ReadReservations&nbsp;t&nbsp;next))&nbsp;=&nbsp;replayReadReservations&nbsp;t&nbsp;&gt;&gt;=&nbsp;next &nbsp;&nbsp;&nbsp;&nbsp;go&nbsp;(InL&nbsp;(CreateReservation&nbsp;_&nbsp;next))&nbsp;=&nbsp;next &nbsp;&nbsp;&nbsp;&nbsp;go&nbsp;(InR&nbsp;(CurrentTime&nbsp;next))&nbsp;=&nbsp;replayCurrentTime&nbsp;&gt;&gt;=&nbsp;next</pre> </p> <p> While this is compact Haskell code that <em>I</em> wrote, I still found it so abstruse that I decided to add a type annotation to a local function. It's not required, but I find that it helps me understand what <code>replayImp</code> does. It uses <code>iterM</code> (a cousin to <code>iterT</code>) to interpret the <code>ReservationsProgram</code>. The entire interpretation is stateful, so runs in the <code>State</code> monad. Here's an example: </p> <p> <pre><span style="color:#2b91af;">replayCurrentTime</span>&nbsp;::&nbsp;<span style="color:blue;">State</span>&nbsp;<span style="color:blue;">ReplayData</span>&nbsp;<span style="color:blue;">LocalTime</span> replayCurrentTime&nbsp;=&nbsp;<span style="color:blue;">do</span> &nbsp;&nbsp;xs&nbsp;&lt;-&nbsp;State.gets&nbsp;observationsOfCurrentTime &nbsp;&nbsp;<span style="color:blue;">let</span>&nbsp;(observation:rest)&nbsp;=&nbsp;xs &nbsp;&nbsp;State.modify&nbsp;(\s&nbsp;-&gt;&nbsp;s&nbsp;{&nbsp;observationsOfCurrentTime&nbsp;=&nbsp;rest&nbsp;}) &nbsp;&nbsp;<span style="color:blue;">return</span>&nbsp;observation</pre> </p> <p> The <code>replayCurrentTime</code> function replays log observations of <code>CurrentTime</code> instructions. The <code>observationsOfCurrentTime</code> field is a list of observed values, parsed from a log. A <code>ReservationsProgram</code> might query the <code>CurrentTime</code> multiple times, so there could conceivably be several such observations. The idea is to replay them, starting with the earliest. </p> <p> Each time the function replays an observation, it should remove it from the log. It does that by first retrieving all observations from the state. It then pattern-matches the <code>observation</code> from the <code>rest</code> of the observations. I execute my code with the <code>-Wall</code> option, so I'm puzzled that I don't get a warning from the compiler about that line. After all, the <code>xs</code> list could be empty. This is, however, prototype code, so I decided to ignore that issue. </p> <p> Before the function returns the <code>observation</code> it updates the replay data by effectively removing the <code>observation</code>, but without touching anything else. </p> <p> The <code>replayReadReservation</code> and <code>replayReadReservations</code> functions follow the same template. You can consult the source code repository if you're curious about the details. You may also notice that the <code>go</code> function doesn't do anything when it encounters a <code>CreateReservation</code> instruction. This is because that instruction has no return value, so there's no reason to consult a log to figure out what to return. </p> <h3 id="fa5477f706a143d59c0006e52af2fe2d"> Summary <a href="#fa5477f706a143d59c0006e52af2fe2d" title="permalink">#</a> </h3> <p> The point of this article was to flesh out a fully functional feature (a vertical slice, if you're so inclined) in Haskell, in order to verify that the only impure actions involved are: <ul> <li>Getting the current time</li> <li>Interacting with the application database</li> </ul> This turns out to be the case. </p> <p> Furthermore, prototype code demonstrates that based on a log of impure interactions, you can repeat the logged execution. </p> <p> Now that we know what is impure and what can be pure, we can reproduce the same architecture in C# (or another mainstream programming language). </p> <p> <strong>Next:</strong> Repeatable execution in C#. </p> </div><hr> This blog is totally free, but if you like it, please consider <a href="https://blog.ploeh.dk/support">supporting it</a>. Mark Seemann https://blog.ploeh.dk/2020/03/30/repeatable-execution-in-haskell Repeatable execution https://blog.ploeh.dk/2020/03/23/repeatable-execution/ Mon, 23 Mar 2020 08:17:00 UTC <div id="post"> <p> <em>What to log, and how to log it.</em> </p> <p> When I visit software organisations to help them make their code more maintainable, I often see code like this: </p> <p> <pre><span style="color:blue;">public</span>&nbsp;<span style="color:#2b91af;">ILog</span>&nbsp;Log&nbsp;{&nbsp;<span style="color:blue;">get</span>;&nbsp;} <span style="color:blue;">public</span>&nbsp;<span style="color:#2b91af;">ActionResult</span>&nbsp;<span style="font-weight:bold;color:#74531f;">Post</span>(<span style="color:#2b91af;">ReservationDto</span>&nbsp;<span style="font-weight:bold;color:#1f377f;">dto</span>) { &nbsp;&nbsp;&nbsp;&nbsp;Log.<span style="font-weight:bold;color:#74531f;">Debug</span>(<span style="color:#a31515;">$&quot;Entering&nbsp;</span>{<span style="color:blue;">nameof</span>(<span style="font-weight:bold;color:#74531f;">Post</span>)}<span style="color:#a31515;">&nbsp;method...&quot;</span>); &nbsp;&nbsp;&nbsp;&nbsp;<span style="font-weight:bold;color:#8f08c4;">if</span>&nbsp;(!<span style="color:#2b91af;">DateTime</span>.<span style="color:#74531f;">TryParse</span>(<span style="font-weight:bold;color:#1f377f;">dto</span>.Date,&nbsp;<span style="color:blue;">out</span>&nbsp;<span style="color:blue;">var</span>&nbsp;<span style="color:blue;">_</span>)) &nbsp;&nbsp;&nbsp;&nbsp;{ &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;Log.<span style="font-weight:bold;color:#74531f;">Warning</span>(<span style="color:#a31515;">&quot;Invalid&nbsp;reservation&nbsp;date.&quot;</span>); &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="font-weight:bold;color:#8f08c4;">return</span>&nbsp;<span style="font-weight:bold;color:#74531f;">BadRequest</span>(<span style="color:#a31515;">$&quot;Invalid&nbsp;date:&nbsp;</span>{<span style="font-weight:bold;color:#1f377f;">dto</span>.Date}<span style="color:#a31515;">.&quot;</span>); &nbsp;&nbsp;&nbsp;&nbsp;} &nbsp;&nbsp;&nbsp;&nbsp;Log.<span style="font-weight:bold;color:#74531f;">Debug</span>(<span style="color:#a31515;">&quot;Mapping&nbsp;DTO&nbsp;to&nbsp;Domain&nbsp;Model.&quot;</span>); &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:#2b91af;">Reservation</span>&nbsp;<span style="font-weight:bold;color:#1f377f;">reservation</span>&nbsp;=&nbsp;<span style="color:#2b91af;">Mapper</span>.<span style="color:#74531f;">Map</span>(<span style="font-weight:bold;color:#1f377f;">dto</span>); &nbsp;&nbsp;&nbsp;&nbsp;<span style="font-weight:bold;color:#8f08c4;">if</span>&nbsp;(<span style="font-weight:bold;color:#1f377f;">reservation</span>.Date&nbsp;<span style="font-weight:bold;color:#74531f;">&lt;</span>&nbsp;<span style="color:#2b91af;">DateTime</span>.Now) &nbsp;&nbsp;&nbsp;&nbsp;{ &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;Log.<span style="font-weight:bold;color:#74531f;">Warning</span>(<span style="color:#a31515;">&quot;Invalid&nbsp;reservation&nbsp;date.&quot;</span>); &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="font-weight:bold;color:#8f08c4;">return</span>&nbsp;<span style="font-weight:bold;color:#74531f;">BadRequest</span>(<span style="color:#a31515;">$&quot;Invalid&nbsp;date:&nbsp;</span>{<span style="font-weight:bold;color:#1f377f;">reservation</span>.Date}<span style="color:#a31515;">.&quot;</span>); &nbsp;&nbsp;&nbsp;&nbsp;} &nbsp;&nbsp;&nbsp;&nbsp;Log.<span style="font-weight:bold;color:#74531f;">Debug</span>(<span style="color:#a31515;">&quot;Reading&nbsp;existing&nbsp;reservations&nbsp;from&nbsp;database.&quot;</span>); &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">var</span>&nbsp;<span style="font-weight:bold;color:#1f377f;">reservations</span>&nbsp;=&nbsp;Repository.<span style="font-weight:bold;color:#74531f;">ReadReservations</span>(<span style="font-weight:bold;color:#1f377f;">reservation</span>.Date); &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">bool</span>&nbsp;<span style="font-weight:bold;color:#1f377f;">accepted</span>&nbsp;=&nbsp;maîtreD.<span style="font-weight:bold;color:#74531f;">CanAccept</span>(<span style="font-weight:bold;color:#1f377f;">reservations</span>,&nbsp;<span style="font-weight:bold;color:#1f377f;">reservation</span>); &nbsp;&nbsp;&nbsp;&nbsp;<span style="font-weight:bold;color:#8f08c4;">if</span>&nbsp;(!<span style="font-weight:bold;color:#1f377f;">accepted</span>) &nbsp;&nbsp;&nbsp;&nbsp;{ &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;Log.<span style="font-weight:bold;color:#74531f;">Warning</span>(<span style="color:#a31515;">&quot;Not&nbsp;enough&nbsp;capacity&quot;</span>); &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="font-weight:bold;color:#8f08c4;">return</span>&nbsp;<span style="font-weight:bold;color:#74531f;">StatusCode</span>( &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:#2b91af;">StatusCodes</span>.Status500InternalServerError, &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:#a31515;">&quot;Couldn&#39;t&nbsp;accept.&quot;</span>); &nbsp;&nbsp;&nbsp;&nbsp;} &nbsp;&nbsp;&nbsp;&nbsp;Log.<span style="font-weight:bold;color:#74531f;">Info</span>(<span style="color:#a31515;">&quot;Adding&nbsp;reservation&nbsp;to&nbsp;database.&quot;</span>); &nbsp;&nbsp;&nbsp;&nbsp;Repository.<span style="font-weight:bold;color:#74531f;">Create</span>(<span style="font-weight:bold;color:#1f377f;">reservation</span>); &nbsp;&nbsp;&nbsp;&nbsp;Log.<span style="font-weight:bold;color:#74531f;">Debug</span>(<span style="color:#a31515;">$&quot;Leaving&nbsp;</span>{<span style="color:blue;">nameof</span>(<span style="font-weight:bold;color:#74531f;">Post</span>)}<span style="color:#a31515;">&nbsp;method...&quot;</span>); &nbsp;&nbsp;&nbsp;&nbsp;<span style="font-weight:bold;color:#8f08c4;">return</span>&nbsp;<span style="font-weight:bold;color:#74531f;">Ok</span>(); }</pre> </p> <p> Logging like this annoys me. It adds avoidable noise to the code, making it harder to read, and thus, more difficult to maintain. </p> <h3 id="75930691088c44568c80941c70bc147a"> Ideal <a href="#75930691088c44568c80941c70bc147a" title="permalink">#</a> </h3> <p> The above code ought to look like this: </p> <p> <pre><span style="color:blue;">public</span>&nbsp;<span style="color:#2b91af;">ActionResult</span>&nbsp;<span style="font-weight:bold;color:#74531f;">Post</span>(<span style="color:#2b91af;">ReservationDto</span>&nbsp;<span style="font-weight:bold;color:#1f377f;">dto</span>) { &nbsp;&nbsp;&nbsp;&nbsp;<span style="font-weight:bold;color:#8f08c4;">if</span>&nbsp;(!<span style="color:#2b91af;">DateTime</span>.<span style="color:#74531f;">TryParse</span>(<span style="font-weight:bold;color:#1f377f;">dto</span>.Date,&nbsp;<span style="color:blue;">out</span>&nbsp;<span style="color:blue;">var</span>&nbsp;<span style="color:blue;">_</span>)) &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="font-weight:bold;color:#8f08c4;">return</span>&nbsp;<span style="font-weight:bold;color:#74531f;">BadRequest</span>(<span style="color:#a31515;">$&quot;Invalid&nbsp;date:&nbsp;</span>{<span style="font-weight:bold;color:#1f377f;">dto</span>.Date}<span style="color:#a31515;">.&quot;</span>); &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:#2b91af;">Reservation</span>&nbsp;<span style="font-weight:bold;color:#1f377f;">reservation</span>&nbsp;=&nbsp;<span style="color:#2b91af;">Mapper</span>.<span style="color:#74531f;">Map</span>(<span style="font-weight:bold;color:#1f377f;">dto</span>); &nbsp;&nbsp;&nbsp;&nbsp;<span style="font-weight:bold;color:#8f08c4;">if</span>&nbsp;(<span style="font-weight:bold;color:#1f377f;">reservation</span>.Date&nbsp;<span style="font-weight:bold;color:#74531f;">&lt;</span>&nbsp;Clock.<span style="font-weight:bold;color:#74531f;">GetCurrentDateTime</span>()) &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="font-weight:bold;color:#8f08c4;">return</span>&nbsp;<span style="font-weight:bold;color:#74531f;">BadRequest</span>(<span style="color:#a31515;">$&quot;Invalid&nbsp;date:&nbsp;</span>{<span style="font-weight:bold;color:#1f377f;">reservation</span>.Date}<span style="color:#a31515;">.&quot;</span>); &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">var</span>&nbsp;<span style="font-weight:bold;color:#1f377f;">reservations</span>&nbsp;=&nbsp;Repository.<span style="font-weight:bold;color:#74531f;">ReadReservations</span>(<span style="font-weight:bold;color:#1f377f;">reservation</span>.Date); &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">bool</span>&nbsp;<span style="font-weight:bold;color:#1f377f;">accepted</span>&nbsp;=&nbsp;maîtreD.<span style="font-weight:bold;color:#74531f;">CanAccept</span>(<span style="font-weight:bold;color:#1f377f;">reservations</span>,&nbsp;<span style="font-weight:bold;color:#1f377f;">reservation</span>); &nbsp;&nbsp;&nbsp;&nbsp;<span style="font-weight:bold;color:#8f08c4;">if</span>&nbsp;(!<span style="font-weight:bold;color:#1f377f;">accepted</span>) &nbsp;&nbsp;&nbsp;&nbsp;{ &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="font-weight:bold;color:#8f08c4;">return</span>&nbsp;<span style="font-weight:bold;color:#74531f;">StatusCode</span>( &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:#2b91af;">StatusCodes</span>.Status500InternalServerError, &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:#a31515;">&quot;Couldn&#39;t&nbsp;accept.&quot;</span>); &nbsp;&nbsp;&nbsp;&nbsp;} &nbsp;&nbsp;&nbsp;&nbsp;Repository.<span style="font-weight:bold;color:#74531f;">Create</span>(<span style="font-weight:bold;color:#1f377f;">reservation</span>); &nbsp;&nbsp;&nbsp;&nbsp;<span style="font-weight:bold;color:#8f08c4;">return</span>&nbsp;<span style="font-weight:bold;color:#74531f;">Ok</span>(); }</pre> </p> <p> This is more readable. The logging statements are gone from the code, thereby amplifying the essential behaviour of the <code>Post</code> method. The noise is gone. </p> <p> <em>Wait a minute!</em> you might say, <em>You can't just remove logging! Logging is important.</em> </p> <p> Yes, I agree, and I didn't. This code still logs. It logs just what you need to log. No more, no less. </p> <h3 id="c176715622a74d69a312cfa8e47159fb"> Types of logging <a href="#c176715622a74d69a312cfa8e47159fb" title="permalink">#</a> </h3> <p> Before we talk about the technical details, I think it's important to establish some vocabulary and context. In this article, I use the term <em>logging</em> broadly to describe any sort of action of recording what happened while software executed. There's more than one reason an application might have to do that: <ul> <li> <strong>Instrumentation.</strong> You may log to support your own work. The first code listing in this article is a typical example of this style of logging. If you've ever had the responsibility of having to support an application that runs in production, you know that you need insight into what happens. When people report strange behaviours, you need those logs to support troubleshooting. </li> <li> <strong>Telemetry.</strong> You may log to support other people's work. You can write status updates, warnings, and errors to support operations. You can record Key Performance Indicators (KPIs) to support 'the business'. </li> <li> <strong>Auditing.</strong> You may log because you're legally obliged to do so. </li> <li> <strong>Metering.</strong> You may log who does what so that you can bill users based on consumption. </li> </ul> Regardless of motivation, I still consider these to be types of logging. All are <em>cross-cutting concerns</em> in that they're independent of application features. Logging records what happened, when it happened, who or what triggered the event, and so on. The difference between instrumentation, telemetry, auditing, and metering is only <em>what</em> you choose to persist. </p> <p> Particularly when it comes to instrumentation, I often see examples of 'overlogging'. When logging is done to support future troubleshooting, you can't predict what you're going to need, so it's better to log too much data than too little. </p> <p> It'd be even better to log <em>only</em> what you need. Not too little, not too much, but just the right amount of logging. Obviously, we should call this <em>Goldilogs</em>. </p> <h3 id="ea53735b49ef4ad7849ebceeabc616ac"> Repeatability <a href="#ea53735b49ef4ad7849ebceeabc616ac" title="permalink">#</a> </h3> <p> How do you know what to log? How do you know that you've logged everything that you'll need, when you don't know your future needs? </p> <p> The key is repeatability. Just like you should be able to <a href="https://en.wikipedia.org/wiki/Reproducible_builds">reproduce builds</a> and <a href="https://en.wikipedia.org/wiki/Continuous_delivery">repeat deployments</a>, you should also be able to reproduce <em>execution</em>. </p> <p> If you can replay what happened when a problem manifested itself, you can troubleshoot it. You need to log just enough data to enable you to repeat execution. How do you identify that data? </p> <p> Consider a line of code like this: </p> <p> <pre><span style="color:blue;">int</span>&nbsp;<span style="font-weight:bold;color:#1f377f;">z</span>&nbsp;=&nbsp;<span style="font-weight:bold;color:#1f377f;">x</span>&nbsp;+&nbsp;<span style="font-weight:bold;color:#1f377f;">y</span>;</pre> </p> <p> Would you log that? </p> <p> It might make sense to log what <code>x</code> and <code>y</code> are, particularly if these values are run-time values (e.g. entered by a user, the result of a web service call, etc.): </p> <p> <pre>Log.<span style="font-weight:bold;color:#74531f;">Debug</span>(<span style="color:#a31515;">$&quot;Adding </span>{<span style="font-weight:bold;color:#1f377f;">x</span>}<span style="color:#a31515;"> and </span>{<span style="font-weight:bold;color:#1f377f;">y</span>}<span style="color:#a31515;">.&quot;</span>); <span style="color:blue;">int</span>&nbsp;<span style="font-weight:bold;color:#1f377f;">z</span>&nbsp;=&nbsp;<span style="font-weight:bold;color:#1f377f;">x</span>&nbsp;+&nbsp;<span style="font-weight:bold;color:#1f377f;">y</span>;</pre> </p> <p> Would you ever log the result, though? </p> <p> <pre>Log.<span style="font-weight:bold;color:#74531f;">Debug</span>(<span style="color:#a31515;">$&quot;Adding </span>{<span style="font-weight:bold;color:#1f377f;">x</span>}<span style="color:#a31515;"> and </span>{<span style="font-weight:bold;color:#1f377f;">y</span>}<span style="color:#a31515;">.&quot;</span>); <span style="color:blue;">int</span>&nbsp;<span style="font-weight:bold;color:#1f377f;">z</span>&nbsp;=&nbsp;<span style="font-weight:bold;color:#1f377f;">x</span>&nbsp;+&nbsp;<span style="font-weight:bold;color:#1f377f;">y</span>; Log.<span style="font-weight:bold;color:#74531f;">Debug</span>(<span style="color:#a31515;">$&quot;Result of addition: </span>{<span style="font-weight:bold;color:#1f377f;">z</span>}<span style="color:#a31515;">&quot;</span>);</pre> </p> <p> There's no reason to log the result of the calculation. Addition is a <a href="https://en.wikipedia.org/wiki/Pure_function">pure function</a>; it's <em>deterministic</em>. If you know the inputs, you can always repeat the calculation to get the output. Two plus two is always four. </p> <p> The more your code is composed from pure functions, the less you need to log. </p> <h3 id="a59305ce898b48879d5ca90db24f243a"> Log only impure actions <a href="#a59305ce898b48879d5ca90db24f243a" title="permalink">#</a> </h3> <p> In principle, all code bases interleave pure functions with impure actions. In most procedural or object-oriented code, no attempt is made of separating the two: </p> <p> <img src="/content/binary/impure-with-stripes-of-purity.png" alt="A box of mostly impure (red) code with vertical stripes of green symbolising pure code."> </p> <p> I've here illustrated impure actions with red and pure functions with green. Imagine that this is a conceptual block of code, with execution flowing from top to bottom. When you write normal procedural or object-oriented code, most of the code will have some sort of local side effect in the form of a state change, a more system-wide side effect, or be non-deterministic. Occasionally, arithmetic calculation or similar will form small pure islands. </p> <p> While you don't need to log the output of those pure functions, it hardly makes a difference, since most of the code is impure. It would be a busy log, in any case. </p> <p> Once you shift towards functional-first programming, your code may begin to look like this instead: </p> <p> <img src="/content/binary/functional-first-impure-pure-box.png" alt="A box of mostly pure (green) code with a few vertical stripes of red symbolising impure code."> </p> <p> You may still have some code that occasionally executes impure actions, but largely, most of the code is pure. If you know the inputs to all the pure code, you can reproduce that part of the code. This means that you only need to log the non-deterministic parts: the impure actions. Particularly, you need to log the outputs from the impure actions, because these impure output values become the inputs to the next pure block of code. </p> <p> This style of architecture is what you'll often get with a well-designed <a href="https://fsharp.org">F#</a> code base, but you can also replicate it in C# or another object-oriented programming language. I'd also draw a diagram like this to illustrate how <a href="https://www.haskell.org">Haskell</a> code works if you <a href="/2017/07/10/pure-interactions">model interactions with free monads</a>. </p> <p> This is the most generally applicable example, so articles in this short series show a Haskell code base with free monads, as well as a C# code base. </p> <p> In reality, you can often get away with an <a href="/2020/03/02/impureim-sandwich">impureim sandwich</a>: </p> <p> <img src="/content/binary/impure-pure-impure-sandwich-box.png" alt="A box with a thin red slice on top, a thick green middle, and a thin red slice at the bottom."> </p> <p> This architecture makes things simpler, including logging. You only need to log the inital and the concluding impure actions. The rest, you can always recompute. </p> <p> I <em>could</em> have implemented the comprehensive example code shown in the next articles as impureim sandwiches, but I chose to use free monads in the Haskell example, and Dependency Injection in the C# example. I did this in order to offer examples from which you can extrapolate a more complex architecture for your production code. </p> <h3 id="28bbf72ea37d47229312d9cf7bf14b9d"> Examples <a href="#28bbf72ea37d47229312d9cf7bf14b9d" title="permalink">#</a> </h3> <p> I've produced two equivalent example code bases to show how to log just enough data. The first is in Haskell because <a href="/2020/02/24/discerning-and-maintaining-purity">it's the best way to be sure that pure and impure code is properly separated</a>. </p> <p> Both example applications have the same externally visible behaviour. They showcase a focused vertical slice of a restaurant reservation system. The only feature they support is the creation of a reservation. </p> <p> Clients make reservations by making an HTTP POST request to the reservation system: </p> <p> <pre>POST /reservations HTTP/1.1 Content-Type: application/json { &nbsp;&nbsp;<span style="color:#2e75b6;">&quot;id&quot;</span>:&nbsp;<span style="color:#a31515;">&quot;84cef648-1e5f-467a-9d13-1b81db7f6df3&quot;</span>, &nbsp;&nbsp;<span style="color:#2e75b6;">&quot;date&quot;</span>:&nbsp;<span style="color:#a31515;">&quot;2021-12-21&nbsp;19:00:00&quot;</span>, &nbsp;&nbsp;<span style="color:#2e75b6;">&quot;email&quot;</span>:&nbsp;<span style="color:#a31515;">&quot;mark@example.com&quot;</span>, &nbsp;&nbsp;<span style="color:#2e75b6;">&quot;name&quot;</span>:&nbsp;<span style="color:#a31515;">&quot;Mark&nbsp;Seemann&quot;</span>, &nbsp;&nbsp;<span style="color:#2e75b6;">&quot;quantity&quot;</span>:&nbsp;4 }</pre> </p> <p> This is an attempt to make a reservation for four people at December 21, 2021 at seven in the evening. Both code bases support this HTTP API. </p> <p> If the web service accepts the reservation, it'll write the reservation as a record in a SQL Server database. The table is defined as: </p> <p> <pre><span style="color:blue;">CREATE</span>&nbsp;<span style="color:blue;">TABLE</span>&nbsp;[dbo]<span style="color:gray;">.</span>[Reservations]<span style="color:blue;">&nbsp;</span><span style="color:gray;">(</span> &nbsp;&nbsp;&nbsp;&nbsp;[Id]&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">INT</span>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:gray;">NOT</span>&nbsp;<span style="color:gray;">NULL</span>&nbsp;<span style="color:blue;">IDENTITY</span><span style="color:gray;">,</span> &nbsp;&nbsp;&nbsp;&nbsp;[Guid]&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">UNIQUEIDENTIFIER</span>&nbsp;&nbsp;&nbsp;<span style="color:gray;">NOT</span>&nbsp;<span style="color:gray;">NULL</span>&nbsp;<span style="color:blue;">UNIQUE</span><span style="color:gray;">,</span> &nbsp;&nbsp;&nbsp;&nbsp;[Date]&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">DATETIME2</span>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:gray;">NOT</span>&nbsp;<span style="color:gray;">NULL,</span> &nbsp;&nbsp;&nbsp;&nbsp;[Name]&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">NVARCHAR&nbsp;</span><span style="color:gray;">(</span>50<span style="color:gray;">)</span>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:gray;">NOT</span>&nbsp;<span style="color:gray;">NULL,</span> &nbsp;&nbsp;&nbsp;&nbsp;[Email]&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">NVARCHAR&nbsp;</span><span style="color:gray;">(</span>50<span style="color:gray;">)</span>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:gray;">NOT</span>&nbsp;<span style="color:gray;">NULL,</span> &nbsp;&nbsp;&nbsp;&nbsp;[Quantity]&nbsp;&nbsp;&nbsp;<span style="color:blue;">INT</span>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:gray;">NOT</span>&nbsp;<span style="color:gray;">NULL</span> &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">PRIMARY</span>&nbsp;<span style="color:blue;">KEY</span>&nbsp;<span style="color:blue;">CLUSTERED&nbsp;</span><span style="color:gray;">(</span>[Id]&nbsp;<span style="color:blue;">ASC</span><span style="color:gray;">)</span></pre> </p> <p> Both implementations of the service can run on the same database. </p> <p> The examples follow in separate articles: <ul> <li><a href="/2020/03/30/repeatable-execution-in-haskell">Repeatable execution in Haskell</a></li> <li>Repeatable execution in C#</li> </ul> Readers not comfortable with Haskell are welcome to skip directly to the C# article. </p> <h3 id="3068df1aa90b48bab281478d4bbf659c"> Log metadata <a href="#3068df1aa90b48bab281478d4bbf659c" title="permalink">#</a> </h3> <p> In this article series, I focus on run-time data. The point is that there's a formal method to identify what to log: <em>Log the inputs to and outputs from impure actions.</em> </p> <p> I don't focus on metadata, but apart from run-time data, each log entry should be accompanied by metadata. As a minimum, each entry should come with information about the time it was observed, but here's a list of metadata to consider: <ul> <li>Date and time of the log entry. Make sure to include the time zone, or alternatively, log exclusively in UTC.</li> <li>The version of the software that produced the entry. This is particularly important if you deploy new versions of the software several times a day.</li> <li>The user account or security context in which the application runs.</li> <li>The machine ID, if you consolidate server farm logs in one place.</li> <li>Correlation IDs, if present.</li> </ul> I don't claim that this list is complete, but I hope it can inspire you to add the metadata that you need. </p> <h3 id="f8469ec9c7e54089b05c6a84562c404d"> Conclusion <a href="#f8469ec9c7e54089b05c6a84562c404d" title="permalink">#</a> </h3> <p> You only need to log what happens in impure actions. In a normal imperative or object-oriented code base, this is almost a useless selection criterion, because most of what happens is impure. Thus, you need to log almost everything. </p> <p> There's many benefits to be had from moving towards a <a href="/2018/11/19/functional-architecture-a-definition">functional architecture</a>. One of them is that it simplifies logging. Even a functional-first approach, as is often seen in <a href="/2015/08/03/idiomatic-or-idiosyncratic">idiomatic</a> F# code bases, can simplify your logging efforts. The good news is that you can adopt a similar architecture in object-oriented code. You don't even have to compromise the design. </p> <p> I've worked on big C# code bases where we logged all the impure actions. It was typically less than a dozen impure actions per HTTP request. When there was a problem in production, I could usually reproduce what caused it based on the logs. </p> <p> You don't have to <em>overlog</em> to be able to troubleshoot your production code. Log the data that matters, and only that. Log the impure inputs and outputs. </p> <p> <strong>Next:</strong> <a href="/2020/03/30/repeatable-execution-in-haskell">Repeatable execution in Haskell</a>. </p> </div><hr> This blog is totally free, but if you like it, please consider <a href="https://blog.ploeh.dk/support">supporting it</a>. Mark Seemann https://blog.ploeh.dk/2020/03/23/repeatable-execution Conway's Law: latency versus throughput https://blog.ploeh.dk/2020/03/16/conways-law-latency-versus-throughput/ Mon, 16 Mar 2020 06:46:00 UTC <div id="post"> <p> <em>Organising work in one way optimises for low latency; in another for throughput.</em> </p> <p> It's a cliché that the software industry is desperate for talent. I also believe that it's a myth. As I've <a href="/2015/12/04/the-rules-of-attraction-location">previously observed</a>, the industry seems desperate for talent <em>within commute range</em>. The implication is that although we perform some of the most intangible and digitised work imaginable, we're expected to be physically present in an office. </p> <p> Since 2014 I've increasingly been working from home, and I love it. I also believe that it's an efficient way to develop software, but not only for the reasons usually given. </p> <p> I believe that distributed, asynchronous software development optimises throughput, but may sacrifice reaction time (i.e. increase latency). </p> <h3 id="dda9b0cd03e941c79365f6ff81969107"> The advantages of working in an office <a href="#dda9b0cd03e941c79365f6ff81969107" title="permalink">#</a> </h3> <p> It's easy to criticise office work, but if it's so unpopular, why is it still the mainstream? </p> <p> I think that there's a multitude of answers to that question. One is that this may be the only way that management can imagine. Since programming is so intangible, it's impossible to measure productivity. What a manager <em>can</em> do, though, is to watch who arrives early, who's the last to leave, and who seems to be always in front of his or her computer, or in a meeting, and so on. </p> <p> Another answer to the question is that people actually <em>like</em> working together. I currently advice <a href="https://idq.dk">IDQ</a> on software development principles and architecture. They have a tight-knit development team. The first day I visited them, I could feel a warm and friendly vibe. I've been visiting them regularly for about a year, now, and the first impression has proven correct. As we Danes say, that work place is positively <a href="https://en.wikipedia.org/wiki/Hygge">hyggelig</a>. </p> <p> Some people also prefer to go to the office to have a formal boundary between their professional and private lives. </p> <p> Finally, if you're into agile software development, you've probably heard about the benefits of <em>team co-location</em>. </p> <p> When the team is located in the same room, working towards the same goals, communication is <em>efficient</em> - or is it? </p> <p> You can certainly get answers to your questions quickly. All you have to do is to <em>interrupt</em> the person who can answer. If you don't know who that is, you just interrupt everybody until you've figured it out. While offices are interruption factories (as <a href="https://dhh.dk">DHH</a> puts it), this style of work can reduce latency. </p> <p> If you explicitly follow e.g. <a href="http://amzn.to/108Pxzb">lean software development</a> and implement something like <em>one-piece flow</em>, you can reduce your cycle time. The less delay between activities, the faster you can deliver value. Once you've delivered one piece (e.g. a <em>feature</em>), you move on to the next. </p> <p> <img src="/content/binary/one-piece-flow.png" alt="Alternating blocks of activities and delays going from left to right."> </p> <p> If this is truly the goal, then putting all team members in the same office makes sense. You don't get higher communications bandwidth than when you're physically together. All the subtle intonations of the way your colleagues speak, the non-verbal cues, etcetera are there if you know how to interpret them. </p> <h3 id="da39de4510544526b6234fa7d75e50bc"> Consequences of team co-location <a href="#da39de4510544526b6234fa7d75e50bc" title="permalink">#</a> </h3> <p> I've seen team co-location work for small teams. People can <a href="https://en.wikipedia.org/wiki/Pair_programming">pair program</a> or even <a href="https://en.wikipedia.org/wiki/Mob_programming">mob program</a>. You can easily draw on the expertise of your co-workers. It does require, however, that everyone respects boundaries. </p> <p> It's a balancing act. You may get your answer sooner, but your interruption could break your colleague's concentration. The net result could be negative productivity. </p> <p> While I've seen team co-location work, I've seen it fail more frequently. There are many reasons for this. </p> <p> First, there's all the interruptions. Most programmers don't like being interrupted. </p> <p> Second, the opportunity for ad-hoc communication easily leads to poor software architecture. This follows from <a href="https://en.wikipedia.org/wiki/Conway%27s_law">Conway's law</a>, which argues that <blockquote> <p> "Any organization that designs a system [...] will inevitably produce a design whose structure is a copy of the organization's communication structure." </p> <footer><cite><a href="http://www.melconway.com/Home/Committees_Paper.html">Melvin Conway</a></cite></footer> </blockquote> </p> <p> I know that it's not a law in any rigid sense of the word, but it can often be fruitful to keep an eye out for this sort of interaction. Based on my experience, it seems to happen often. </p> <p> Ad-hoc office communication leads to ad-hoc communication structures in the code. There's typically little explicit architecture. Knowledge is in the heads of people. </p> <p> Such an organisation tends to have an oral culture. There's no permanence of knowledge, no emphasis on readability of code (because you can always ask someone if there's code you don't understand), and meetings all the time. </p> <p> I once worked as a consultant for a company where there was only one old-timer around. He spent most of his time in meetings, because he knew all the intricate details of how everything worked and talked together, and other people needed to know. </p> <p> After I'd been involved with that (otherwise wonderful) company on and off for a few years, I accumulated some knowledge as well, and people wanted to have meetings with me. </p> <p> In the beginning, I obliged. Then it turned out that a week after I'd had a meeting, I'd be called to what would essentially be <em>the same</em> meeting again. Why? Because some other stakeholder heard about the first meeting and decided that he or she also required that information. The solution? Call another meeting. </p> <p> My counter-move was to begin to write things down. When people would call a meeting, I'd ask for an agenda. That alone filtered away more than half of the meetings. When I did receive an agenda, I could often reply: </p> <p> "Based on the agenda, I believe you'll find everything you need to know <em>here</em>. If not, please let me know what's missing so that I can update the document" </p> <p> I'd attach said document. By doing that, I eliminated ninety percent of my meetings. </p> <p> Notice what I did. I changed the communication structure - at least locally around me. Soon after, I went remote with that client, and had a few successful years doing that. </p> <p> I hope that the previous section outlined that working in an office can be effective, but as I've now outlined, it can also be dysfunctional. </p> <p> If you truly must deliver as soon as possible, because if you don't, the organisation isn't going to be around in five years, office work, with its low communications latency may be the best option. </p> <h3 id="e9958e6f5b75431987f76b9d084b1e30"> Remote office work <a href="#e9958e6f5b75431987f76b9d084b1e30" title="permalink">#</a> </h3> <p> I often see companies advertise for programmers. When remote work is an option, it often comes with the qualification that it must be within a particular country, or a particular time zone. </p> <p> There can be legal or bureaucratic reasons why a company only wants to hire within a country. I get that, but I consider a time zone requirement a danger sign. The same goes for <em>"we use Slack"</em> or whatever other 'team room' instant messaging technology is cool these days. </p> <p> That tells me that while the company allows people to be physically not in the office, they must still obey office hours. This indicates to me that communication remains ad-hoc and transient. Again, <a href="/2019/03/04/code-quality-is-not-software-quality">code quality</a> suffers. </p> <p> These days, because of the Corona virus, many organisations deeply entrenched in the oral culture of co-location find that they must now work as a distributed team. They try to address the situation by setting up day-long video conference calls. </p> <p> It may work in an office, but it's not the best fit for a distributed team. </p> <h3 id="1dd79d5d27e44a4da134a08a0df29fc4"> Distributed asynchronous software development <a href="#1dd79d5d27e44a4da134a08a0df29fc4" title="permalink">#</a> </h3> <p> Decades of open-source development has shown another way. Successful open-source software (OSS) projects are distributed and use asynchronous communication channels (mailing lists, issue trackers). It's worth considering the causation. I don't think anyone sat down and decided to do it this way in order to be successful. I think that the OSS projects that became successful became successful exactly because they organised work that way. </p> <p> When contributions are voluntary, you have to cast a wide net. A successful OSS project should accept contributions from around the world. If an excellent contribution from Japan falters because the project team is based in the US, and immediate, real-time communication is required, then that project has odds against it. </p> <p> An OSS project that works asynchronously can receive contributions from any time zone. The disadvantage can be significant communication lag. </p> <p> If you get a contribution from Australia, but you're in Europe, you may send a reply asking for clarifications or improvements. At the time you do that, the contributor may have already gone to bed. He or she isn't going to reply later, at which time you've gone to bed. </p> <p> It can take days to get anything done. That doesn't sound efficient, and if you're in a <em>one-piece flow</em> mindset it isn't. You need to enable parallel development. If you do that, you can work on something else while you wait for your asynchronous collaborator to respond. </p> <p> <img src="/content/binary/one-piece-flow-vs-paralle-development.png" alt="A diagram juxtaposing two pieces finished one after the other, against two pieces finished in parallel."> </p> <p> In this diagram, the wait-times in the production of one piece (e.g. one feature) can be used to move forward with another feature. The result is that you may actually be able to finish both tasks sooner than if you stick strictly to one-piece flow. </p> <p> Before you protest: in reality, delay times are much longer than implied by the diagram. An activity could be something as brief as responding to a request for more information. You may be able to finish this activity in 30 minutes, whereafter the delay time is another twenty hours. Thus, in order to keep throughput comparable, you need to juggle not two, but dozens of parallel processes. </p> <p> You may also feel the urge to protest that the diagram postulates a false dichotomy. That's not my intention. Even with co-location, you could do parallel development. </p> <p> There's also the argument that parallel development requires context switching. That's true, and it comes with overhead. </p> <p> My argument is only this: if you decide to shift to an asynchronous process, then I consider parallel development essential. Even with parallel development, you can't get the same (low) latency as is possible in the office, but you may be able to get better throughput. </p> <p> This again has implications for software architecture. Parallel development works when features can be developed independently of each other - when there's only minimal dependencies between various areas of the code. </p> <p> Conway's law is relevant here as well. If you decouple the communication between various parts of the system, you can also decouple the development of said parts. Ultimately, the best fit for a distributed, asynchronous software development <em>process</em> may be a distributed, asynchronous system. </p> <h3 id="f02f525b49564f1fadfa27d471f41e06"> Quadrants <a href="#f02f525b49564f1fadfa27d471f41e06" title="permalink">#</a> </h3> <p> This is the point where, if this was a Gartner report, it'd include a 2x2 table with four quadrants. It's not, but I'll supply it anyway: <table> <thead> <tr> <td></td> <td>Synchronous</td> <td>Asynchronous</td> </tr> </thead> <tbody> <tr> <td>Distributed</td> <td>Virtual office</td> <td>OSS-like parallel development</td> </tr> <tr> <td>Co-located</td> <td>Scrum, XP, etc.</td> <td>Emailing the person next to you</td> </tr> </tbody> </table> The current situation where the oral, co-located teams find themselves forced to work remotely is what I call the <em>virtual office</em>. If the Corona outbreak is over in weeks, it's probably best to just carry on in that way. I don't, however, think it's a sustainable process model. There's still too much friction involved in having to be connected to a video conference call for 8 hours each day. Long-term, I think that a migration towards a distributed, asynchronous process would be beneficial. </p> <p> I've yet to discuss the fourth quadrant. This is where people sit next to each other, yet still email each other. That's just weird. Like the <em>virtual office</em>, I don't think it's a long-term sustainable process. The advantages of just talking to each other is just too great. If you're co-located, ad-hoc communication is possible, so that's where the software architecture will gravitate as well. Again, Conway's law applies. </p> <p> If you want to move towards a sustainable distributed process, you should consider adjusting everything accordingly. A major endeavour in that shift involves migrating from an oral to a written culture. <a href="https://basecamp.com/guides/how-we-communicate">Basecamp has a good guide to get you started.</a> </p> <h3 id="d0381a7649cb40deab87c4388001f339"> Your writer reveals himself <a href="#d0381a7649cb40deab87c4388001f339" title="permalink">#</a> </h3> <p> I intend this to be an opinion piece. It's based on a combination of observations made by others, mixed with my personal experiences, but I also admit that it's coloured by my personal preferences. I strongly prefer distributed, asynchronous processes with an emphasis on written communication. Since this blog contains more than 500 articles, it should hardly come as a surprise to anyone that I'm a prolific writer. </p> <p> I've had great experiences with distributed, asynchronous software development. One such experience was the decade I led the <a href="https://github.com/AutoFixture/AutoFixture">AutoFixture</a> open-source project. Other experiences include a handful of commercial, closed-source projects where I did the bulk of the work remotely. </p> <p> This style of work benefits my employer. By working asynchronously, I have to document what I do, and why I do it. I leave behind a trail of text artefacts other people can consult when I'm not available. </p> <p> I like asynchronous processes because they liberate me to work when I want to, where I want to. I take advantage of this to go for a run during daylight hours (otherwise an issue during Scandinavian winters), to go grocery shopping outside of rush hour, to be with my son when he comes home from school, etcetera. I compensate by working at other hours (evenings, weekends). This isn't a lifestyle that suits everyone, but it suits me. </p> <p> This preference produces a bias in the way that I see the world. I don't think I can avoid that. Like DHH I view offices as interruption factories. I self-identify as an introvert. I like being alone. </p> <p> Still, I've tried to describe some forces that affect how work is done. I've tried to be fair to co-location, even though I don't like it. </p> <h3 id="b8e64a09f56345c883b596ff612f942f"> Conclusion <a href="#b8e64a09f56345c883b596ff612f942f" title="permalink">#</a> </h3> <p> Software development with a co-located team can be efficient. It offers the benefits of high-bandwidth communication, pair programming, and low-latency decision making. It also implies an oral tradition. Knowledge has little permanence and the team is vulnerable to key team members going missing. </p> <p> While such a team organisation can work well when team members are physically close to each other, I believe that this model comes under pressure when team members work remotely. I haven't seen the oral, ad-hoc team process work well in a distributed setting. </p> <p> Successful distributed software development is asynchronous and based on a literate culture. It only works if the software architecture allows it. Code has to be decoupled and independently deployable. If it is, though, you can perform work in parallel. Conway's law still applies. </p> </div><hr> This blog is totally free, but if you like it, please consider <a href="https://blog.ploeh.dk/support">supporting it</a>. Mark Seemann https://blog.ploeh.dk/2020/03/16/conways-law-latency-versus-throughput Polymorphic Builder https://blog.ploeh.dk/2020/03/09/polymorphic-builder/ Mon, 09 Mar 2020 06:47:00 UTC <div id="post"> <p> <em>Keeping illegal states unrepresentable with the Builder pattern.</em> </p> <p> As a reaction to <a href="/2020/02/10/builder-isomorphisms">my article on Builder isomorphisms</a> Tyson Williams asked: <blockquote> <p> "If a <code>GET</code> or <code>DELETE</code> request had a body or if a <code>POST</code> request did not have a body, then I would suspect that such behavior was a bug. </p> <p> "For the sake of a question that I would like to ask, let's suppose that a body must be added if and only if the method is <code>POST</code>. Under this assumption, <code>HttpRequestMessageBuilder</code> can create invalid messages. For example, it can create a <code>GET</code> request with a body, and it can create a <code>POST</code> request without a body. Under this assumption, how would you modify your design so that only valid messages can be created?" </p> </blockquote> I'm happy to receive that question, because I struggled to find a compelling example of a <a href="https://en.wikipedia.org/wiki/Builder_pattern">Builder</a> where polymorphism seems warranted. Here, it does. </p> <h3 id="49a6ffa95ffd44dfbf7c1160879af8e9"> Valid combinations <a href="#49a6ffa95ffd44dfbf7c1160879af8e9" title="permalink">#</a> </h3> <p> Before showing code, I think a few comments are in order. As far as I'm aware, the HTTP specification doesn't prohibit weird combinations like a <code>GET</code> request with a body. Still, such a combination is so odd that it seems fair to design an API to prevent this. </p> <p> On the other hand I think that a <code>POST</code> request without a body should still be allowed. It's not too common, but there are edge cases where this combination is valid. If you want to cause a side effect to happen, a <code>GET</code> is inappropriate, but sometimes all you want do to is to produce an effect. In the <a href="http://amzn.to/YFnkRg">Restful Web Services Cookbook</a> Subbu Allamaraju gives this example of a <em>fire-and-forget bulk task:</em> </p> <p> <pre>POST /address-correction?before=2010-01-01 HTTP/1.1</pre> </p> <p> As he puts it, <em>"in essence, the client is "flipping a switch" to start the work."</em> </p> <p> I'll design the following API to allow this combination, also because it showcases how that sort of flexibility can still be included. On the other hand, I'll prohibit the combination of a request body in a <code>GET</code> request, as Tyson Williams suggested. </p> <h3 id="5509ba650064423097e277f6f532d578"> Expanded API <a href="#5509ba650064423097e277f6f532d578" title="permalink">#</a> </h3> <p> I'll expand on the <code>HttpRequestMessageBuilder</code> example shown in the previous article. As <a href="/2020/02/17/builder-as-a-monoid#6d834828809b4ac2b36f59bb244e5952">outlined in another article</a>, apart from the <code>Build</code> method the Builder really only has two capabilities: <ul> <li>Change the HTTP method</li> <li>Add (or update) a JSON body</li> </ul> These are the two combinations we now need to model differently. If I do that now, there'd be no other affordances offered by the Builder API. In order to make the example more explicit, I'll first add a pair of new capabilities: <ul> <li>Add or change the <code>Accept</code> header</li> <li>Add or change a <code>Bearer</code> token</li> </ul> When I do that, the <code>HttpRequestMessageBuilder</code> class now looks like this: </p> <p> <pre><span style="color:blue;">public</span>&nbsp;<span style="color:blue;">class</span>&nbsp;<span style="color:#2b91af;">HttpRequestMessageBuilder</span> { &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">private</span>&nbsp;<span style="color:blue;">readonly</span>&nbsp;<span style="color:#2b91af;">Uri</span>&nbsp;url; &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">private</span>&nbsp;<span style="color:blue;">readonly</span>&nbsp;<span style="color:blue;">object</span>?&nbsp;jsonBody; &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">private</span>&nbsp;<span style="color:blue;">readonly</span>&nbsp;<span style="color:blue;">string</span>?&nbsp;acceptHeader; &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">private</span>&nbsp;<span style="color:blue;">readonly</span>&nbsp;<span style="color:blue;">string</span>?&nbsp;bearerToken; &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">public</span>&nbsp;<span style="color:#2b91af;">HttpRequestMessageBuilder</span>(<span style="color:blue;">string</span>&nbsp;<span style="font-weight:bold;color:#1f377f;">url</span>)&nbsp;:&nbsp;<span style="color:blue;">this</span>(<span style="color:blue;">new</span>&nbsp;<span style="color:#2b91af;">Uri</span>(<span style="font-weight:bold;color:#1f377f;">url</span>))&nbsp;{&nbsp;} &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">public</span>&nbsp;<span style="color:#2b91af;">HttpRequestMessageBuilder</span>(<span style="color:#2b91af;">Uri</span>&nbsp;<span style="font-weight:bold;color:#1f377f;">url</span>)&nbsp;: &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">this</span>(<span style="font-weight:bold;color:#1f377f;">url</span>,&nbsp;<span style="color:#2b91af;">HttpMethod</span>.Get,&nbsp;<span style="color:blue;">null</span>,&nbsp;<span style="color:blue;">null</span>,&nbsp;<span style="color:blue;">null</span>)&nbsp;{&nbsp;} &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">private</span>&nbsp;<span style="color:#2b91af;">HttpRequestMessageBuilder</span>( &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:#2b91af;">Uri</span>&nbsp;<span style="font-weight:bold;color:#1f377f;">url</span>, &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:#2b91af;">HttpMethod</span>&nbsp;<span style="font-weight:bold;color:#1f377f;">method</span>, &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">object</span>?&nbsp;<span style="font-weight:bold;color:#1f377f;">jsonBody</span>, &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">string</span>?&nbsp;<span style="font-weight:bold;color:#1f377f;">acceptHeader</span>, &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">string</span>?&nbsp;<span style="font-weight:bold;color:#1f377f;">bearerToken</span>) &nbsp;&nbsp;&nbsp;&nbsp;{ &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">this</span>.url&nbsp;=&nbsp;<span style="font-weight:bold;color:#1f377f;">url</span>; &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;Method&nbsp;=&nbsp;<span style="font-weight:bold;color:#1f377f;">method</span>; &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">this</span>.jsonBody&nbsp;=&nbsp;<span style="font-weight:bold;color:#1f377f;">jsonBody</span>; &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">this</span>.acceptHeader&nbsp;=&nbsp;<span style="font-weight:bold;color:#1f377f;">acceptHeader</span>; &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">this</span>.bearerToken&nbsp;=&nbsp;<span style="font-weight:bold;color:#1f377f;">bearerToken</span>; &nbsp;&nbsp;&nbsp;&nbsp;} &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">public</span>&nbsp;<span style="color:#2b91af;">HttpMethod</span>&nbsp;Method&nbsp;{&nbsp;<span style="color:blue;">get</span>;&nbsp;} &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">public</span>&nbsp;<span style="color:#2b91af;">HttpRequestMessageBuilder</span>&nbsp;<span style="font-weight:bold;color:#74531f;">WithMethod</span>(<span style="color:#2b91af;">HttpMethod</span>&nbsp;<span style="font-weight:bold;color:#1f377f;">newMethod</span>) &nbsp;&nbsp;&nbsp;&nbsp;{ &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="font-weight:bold;color:#8f08c4;">return</span>&nbsp;<span style="color:blue;">new</span>&nbsp;<span style="color:#2b91af;">HttpRequestMessageBuilder</span>( &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;url, &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="font-weight:bold;color:#1f377f;">newMethod</span>, &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;jsonBody, &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;acceptHeader, &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;bearerToken); &nbsp;&nbsp;&nbsp;&nbsp;} &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">public</span>&nbsp;<span style="color:#2b91af;">HttpRequestMessageBuilder</span>&nbsp;<span style="font-weight:bold;color:#74531f;">AddJsonBody</span>(<span style="color:blue;">object</span>&nbsp;<span style="font-weight:bold;color:#1f377f;">jsonBody</span>) &nbsp;&nbsp;&nbsp;&nbsp;{ &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="font-weight:bold;color:#8f08c4;">return</span>&nbsp;<span style="color:blue;">new</span>&nbsp;<span style="color:#2b91af;">HttpRequestMessageBuilder</span>( &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;url, &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;Method, &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="font-weight:bold;color:#1f377f;">jsonBody</span>, &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;acceptHeader, &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;bearerToken); &nbsp;&nbsp;&nbsp;&nbsp;} &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">public</span>&nbsp;<span style="color:#2b91af;">HttpRequestMessageBuilder</span>&nbsp;<span style="font-weight:bold;color:#74531f;">WithAcceptHeader</span>(<span style="color:blue;">string</span>&nbsp;<span style="font-weight:bold;color:#1f377f;">newAcceptHeader</span>) &nbsp;&nbsp;&nbsp;&nbsp;{ &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="font-weight:bold;color:#8f08c4;">return</span>&nbsp;<span style="color:blue;">new</span>&nbsp;<span style="color:#2b91af;">HttpRequestMessageBuilder</span>( &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;url, &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;Method, &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;jsonBody, &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="font-weight:bold;color:#1f377f;">newAcceptHeader</span>, &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;bearerToken); &nbsp;&nbsp;&nbsp;&nbsp;} &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">public</span>&nbsp;<span style="color:#2b91af;">HttpRequestMessageBuilder</span>&nbsp;<span style="font-weight:bold;color:#74531f;">WithBearerToken</span>(<span style="color:blue;">string</span>&nbsp;<span style="font-weight:bold;color:#1f377f;">newBearerToken</span>) &nbsp;&nbsp;&nbsp;&nbsp;{ &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="font-weight:bold;color:#8f08c4;">return</span>&nbsp;<span style="color:blue;">new</span>&nbsp;<span style="color:#2b91af;">HttpRequestMessageBuilder</span>( &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;url, &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;Method, &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;jsonBody, &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;acceptHeader, &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="font-weight:bold;color:#1f377f;">newBearerToken</span>); &nbsp;&nbsp;&nbsp;&nbsp;} &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">public</span>&nbsp;<span style="color:#2b91af;">HttpRequestMessage</span>&nbsp;<span style="font-weight:bold;color:#74531f;">Build</span>() &nbsp;&nbsp;&nbsp;&nbsp;{ &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">var</span>&nbsp;<span style="font-weight:bold;color:#1f377f;">message</span>&nbsp;=&nbsp;<span style="color:blue;">new</span>&nbsp;<span style="color:#2b91af;">HttpRequestMessage</span>(Method,&nbsp;url); &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="font-weight:bold;color:#74531f;">BuildBody</span>(<span style="font-weight:bold;color:#1f377f;">message</span>); &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="font-weight:bold;color:#74531f;">AddAcceptHeader</span>(<span style="font-weight:bold;color:#1f377f;">message</span>); &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="font-weight:bold;color:#74531f;">AddBearerToken</span>(<span style="font-weight:bold;color:#1f377f;">message</span>); &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="font-weight:bold;color:#8f08c4;">return</span>&nbsp;<span style="font-weight:bold;color:#1f377f;">message</span>; &nbsp;&nbsp;&nbsp;&nbsp;} &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">private</span>&nbsp;<span style="color:blue;">void</span>&nbsp;<span style="font-weight:bold;color:#74531f;">BuildBody</span>(<span style="color:#2b91af;">HttpRequestMessage</span>&nbsp;<span style="font-weight:bold;color:#1f377f;">message</span>) &nbsp;&nbsp;&nbsp;&nbsp;{ &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="font-weight:bold;color:#8f08c4;">if</span>&nbsp;(jsonBody&nbsp;<span style="color:blue;">is</span>&nbsp;<span style="color:blue;">null</span>) &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="font-weight:bold;color:#8f08c4;">return</span>; &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">string</span>&nbsp;<span style="font-weight:bold;color:#1f377f;">json</span>&nbsp;=&nbsp;<span style="color:#2b91af;">JsonConvert</span>.<span style="color:#74531f;">SerializeObject</span>(jsonBody); &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="font-weight:bold;color:#1f377f;">message</span>.Content&nbsp;=&nbsp;<span style="color:blue;">new</span>&nbsp;<span style="color:#2b91af;">StringContent</span>(<span style="font-weight:bold;color:#1f377f;">json</span>); &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="font-weight:bold;color:#1f377f;">message</span>.Content.Headers.ContentType.MediaType&nbsp;=&nbsp;<span style="color:#a31515;">&quot;application/json&quot;</span>; &nbsp;&nbsp;&nbsp;&nbsp;} &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">private</span>&nbsp;<span style="color:blue;">void</span>&nbsp;<span style="font-weight:bold;color:#74531f;">AddAcceptHeader</span>(<span style="color:#2b91af;">HttpRequestMessage</span>&nbsp;<span style="font-weight:bold;color:#1f377f;">message</span>) &nbsp;&nbsp;&nbsp;&nbsp;{ &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="font-weight:bold;color:#8f08c4;">if</span>&nbsp;(acceptHeader&nbsp;<span style="color:blue;">is</span>&nbsp;<span style="color:blue;">null</span>) &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="font-weight:bold;color:#8f08c4;">return</span>; &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="font-weight:bold;color:#1f377f;">message</span>.Headers.Accept.<span style="font-weight:bold;color:#74531f;">ParseAdd</span>(acceptHeader); &nbsp;&nbsp;&nbsp;&nbsp;} &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">private</span>&nbsp;<span style="color:blue;">void</span>&nbsp;<span style="font-weight:bold;color:#74531f;">AddBearerToken</span>(<span style="color:#2b91af;">HttpRequestMessage</span>&nbsp;<span style="font-weight:bold;color:#1f377f;">message</span>) &nbsp;&nbsp;&nbsp;&nbsp;{ &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="font-weight:bold;color:#8f08c4;">if</span>&nbsp;(bearerToken&nbsp;<span style="color:blue;">is</span>&nbsp;<span style="color:blue;">null</span>) &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="font-weight:bold;color:#8f08c4;">return</span>; &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="font-weight:bold;color:#1f377f;">message</span>.Headers.Authorization&nbsp;= &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">new</span>&nbsp;<span style="color:#2b91af;">AuthenticationHeaderValue</span>(<span style="color:#a31515;">&quot;Bearer&quot;</span>,&nbsp;bearerToken); &nbsp;&nbsp;&nbsp;&nbsp;} }</pre> </p> <p> Notice that I've added the methods <code>WithAcceptHeader</code> and <code>WithBearerToken</code>, with supporting implementation. So far, those are the only changes. </p> <p> It enables you to build HTTP request messages like this: </p> <p> <pre><span style="color:#2b91af;">HttpRequestMessage</span>&nbsp;<span style="font-weight:bold;color:#1f377f;">msg</span>&nbsp;=&nbsp;<span style="color:blue;">new</span>&nbsp;<span style="color:#2b91af;">HttpRequestMessageBuilder</span>(<span style="font-weight:bold;color:#1f377f;">url</span>) &nbsp;&nbsp;&nbsp;&nbsp;.<span style="font-weight:bold;color:#74531f;">WithBearerToken</span>(<span style="color:#a31515;">&quot;cGxvZWg=&quot;</span>) &nbsp;&nbsp;&nbsp;&nbsp;.<span style="font-weight:bold;color:#74531f;">Build</span>();</pre> </p> <p> Or this: </p> <p> <pre><span style="color:#2b91af;">HttpRequestMessage</span>&nbsp;<span style="font-weight:bold;color:#1f377f;">msg</span>&nbsp;=&nbsp;<span style="color:blue;">new</span>&nbsp;<span style="color:#2b91af;">HttpRequestMessageBuilder</span>(<span style="font-weight:bold;color:#1f377f;">url</span>) &nbsp;&nbsp;&nbsp;&nbsp;.<span style="font-weight:bold;color:#74531f;">WithMethod</span>(<span style="color:#2b91af;">HttpMethod</span>.Post) &nbsp;&nbsp;&nbsp;&nbsp;.<span style="font-weight:bold;color:#74531f;">AddJsonBody</span>(<span style="color:blue;">new</span> &nbsp;&nbsp;&nbsp;&nbsp;{ &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;id&nbsp;=&nbsp;<span style="color:#2b91af;">Guid</span>.<span style="color:#74531f;">NewGuid</span>(), &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;date&nbsp;=&nbsp;<span style="color:#a31515;">&quot;2021-02-09&nbsp;19:15:00&quot;</span>, &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;name&nbsp;=&nbsp;<span style="color:#a31515;">&quot;Hervor&quot;</span>, &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;email&nbsp;=&nbsp;<span style="color:#a31515;">&quot;hervor@example.com&quot;</span>, &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;quantity&nbsp;=&nbsp;2 &nbsp;&nbsp;&nbsp;&nbsp;}) &nbsp;&nbsp;&nbsp;&nbsp;.<span style="font-weight:bold;color:#74531f;">WithAcceptHeader</span>(<span style="color:#a31515;">&quot;application/vnd.foo.bar+json&quot;</span>) &nbsp;&nbsp;&nbsp;&nbsp;.<span style="font-weight:bold;color:#74531f;">WithBearerToken</span>(<span style="color:#a31515;">&quot;cGxvZWg=&quot;</span>) &nbsp;&nbsp;&nbsp;&nbsp;.<span style="font-weight:bold;color:#74531f;">Build</span>();</pre> </p> <p> It still doesn't address Tyson Williams' requirement, because you can build an HTTP request like this: </p> <p> <pre><span style="color:#2b91af;">HttpRequestMessage</span>&nbsp;<span style="font-weight:bold;color:#1f377f;">msg</span>&nbsp;=&nbsp;<span style="color:blue;">new</span>&nbsp;<span style="color:#2b91af;">HttpRequestMessageBuilder</span>(<span style="font-weight:bold;color:#1f377f;">url</span>) &nbsp;&nbsp;&nbsp;&nbsp;.<span style="font-weight:bold;color:#74531f;">AddJsonBody</span>(<span style="color:blue;">new</span>&nbsp;{ &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;id&nbsp;=&nbsp;<span style="color:#2b91af;">Guid</span>.<span style="color:#74531f;">NewGuid</span>(), &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;date&nbsp;=&nbsp;<span style="color:#a31515;">&quot;2020-03-22&nbsp;19:30:00&quot;</span>, &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;name&nbsp;=&nbsp;<span style="color:#a31515;">&quot;Ælfgifu&quot;</span>, &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;email&nbsp;=&nbsp;<span style="color:#a31515;">&quot;ælfgifu@example.net&quot;</span>, &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;quantity&nbsp;=&nbsp;1&nbsp;}) &nbsp;&nbsp;&nbsp;&nbsp;.<span style="font-weight:bold;color:#74531f;">Build</span>();</pre> </p> <p> Recall that the default HTTP method is <code>GET</code>. Since the above code doesn't specify a method, it creates a <code>GET</code> request with a message body. That's what shouldn't be possible. Let's <a href="https://blog.janestreet.com/effective-ml-video">make illegal states unrepresentable</a>. </p> <h3 id="95ac7d907e2b461ea56247bfe4eec6da"> Builder interface <a href="#95ac7d907e2b461ea56247bfe4eec6da" title="permalink">#</a> </h3> <p> Making illegal states unrepresentable is a catch phrase coined by <a href="https://twitter.com/yminsky">Yaron Minsky</a> to describe advantages of statically typed functional programming. Unintentionally, it also describes a fundamental tenet of object-oriented programming. In <a href="http://amzn.to/1claOin">Object-Oriented Software Construction</a> Bertrand Meyer describes object-oriented programming as the discipline of guaranteeing that an object can never be in an invalid state. </p> <p> In the present example, we can't allow an arbitrary HTTP Builder object to afford an operation to add a body, because that Builder object might produce a <code>GET</code> request. On the other hand, there are operations that are <em>always</em> legal: adding an <code>Accept</code> header or a <code>Bearer</code> token. Because these operations are always legal, they constitute a shared API. Extract those to an interface: </p> <p> <pre><span style="color:blue;">public</span>&nbsp;<span style="color:blue;">interface</span>&nbsp;<span style="color:#2b91af;">IHttpRequestMessageBuilder</span> { &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:#2b91af;">IHttpRequestMessageBuilder</span>&nbsp;<span style="font-weight:bold;color:#74531f;">WithAcceptHeader</span>(<span style="color:blue;">string</span>&nbsp;<span style="font-weight:bold;color:#1f377f;">newAcceptHeader</span>); &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:#2b91af;">IHttpRequestMessageBuilder</span>&nbsp;<span style="font-weight:bold;color:#74531f;">WithBearerToken</span>(<span style="color:blue;">string</span>&nbsp;<span style="font-weight:bold;color:#1f377f;">newBearerToken</span>); &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:#2b91af;">HttpRequestMessage</span>&nbsp;<span style="font-weight:bold;color:#74531f;">Build</span>(); }</pre> </p> <p> Notice that both the <code>With[...]</code> methods return the new interface. Any <code>IHttpRequestMessageBuilder</code> must implement the interface, but is free to support other operations not part of the interface. </p> <h3 id="23af7eedc51441118c8bd8819f9b3ce3"> HTTP GET Builder <a href="#23af7eedc51441118c8bd8819f9b3ce3" title="permalink">#</a> </h3> <p> You can now implement the interface to build HTTP <code>GET</code> requests: </p> <p> <pre><span style="color:blue;">public</span>&nbsp;<span style="color:blue;">class</span>&nbsp;<span style="color:#2b91af;">HttpGetMessageBuilder</span>&nbsp;:&nbsp;<span style="color:#2b91af;">IHttpRequestMessageBuilder</span> { &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">private</span>&nbsp;<span style="color:blue;">readonly</span>&nbsp;<span style="color:#2b91af;">Uri</span>&nbsp;url; &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">private</span>&nbsp;<span style="color:blue;">readonly</span>&nbsp;<span style="color:blue;">string</span>?&nbsp;acceptHeader; &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">private</span>&nbsp;<span style="color:blue;">readonly</span>&nbsp;<span style="color:blue;">string</span>?&nbsp;bearerToken; &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">public</span>&nbsp;<span style="color:#2b91af;">HttpGetMessageBuilder</span>(<span style="color:blue;">string</span>&nbsp;<span style="font-weight:bold;color:#1f377f;">url</span>)&nbsp;:&nbsp;<span style="color:blue;">this</span>(<span style="color:blue;">new</span>&nbsp;<span style="color:#2b91af;">Uri</span>(<span style="font-weight:bold;color:#1f377f;">url</span>))&nbsp;{&nbsp;} &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">public</span>&nbsp;<span style="color:#2b91af;">HttpGetMessageBuilder</span>(<span style="color:#2b91af;">Uri</span>&nbsp;<span style="font-weight:bold;color:#1f377f;">url</span>)&nbsp;:&nbsp;<span style="color:blue;">this</span>(<span style="font-weight:bold;color:#1f377f;">url</span>,&nbsp;<span style="color:blue;">null</span>,&nbsp;<span style="color:blue;">null</span>)&nbsp;{&nbsp;} &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">private</span>&nbsp;<span style="color:#2b91af;">HttpGetMessageBuilder</span>( &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:#2b91af;">Uri</span>&nbsp;<span style="font-weight:bold;color:#1f377f;">url</span>, &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">string</span>?&nbsp;<span style="font-weight:bold;color:#1f377f;">acceptHeader</span>, &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">string</span>?&nbsp;<span style="font-weight:bold;color:#1f377f;">bearerToken</span>) &nbsp;&nbsp;&nbsp;&nbsp;{ &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">this</span>.url&nbsp;=&nbsp;<span style="font-weight:bold;color:#1f377f;">url</span>; &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">this</span>.acceptHeader&nbsp;=&nbsp;<span style="font-weight:bold;color:#1f377f;">acceptHeader</span>; &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">this</span>.bearerToken&nbsp;=&nbsp;<span style="font-weight:bold;color:#1f377f;">bearerToken</span>; &nbsp;&nbsp;&nbsp;&nbsp;} &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">public</span>&nbsp;<span style="color:#2b91af;">IHttpRequestMessageBuilder</span>&nbsp;<span style="font-weight:bold;color:#74531f;">WithAcceptHeader</span>(<span style="color:blue;">string</span>&nbsp;<span style="font-weight:bold;color:#1f377f;">newAcceptHeader</span>) &nbsp;&nbsp;&nbsp;&nbsp;{ &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="font-weight:bold;color:#8f08c4;">return</span>&nbsp;<span style="color:blue;">new</span>&nbsp;<span style="color:#2b91af;">HttpGetMessageBuilder</span>(url,&nbsp;<span style="font-weight:bold;color:#1f377f;">newAcceptHeader</span>,&nbsp;bearerToken); &nbsp;&nbsp;&nbsp;&nbsp;} &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">public</span>&nbsp;<span style="color:#2b91af;">IHttpRequestMessageBuilder</span>&nbsp;<span style="font-weight:bold;color:#74531f;">WithBearerToken</span>(<span style="color:blue;">string</span>&nbsp;<span style="font-weight:bold;color:#1f377f;">newBearerToken</span>) &nbsp;&nbsp;&nbsp;&nbsp;{ &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="font-weight:bold;color:#8f08c4;">return</span>&nbsp;<span style="color:blue;">new</span>&nbsp;<span style="color:#2b91af;">HttpGetMessageBuilder</span>(url,&nbsp;acceptHeader,&nbsp;<span style="font-weight:bold;color:#1f377f;">newBearerToken</span>); &nbsp;&nbsp;&nbsp;&nbsp;} &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">public</span>&nbsp;<span style="color:#2b91af;">HttpRequestMessage</span>&nbsp;<span style="font-weight:bold;color:#74531f;">Build</span>() &nbsp;&nbsp;&nbsp;&nbsp;{ &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">var</span>&nbsp;<span style="font-weight:bold;color:#1f377f;">message</span>&nbsp;=&nbsp;<span style="color:blue;">new</span>&nbsp;<span style="color:#2b91af;">HttpRequestMessage</span>(<span style="color:#2b91af;">HttpMethod</span>.Get,&nbsp;url); &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="font-weight:bold;color:#74531f;">AddAcceptHeader</span>(<span style="font-weight:bold;color:#1f377f;">message</span>); &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="font-weight:bold;color:#74531f;">AddBearerToken</span>(<span style="font-weight:bold;color:#1f377f;">message</span>); &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="font-weight:bold;color:#8f08c4;">return</span>&nbsp;<span style="font-weight:bold;color:#1f377f;">message</span>; &nbsp;&nbsp;&nbsp;&nbsp;} &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">private</span>&nbsp;<span style="color:blue;">void</span>&nbsp;<span style="font-weight:bold;color:#74531f;">AddAcceptHeader</span>(<span style="color:#2b91af;">HttpRequestMessage</span>&nbsp;<span style="font-weight:bold;color:#1f377f;">message</span>) &nbsp;&nbsp;&nbsp;&nbsp;{ &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="font-weight:bold;color:#8f08c4;">if</span>&nbsp;(acceptHeader&nbsp;<span style="color:blue;">is</span>&nbsp;<span style="color:blue;">null</span>) &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="font-weight:bold;color:#8f08c4;">return</span>; &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="font-weight:bold;color:#1f377f;">message</span>.Headers.Accept.<span style="font-weight:bold;color:#74531f;">ParseAdd</span>(acceptHeader); &nbsp;&nbsp;&nbsp;&nbsp;} &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">private</span>&nbsp;<span style="color:blue;">void</span>&nbsp;<span style="font-weight:bold;color:#74531f;">AddBearerToken</span>(<span style="color:#2b91af;">HttpRequestMessage</span>&nbsp;<span style="font-weight:bold;color:#1f377f;">message</span>) &nbsp;&nbsp;&nbsp;&nbsp;{ &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="font-weight:bold;color:#8f08c4;">if</span>&nbsp;(bearerToken&nbsp;<span style="color:blue;">is</span>&nbsp;<span style="color:blue;">null</span>) &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="font-weight:bold;color:#8f08c4;">return</span>; &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="font-weight:bold;color:#1f377f;">message</span>.Headers.Authorization&nbsp;= &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">new</span>&nbsp;<span style="color:#2b91af;">AuthenticationHeaderValue</span>(<span style="color:#a31515;">&quot;Bearer&quot;</span>,&nbsp;bearerToken); &nbsp;&nbsp;&nbsp;&nbsp;} }</pre> </p> <p> Notice that the <code>Build</code> method hard-codes <code>HttpMethod.Get</code>. When you're using an <code>HttpGetMessageBuilder</code> object, you can't modify the HTTP method. You also can't add a request body, because there's no API that affords that operation. </p> <p> What you <em>can</em> do, for example, is to create an HTTP request with an <code>Accept</code> header: </p> <p> <pre><span style="color:#2b91af;">HttpRequestMessage</span>&nbsp;<span style="font-weight:bold;color:#1f377f;">msg</span>&nbsp;=&nbsp;<span style="color:blue;">new</span>&nbsp;<span style="color:#2b91af;">HttpGetMessageBuilder</span>(<span style="font-weight:bold;color:#1f377f;">url</span>) &nbsp;&nbsp;&nbsp;&nbsp;.<span style="font-weight:bold;color:#74531f;">WithAcceptHeader</span>(<span style="color:#a31515;">&quot;application/vnd.foo.bar+json&quot;</span>) &nbsp;&nbsp;&nbsp;&nbsp;.<span style="font-weight:bold;color:#74531f;">Build</span>();</pre> </p> <p> This creates a request with an <code>Accept</code> header, but no <code>Bearer</code> token. </p> <h3 id="b96c590c45394c1d86ec0ff841b82a52"> HTTP POST Builder <a href="#b96c590c45394c1d86ec0ff841b82a52" title="permalink">#</a> </h3> <p> As a peer to <code>HttpGetMessageBuilder</code> you can implement the <code>IHttpRequestMessageBuilder</code> interface to support <code>POST</code> requests: </p> <p> <pre><span style="color:blue;">public</span>&nbsp;<span style="color:blue;">class</span>&nbsp;<span style="color:#2b91af;">HttpPostMessageBuilder</span>&nbsp;:&nbsp;<span style="color:#2b91af;">IHttpRequestMessageBuilder</span> { &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">private</span>&nbsp;<span style="color:blue;">readonly</span>&nbsp;<span style="color:#2b91af;">Uri</span>&nbsp;url; &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">private</span>&nbsp;<span style="color:blue;">readonly</span>&nbsp;<span style="color:blue;">object</span>?&nbsp;jsonBody; &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">private</span>&nbsp;<span style="color:blue;">readonly</span>&nbsp;<span style="color:blue;">string</span>?&nbsp;acceptHeader; &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">private</span>&nbsp;<span style="color:blue;">readonly</span>&nbsp;<span style="color:blue;">string</span>?&nbsp;bearerToken; &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">public</span>&nbsp;<span style="color:#2b91af;">HttpPostMessageBuilder</span>(<span style="color:blue;">string</span>&nbsp;<span style="font-weight:bold;color:#1f377f;">url</span>)&nbsp;:&nbsp;<span style="color:blue;">this</span>(<span style="color:blue;">new</span>&nbsp;<span style="color:#2b91af;">Uri</span>(<span style="font-weight:bold;color:#1f377f;">url</span>))&nbsp;{&nbsp;} &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">public</span>&nbsp;<span style="color:#2b91af;">HttpPostMessageBuilder</span>(<span style="color:#2b91af;">Uri</span>&nbsp;<span style="font-weight:bold;color:#1f377f;">url</span>)&nbsp;:&nbsp;<span style="color:blue;">this</span>(<span style="font-weight:bold;color:#1f377f;">url</span>,&nbsp;<span style="color:blue;">null</span>,&nbsp;<span style="color:blue;">null</span>,&nbsp;<span style="color:blue;">null</span>)&nbsp;{&nbsp;} &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">public</span>&nbsp;<span style="color:#2b91af;">HttpPostMessageBuilder</span>(<span style="color:blue;">string</span>&nbsp;<span style="font-weight:bold;color:#1f377f;">url</span>,&nbsp;<span style="color:blue;">object</span>&nbsp;<span style="font-weight:bold;color:#1f377f;">jsonBody</span>)&nbsp;: &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">this</span>(<span style="color:blue;">new</span>&nbsp;<span style="color:#2b91af;">Uri</span>(<span style="font-weight:bold;color:#1f377f;">url</span>),&nbsp;<span style="font-weight:bold;color:#1f377f;">jsonBody</span>) &nbsp;&nbsp;&nbsp;&nbsp;{&nbsp;} &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">public</span>&nbsp;<span style="color:#2b91af;">HttpPostMessageBuilder</span>(<span style="color:#2b91af;">Uri</span>&nbsp;<span style="font-weight:bold;color:#1f377f;">url</span>,&nbsp;<span style="color:blue;">object</span>&nbsp;<span style="font-weight:bold;color:#1f377f;">jsonBody</span>)&nbsp;: &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">this</span>(<span style="font-weight:bold;color:#1f377f;">url</span>,&nbsp;<span style="font-weight:bold;color:#1f377f;">jsonBody</span>,&nbsp;<span style="color:blue;">null</span>,&nbsp;<span style="color:blue;">null</span>) &nbsp;&nbsp;&nbsp;&nbsp;{&nbsp;} &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">private</span>&nbsp;<span style="color:#2b91af;">HttpPostMessageBuilder</span>( &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:#2b91af;">Uri</span>&nbsp;<span style="font-weight:bold;color:#1f377f;">url</span>, &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">object</span>?&nbsp;<span style="font-weight:bold;color:#1f377f;">jsonBody</span>, &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">string</span>?&nbsp;<span style="font-weight:bold;color:#1f377f;">acceptHeader</span>, &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">string</span>?&nbsp;<span style="font-weight:bold;color:#1f377f;">bearerToken</span>) &nbsp;&nbsp;&nbsp;&nbsp;{ &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">this</span>.url&nbsp;=&nbsp;<span style="font-weight:bold;color:#1f377f;">url</span>; &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">this</span>.jsonBody&nbsp;=&nbsp;<span style="font-weight:bold;color:#1f377f;">jsonBody</span>; &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">this</span>.acceptHeader&nbsp;=&nbsp;<span style="font-weight:bold;color:#1f377f;">acceptHeader</span>; &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">this</span>.bearerToken&nbsp;=&nbsp;<span style="font-weight:bold;color:#1f377f;">bearerToken</span>; &nbsp;&nbsp;&nbsp;&nbsp;} &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">public</span>&nbsp;<span style="color:#2b91af;">IHttpRequestMessageBuilder</span>&nbsp;<span style="font-weight:bold;color:#74531f;">WithAcceptHeader</span>(<span style="color:blue;">string</span>&nbsp;<span style="font-weight:bold;color:#1f377f;">newAcceptHeader</span>) &nbsp;&nbsp;&nbsp;&nbsp;{ &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="font-weight:bold;color:#8f08c4;">return</span>&nbsp;<span style="color:blue;">new</span>&nbsp;<span style="color:#2b91af;">HttpPostMessageBuilder</span>( &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;url, &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;jsonBody, &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="font-weight:bold;color:#1f377f;">newAcceptHeader</span>, &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;bearerToken); &nbsp;&nbsp;&nbsp;&nbsp;} &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">public</span>&nbsp;<span style="color:#2b91af;">IHttpRequestMessageBuilder</span>&nbsp;<span style="font-weight:bold;color:#74531f;">WithBearerToken</span>(<span style="color:blue;">string</span>&nbsp;<span style="font-weight:bold;color:#1f377f;">newBearerToken</span>) &nbsp;&nbsp;&nbsp;&nbsp;{ &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="font-weight:bold;color:#8f08c4;">return</span>&nbsp;<span style="color:blue;">new</span>&nbsp;<span style="color:#2b91af;">HttpPostMessageBuilder</span>( &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;url, &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;jsonBody, &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;acceptHeader, &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="font-weight:bold;color:#1f377f;">newBearerToken</span>); &nbsp;&nbsp;&nbsp;&nbsp;} &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">public</span>&nbsp;<span style="color:#2b91af;">HttpRequestMessage</span>&nbsp;<span style="font-weight:bold;color:#74531f;">Build</span>() &nbsp;&nbsp;&nbsp;&nbsp;{ &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">var</span>&nbsp;<span style="font-weight:bold;color:#1f377f;">message</span>&nbsp;=&nbsp;<span style="color:blue;">new</span>&nbsp;<span style="color:#2b91af;">HttpRequestMessage</span>(<span style="color:#2b91af;">HttpMethod</span>.Post,&nbsp;url); &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="font-weight:bold;color:#74531f;">BuildBody</span>(<span style="font-weight:bold;color:#1f377f;">message</span>); &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="font-weight:bold;color:#74531f;">AddAcceptHeader</span>(<span style="font-weight:bold;color:#1f377f;">message</span>); &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="font-weight:bold;color:#74531f;">AddBearerToken</span>(<span style="font-weight:bold;color:#1f377f;">message</span>); &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="font-weight:bold;color:#8f08c4;">return</span>&nbsp;<span style="font-weight:bold;color:#1f377f;">message</span>; &nbsp;&nbsp;&nbsp;&nbsp;} &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">private</span>&nbsp;<span style="color:blue;">void</span>&nbsp;<span style="font-weight:bold;color:#74531f;">BuildBody</span>(<span style="color:#2b91af;">HttpRequestMessage</span>&nbsp;<span style="font-weight:bold;color:#1f377f;">message</span>) &nbsp;&nbsp;&nbsp;&nbsp;{ &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="font-weight:bold;color:#8f08c4;">if</span>&nbsp;(jsonBody&nbsp;<span style="color:blue;">is</span>&nbsp;<span style="color:blue;">null</span>) &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="font-weight:bold;color:#8f08c4;">return</span>; &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">string</span>&nbsp;<span style="font-weight:bold;color:#1f377f;">json</span>&nbsp;=&nbsp;<span style="color:#2b91af;">JsonConvert</span>.<span style="color:#74531f;">SerializeObject</span>(jsonBody); &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="font-weight:bold;color:#1f377f;">message</span>.Content&nbsp;=&nbsp;<span style="color:blue;">new</span>&nbsp;<span style="color:#2b91af;">StringContent</span>(<span style="font-weight:bold;color:#1f377f;">json</span>); &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="font-weight:bold;color:#1f377f;">message</span>.Content.Headers.ContentType.MediaType&nbsp;=&nbsp;<span style="color:#a31515;">&quot;application/json&quot;</span>; &nbsp;&nbsp;&nbsp;&nbsp;} &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">private</span>&nbsp;<span style="color:blue;">void</span>&nbsp;<span style="font-weight:bold;color:#74531f;">AddAcceptHeader</span>(<span style="color:#2b91af;">HttpRequestMessage</span>&nbsp;<span style="font-weight:bold;color:#1f377f;">message</span>) &nbsp;&nbsp;&nbsp;&nbsp;{ &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="font-weight:bold;color:#8f08c4;">if</span>&nbsp;(acceptHeader&nbsp;<span style="color:blue;">is</span>&nbsp;<span style="color:blue;">null</span>) &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="font-weight:bold;color:#8f08c4;">return</span>; &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="font-weight:bold;color:#1f377f;">message</span>.Headers.Accept.<span style="font-weight:bold;color:#74531f;">ParseAdd</span>(acceptHeader); &nbsp;&nbsp;&nbsp;&nbsp;} &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">private</span>&nbsp;<span style="color:blue;">void</span>&nbsp;<span style="font-weight:bold;color:#74531f;">AddBearerToken</span>(<span style="color:#2b91af;">HttpRequestMessage</span>&nbsp;<span style="font-weight:bold;color:#1f377f;">message</span>) &nbsp;&nbsp;&nbsp;&nbsp;{ &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="font-weight:bold;color:#8f08c4;">if</span>&nbsp;(bearerToken&nbsp;<span style="color:blue;">is</span>&nbsp;<span style="color:blue;">null</span>) &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="font-weight:bold;color:#8f08c4;">return</span>; &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="font-weight:bold;color:#1f377f;">message</span>.Headers.Authorization&nbsp;= &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">new</span>&nbsp;<span style="color:#2b91af;">AuthenticationHeaderValue</span>(<span style="color:#a31515;">&quot;Bearer&quot;</span>,&nbsp;bearerToken); &nbsp;&nbsp;&nbsp;&nbsp;} }</pre> </p> <p> This class affords various constructor overloads. Two of them don't take a JSON body, and two of them do. This supports both the case where you do want to supply a request body, and the edge case where you don't. </p> <p> I didn't add an explicit <code>WithJsonBody</code> method to the class, so you can't change your mind once you've created an instance of <code>HttpPostMessageBuilder</code>. The only reason I didn't, though, was to save some space. You can add such a method if you'd like to. As long as it's not part of the interface, but only part of the concrete <code>HttpPostMessageBuilder</code> class, illegal states are still unrepresentable. You can represent a <code>POST</code> request with or without a body, but you can't represent a <code>GET</code> request with a body. </p> <p> You can now build requests like this: </p> <p> <pre><span style="color:#2b91af;">HttpRequestMessage</span>&nbsp;<span style="font-weight:bold;color:#1f377f;">msg</span>&nbsp;= &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">new</span>&nbsp;<span style="color:#2b91af;">HttpPostMessageBuilder</span>( &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="font-weight:bold;color:#1f377f;">url</span>, &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">new</span> &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;{ &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;id&nbsp;=&nbsp;<span style="color:#2b91af;">Guid</span>.<span style="color:#74531f;">NewGuid</span>(), &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;date&nbsp;=&nbsp;<span style="color:#a31515;">&quot;2021-02-09&nbsp;19:15:00&quot;</span>, &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;name&nbsp;=&nbsp;<span style="color:#a31515;">&quot;Hervor&quot;</span>, &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;email&nbsp;=&nbsp;<span style="color:#a31515;">&quot;hervor@example.com&quot;</span>, &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;quantity&nbsp;=&nbsp;2 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;}) &nbsp;&nbsp;&nbsp;&nbsp;.<span style="font-weight:bold;color:#74531f;">WithAcceptHeader</span>(<span style="color:#a31515;">&quot;application/vnd.foo.bar+json&quot;</span>) &nbsp;&nbsp;&nbsp;&nbsp;.<span style="font-weight:bold;color:#74531f;">WithBearerToken</span>(<span style="color:#a31515;">&quot;cGxvZWg=&quot;</span>) &nbsp;&nbsp;&nbsp;&nbsp;.<span style="font-weight:bold;color:#74531f;">Build</span>();</pre> </p> <p> This builds a <code>POST</code> request with both a JSON body, an <code>Accept</code> header, and a <code>Bearer</code> token. </p> <h3 id="4104677292a94451a896e6bee22df93a"> Is polymorphism required? <a href="#4104677292a94451a896e6bee22df93a" title="permalink">#</a> </h3> <p> In <a href="/2020/02/10/builder-isomorphisms">my previous Builder article</a>, I struggled to produce a compelling example of a polymorphic Builder. It seems that I've now mended the situation. Or have I? </p> <p> Is the <code>IHttpRequestMessageBuilder</code> interface really required? </p> <p> Perhaps. It depends on your usage scenarios. I can actually delete the interface, and none of the usage examples I've shown here need change. </p> <p> On the other hand, had I written helper methods against the interface, obviously I couldn't just delete it. </p> <p> The bottom line is that polymorphism can be helpful, but it still strikes me as being non-essential to the Builder pattern. </p> <h3 id="07ed5f99efb549509a3af0c7b510553a"> Conclusion <a href="#07ed5f99efb549509a3af0c7b510553a" title="permalink">#</a> </h3> <p> In this article, I've shown how to guarantee that Builders never get into invalid states (according to the rules we've arbitrarily established). I used the common trick of <a href="/2011/05/30/DesignSmellDefaultConstructor">using constructors for object initialisation</a>. If a constructor completes without throwing an exception, we should expect the object to be in a valid state. The price I've paid for this design is some code duplication. </p> <p> You may have noticed that there's duplicated code between <code>HttpGetMessageBuilder</code> and <code>HttpPostMessageBuilder</code>. There are ways to address that concern, but I'll leave that as an exercise. </p> <p> For the sake of brevity, I've only shown examples written as Immutable Fluent Builders. You can refactor all the examples to mutable Fluent Builders or to the original Gang-of-Four Builder pattern. This, too, will remain an exercise for the interested reader. </p> </div> <div id="comments"> <hr> <h2 id="comments-header"> Comments </h2> <div class="comment" id="c1ea86ea39814f278e1a19f82b45622b"> <div class="comment-author"><a href="https://about.me/tysonwilliams">Tyson Williams</a></div> <div class="comment-content"> <blockquote> I'm happy to receive that question, because I struggled to find a compelling example of a Builder where polymorphism seems warranted. Here, it does. </blockquote> <p> I know of essentially one occurrence in .NET. Starting with <code>IEnumerable&lt;T&gt;</code>, calling either of the extension methods <a href="https://docs.microsoft.com/en-us/dotnet/api/system.linq.enumerable.orderby?view=netframework-4.8">OrderBy</a> or <a href="https://docs.microsoft.com/en-us/dotnet/api/system.linq.enumerable.orderbydescending?view=netframework-4.8">OrderByDescending</a> returns <code>IOrderedEnumerable&lt;T&gt;</code>, which has the additional extension methods <a href="https://docs.microsoft.com/en-us/dotnet/api/system.linq.enumerable.thenby?view=netframework-4.8">ThenBy</a> and <a href="https://docs.microsoft.com/en-us/dotnet/api/system.linq.enumerable.thenbydescending?view=netframework-4.8">ThenByDescending</a>. </p> <p> Quoting your recent <a href="https://blog.ploeh.dk/2020/02/10/builder-isomorphisms/">Builder isomorphisms</a> post. </p> <blockquote> The Builder pattern isn't useful only because it enables you to "separate the construction of a complex object from its representation." It's useful because it enables you to present an API that comes with good default behaviour, but which can be tweaked into multiple configurations. </blockquote> <p> I also find the builder pattern useful because its methods typically accept one argument one at a time. The builders in your recent posts are like this. The <code>OrderBy</code> and <code>ThenBy</code> methods and their <code>Descending</code> alternatives in .NET are also examples of this. </p> <p> However, some of the builders in your recent posts have some constructors that take multiple arguments. That is the situation that I was trying to address when <a href="https://blog.ploeh.dk/2017/09/11/test-data-without-builders/#b30ddcf557964bf2a7b63c0e247294e1">I asked</a> </p> <blockquote> Have you ever written a builder that accepted multiple arguments one at a time none of which have reasonable defaults? </blockquote> <p> This could be a <a href="https://blog.ploeh.dk/2020/01/13/on-doing-katas/">kata variation</a>: all public functions accept at most one argument. So <code>Foo(a, b)</code> would not be allowed but <code>Foo.WithA(a).WithB(b)</code> would. In an issue on this blog's GitHub, jaco0646 nicely summerized the reasoning that could lead to applying this design philosophy to production code by <a href="https://github.com/ploeh/ploeh.github.com/issues/539#issuecomment-585837934">saying</a> </p> <blockquote> Popular advice for a builder with required parameters is to put those in a constructor; but with more than a handful of required parameters, we return to the original problem: too much complexity in a constructor. </blockquote> <p> That comment by jaco0646 also supplied names by which this type of design is known. Those names (with the same links from the comment) are <a href="https://blog.jayway.com/2012/02/07/builder-pattern-with-a-twist/">Builder with a twist</a> or <a href="https://rdafbn.blogspot.com/2012/07/step-builder-pattern_28.html">Step Builder</a>. This is great, because I didn't have any good names. (I vaguely recall once thinking that another name was "progressive API" or "progressive fluent API", but now when I search for anything with "progressive", all I get are false positives for <a href="https://en.wikipedia.org/wiki/Progressive_web_application">progressive web app</a>. </p> <p> When replacing a multi-argument constructor with a sequence of function calls that each accept one argument, care must be taken to ensure that illegal state remains unrepresentable. My general impression is that many libraries have designed such APIs well. The two that I have enough experience with to recommend as good examples of this design are the <a href="https://www.learnentityframeworkcore.com/configuration/fluent-api">fluent configuration API in Entity Framework</a> and <a href="https://fluentassertions.com/introduction">Fluent Assertions</a>. As I <a href="https://blog.ploeh.dk/2017/09/11/test-data-without-builders/#be62acdf925841e09485f4253ab0c5fe">said before</a>, the most formal treatment I have seen about this type of API design was in <a href="https://blog.jooq.org/2012/01/05/the-java-fluent-api-designer-crash-course/">this blog post</a>. </p> </div> <div class="comment-date">2020-03-11 17:57 UTC</div> </div> <div class="comment" id="d31b6312b4204c7e8a1c047ed49cd4e6"> <div class="comment-author"><a href="/">Mark Seemann</a></div> <div class="comment-content"> <p> Tyson, apart from as <a href="/2020/01/13/on-doing-katas">a kata constraint</a>, is there any reason to prefer such a design? </p> <p> I'll be happy to give it a more formal treatment if there's reasonable scenario. Can you think of one? </p> <p> I don't find the motivation given by jaco0646 convincing. If you have more than a handful of required parameters, I agree that that's an issue with complexity, but I don't agree that the solution is to add more complexity on top of it. Builders add complexity. </p> <p> At a glance, though, with something like <code>Foo.WithA(a).WithB(b)</code> it seems to me that you're essentially reinventing <a href="https://en.wikipedia.org/wiki/Currying">currying</a> the hard way around. </p> <p> Related to the overall Builder discussion (but not to currying) you may also find <a href="https://blog.frankel.ch/builder-pattern-finite-state-machine">this article</a> and <a href="https://stackoverflow.com/a/2267467/126014">this Stack Overflow answer</a> interesting. </p> </div> <div class="comment-date">2020-03-13 6:19 UTC</div> </div> <div class="comment" id="b30263d2a8e440e7b89dc23bd9d8d3c6"> <div class="comment-author"><a href="https://about.me/tysonwilliams">Tyson Williams</a></div> <div class="comment-content"> <blockquote> ...is there any reason to prefer such a design? </blockquote> <p> Yes. Just like you, I want to write <a href="https://blog.ploeh.dk/2019/11/04/the-80-24-rule/">small functions</a>. In that post, you suggest an arbitrary maximum of 24 lines. One thing I find fascinating about functional programming is how useful the common functions are (such as <code>map</code>) and how they are implemented in only a few lines (often just one line). There is a correlation between the number of function arguments and the length of the function. So to help control the length of a function, it helps to control the number of arguments to the functions. I think Robert Martin has a similar argument. When talking about functions in chapter 3 of <a href="">Clean Code</a>, his first section is about writing small functions and a later section about function arguments open by saying </p> <blockquote> The ideal number of arguments for a function is zero (niladic). Next comes one (monadic), followed closely by two (dyadic). Three arguments (triadic) should be avoided where possible. More than three (polyadic) requires very special justification--and then shouldn't be used anyway. </blockquote> <p> In the C# code <code>a.Foo(b)</code>, <code>Foo</code> is an instance method that "feels" like it only has one argument. In reality, its two inputs are <code>a</code> and <code>b</code>, and that code uses infix notation. The situation is similar in the F# code <code>a |&gt; List.map f</code>. The function <code>List.map</code> (as well as the operator <code>|&gt;</code>) has two arguments and is applied using infix notation. I try to avoid creating functions that have more than two arguments. </p> <blockquote> I don't find the motivation given by jaco0646 convincing. If you have more than a handful of required parameters, I agree that that's an issue with complexity, but I don't agree that the solution is to add more complexity on top of it. Builders add complexity. </blockquote> <p> I am not sure how you are measuring complexity. I like to think that there are two types of complexity: local and global. For the sake of argument, let's suppose <ol> <li>that local complexity is only defined for a function and is the number of arguments of that function and <li>that global complexity is only defined for a entire program and is the number of lines in the program. </ol> I would argue that many required arguments is an issue of local complexity. We can decrease the local complexity at the expense of increasing the global complexity by replacing one function accepting many arguments with several functions accepting fewer arguments. I like to express this idea with the phrase "minimize the maximum (local) complexity". </p> <blockquote> ...you may also find <a href="https://blog.frankel.ch/builder-pattern-finite-state-machine">this article</a> [titled The Builder pattern is a finite state machine]...interesting. </blockquote> <p> Indeed, that is a nice article. Finite state machines/automata (both deterministic and nondeterministic) have the same expressiveness as regular expressions. </p> <blockquote> At a glance, though, with something like <code>Foo.WithA(a).WithB(b)</code> it seems to me that you're essentially reinventing <a href="https://en.wikipedia.org/wiki/Currying">currying</a> the hard way around. </blockquote> <p> It is. As a regular expression, it would be something like <code>AB</code>. I was just trying to give a simple example. The point of the article you shared is that the builder pattern is much more expressive. I have previously shared a <a href="https://blog.jooq.org/2012/01/05/the-java-fluent-api-designer-crash-course/">similar article</a>, but I like yours better. Thanks :) </p> <blockquote> ...you may also find...<a href="https://stackoverflow.com/a/2267467/126014">this Stack Overflow answer</a> interesting. </blockquote> <p> Wow. That is extremely cleaver! I would never thought of that. Thank you very much for sharing. </p> <blockquote> I'll be happy to give it a more formal treatment if there's reasonable scenario. Can you think of one? </blockquote> <p> As I said above, I often try to find ways to minimize the maximum complexity of the code that I write. In this case, the reason that I <a href="https://blog.ploeh.dk/2017/09/11/test-data-without-builders/#cb79773e74624514a1801af115f52f6b">originally asked you about the builder pattern</a> is that I was trying to improve the API for creating a binding in <a href="https://github.com/elmish/Elmish.WPF">Elmish.WPF</a>. The tutorial has a great <a href="https://github.com/elmish/Elmish.WPF/blob/master/TUTORIAL.md#the-elmishwpf-bindings">section about bindings</a>. There are many binding types, and each has multiple ways to create it. Most arguments are required and some are optional. </p> <p> <a href="https://github.com/elmish/Elmish.WPF/issues/87">Here</a> is a closed issue that was created during the transition to the current binding API, which uses method overloading. In an attempt to come up with a better API, <a href="https://github.com/elmish/Elmish.WPF/issues/87#issuecomment-530962855">I suggested</a> that we could use your suggestion to <a href="https://blog.ploeh.dk/2013/10/21/replace-overloading-with-discriminated-unions/">replace overloading with discriminated unions</a>, but my co-maintainer wasn't convinced that it would be better. </p> <p> Three days later, I increased the expressiveness of our bindings in <a href="https://github.com/elmish/Elmish.WPF/pull/118/files">this pull request</a>. Conceptually it was a small change; I added a single optional argument. For a regular expression, such a change is trivial. However, in my case it was a delta of +300 lines of mind-numbingly boring code. </p> <p> I agree with my co-maintainer that the current binding API is pretty good for the user. On the implementation side though, I am not satisfied. I want to find something better without sacrificing (and maybe even improving) the user's experience. </p> </div> <div class="comment-date">2020-03-16 04:03 UTC</div> </div> </div><hr> This blog is totally free, but if you like it, please consider <a href="https://blog.ploeh.dk/support">supporting it</a>. Mark Seemann https://blog.ploeh.dk/2020/03/09/polymorphic-builder Impureim sandwich https://blog.ploeh.dk/2020/03/02/impureim-sandwich/ Mon, 02 Mar 2020 07:03:00 UTC <div id="post"> <p> <em>Pronounced 'impurium sandwich'.</em> </p> <p> <a href="/2017/01/27/from-dependency-injection-to-dependency-rejection">Since January 2017</a> I've been singing the praise of the <em>impure/pure/impure</em> sandwich, but I've never published an article that defines the term. I intend this article to remedy the situation. </p> <h3 id="b1755f32e36d4a07b336d1b8fdc1b227"> Functional architecture <a href="#b1755f32e36d4a07b336d1b8fdc1b227" title="permalink">#</a> </h3> <p> In <a href="/2018/11/19/functional-architecture-a-definition">a functional architecture</a> <a href="https://en.wikipedia.org/wiki/Pure_function">pure functions</a> can't call impure actions. On the other hand, as <a href="https://en.wikipedia.org/wiki/Simon_Peyton_Jones">Simon Peyton Jones</a> observed in a lecture, <em>observing the result of pure computation is a side-effect</em>. In practical terms, <em>executing</em> a pure function is also impure, because it happens non-deterministically. Thus, even for a piece of software written in a functional style, the entry point must be impure. </p> <p> While pure functions can't call impure actions, there's no rule to prevent the obverse. Impure actions <em>can</em> call pure functions. </p> <p> Therefore, the best we can ever hope to achieve is an impure entry point that calls pure code and impurely reports the result from the pure function. </p> <p> <img src="/content/binary/impure-pure-impure-sandwich-box.png" alt="A box with a thin red slice on top, a thick green middle, and a thin red slice at the bottom."> </p> <p> The flow of code here goes from top to bottom: <ol> <li>Gather data from impure sources.</li> <li>Call a pure function with that data.</li> <li>Change state (including user interface) based on return value from pure function.</li> </ol> This is the <em>impure/pure/impure</em> sandwich. </p> <h3 id="c568a515c5a04024832079e491432bc4"> Metaphor <a href="#c568a515c5a04024832079e491432bc4" title="permalink">#</a> </h3> <p> The reason I call this a <em>sandwich</em> is that I think that it <em>looks</em> like a sandwich, albeit, perhaps, a rather tall one. According to the <a href="https://en.wikipedia.org/wiki/Sandwich">myth of the sandwich</a>, the <a href="https://en.wikipedia.org/wiki/John_Montagu,_4th_Earl_of_Sandwich">4th Earl of Sandwich</a> was a notorious gambler. While playing cards, he'd order two slices of bread with meat in between. This enabled him to keep playing without greasing the cards. His compatriots would order <em>the same as Sandwich</em>, or simply <em>a Sandwich</em>, and the name stuck. </p> <p> I like the sandwich as a metaphor. The bread is an <em>affordance</em>, in <a href="http://amzn.to/1NVqXQH">the spirit of Donald A. Norman</a>. It enables you to handle the meat without getting your fingers greased. In the same way, I think, impure actions enable you to handle a pure function. They let you invoke and observe the result of it. </p> <h3 id="0aa40b6f0f7c4648ac9a83f8fe2ab449"> Examples <a href="#0aa40b6f0f7c4648ac9a83f8fe2ab449" title="permalink">#</a> </h3> <p> One of the cleanest examples of an <em>impureim sandwich</em> remains <a href="/2017/02/02/dependency-rejection">my original article</a>: </p> <p> <pre><span style="color:#600277;">tryAcceptComposition</span>&nbsp;::&nbsp;<span style="color:blue;">Reservation</span>&nbsp;<span style="color:blue;">-&gt;</span>&nbsp;IO&nbsp;(Maybe&nbsp;Int) tryAcceptComposition&nbsp;reservation&nbsp;<span style="color:#666666;">=</span>&nbsp;runMaybeT&nbsp;<span style="color:#666666;">$</span> <span style="background-color: lightsalmon;">&nbsp;&nbsp;liftIO&nbsp;(<span style="color:#dd0000;">DB</span><span style="color:#666666;">.</span>readReservations&nbsp;connectionString&nbsp;<span style="color:#666666;">$</span>&nbsp;date&nbsp;reservation)</span> <span style="background-color: palegreen;">&nbsp;&nbsp;<span style="color:#666666;">&gt;&gt;=</span>&nbsp;<span style="color:#dd0000;">MaybeT</span>&nbsp;<span style="color:#666666;">.</span>&nbsp;return&nbsp;<span style="color:#666666;">.</span>&nbsp;flip&nbsp;(tryAccept&nbsp;<span style="color:#09885a;">10</span>)&nbsp;reservation</span> <span style="background-color: lightsalmon;">&nbsp;&nbsp;<span style="color:#666666;">&gt;&gt;=</span>&nbsp;liftIO&nbsp;<span style="color:#666666;">.</span>&nbsp;<span style="color:#dd0000;">DB</span><span style="color:#666666;">.</span>createReservation&nbsp;connectionString</span></pre> </p> <p> I've here repeated the code, but coloured the background of the impure, pure, and impure parts of the sandwich. </p> <p> I've shown plenty of other examples of this sandwich architecture, recently, for example, while <a href="/2019/12/02/refactoring-registration-flow-to-functional-architecture">refactoring a registration flow</a> in <a href="https://fsharp.org">F#</a>: </p> <p> <pre><span style="color:blue;">let</span>&nbsp;sut&nbsp;pid&nbsp;r&nbsp;=&nbsp;async&nbsp;{ <span style="background-color: lightsalmon;">&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">let!</span>&nbsp;validityOfProof&nbsp;=&nbsp;AsyncOption.traverse&nbsp;(twoFA.VerifyProof&nbsp;r.Mobile)&nbsp;pid</span> <span style="background-color: palegreen;">&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">let</span>&nbsp;decision&nbsp;=&nbsp;completeRegistrationWorkflow&nbsp;r&nbsp;validityOfProof</span> <span style="background-color: lightsalmon;">&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">return!</span> &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;decision &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;|&gt;&nbsp;AsyncResult.traverseBoth&nbsp;db.CompleteRegistration&nbsp;twoFA.CreateProof &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;|&gt;&nbsp;AsyncResult.cata&nbsp;(<span style="color:blue;">fun</span>&nbsp;()&nbsp;<span style="color:blue;">-&gt;</span>&nbsp;RegistrationCompleted)&nbsp;ProofRequired</span> &nbsp;&nbsp;&nbsp;&nbsp;}</pre> </p> <p> This last example looks as though the bottom part of the sandwich is larger then the rest of the composition. This can sometimes happen (and, in fact, last line of code is also pure). On the other hand, the pure part in the middle will typically <a href="/2019/12/09/put-cyclomatic-complexity-to-good-use">look like just a single line of code, even when the invoked function performs work of significant complexity</a>. </p> <p> The sandwich is a pattern independent of language. You can also <a href="/2019/02/11/asynchronous-injection">apply it in C#</a>: </p> <p> <pre><span style="color:blue;">public</span>&nbsp;<span style="color:blue;">async</span>&nbsp;<span style="color:#2b91af;">Task</span>&lt;<span style="color:#2b91af;">IActionResult</span>&gt;&nbsp;Post(<span style="color:#2b91af;">Reservation</span>&nbsp;reservation) { <span style="background-color: lightsalmon;">&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">return</span>&nbsp;<span style="color:blue;">await</span>&nbsp;Repository.ReadReservations(reservation.Date)</span> <span style="background-color: palegreen;">&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;.Select(rs&nbsp;=&gt;&nbsp;maîtreD.TryAccept(rs,&nbsp;reservation))</span> <span style="background-color: lightsalmon;">&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;.SelectMany(m&nbsp;=&gt;&nbsp;m.Traverse(Repository.Create)) &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;.Match(InternalServerError(<span style="color:#a31515;">&quot;Table&nbsp;unavailable&quot;</span>),&nbsp;Ok);</span> }</pre> </p> <p> Like in the previous F# example, the final <code>Match</code> is most likely pure. In practice, <a href="/2020/02/24/discerning-and-maintaining-purity">you may not know</a>, because a method like <code>InternalServerError</code> or <code>Ok</code> is an inherited base class method. Regardless, I don't think that it's architecturally important, because what's going on there is rather trivial. </p> <h3 id="de8d05083dcd4dedae2b8b714702cc44"> Naming <a href="#de8d05083dcd4dedae2b8b714702cc44" title="permalink">#</a> </h3> <p> Since the metaphor occurred to me, I've been looking for a better name. The term <em>impure/pure/impure sandwich</em> seems too inconvenient, but nevertheless, people seem to have picked it up. </p> <p> I want a more distinct name, but have had trouble coming up with one. I've been toying with various abbreviations of <em>impure</em> and <em>pure</em>, but have finally settled on <em>impureim sandwich</em>. It's a contraction of <strong>im</strong>pure/<strong>pure</strong>/<strong>im</strong>pure. </p> <p> Why this particular contraction? </p> <p> I've played with lots of alternatives: <ul> <li>impureim: <strong>im</strong>pure/<strong>pure</strong>/<strong>im</strong>pure</li> <li>ipi: <strong>i</strong>mpure/<strong>p</strong>ure/<strong>i</strong>mpure</li> <li>impi: <strong>im</strong>pure/<strong>p</strong>ure/<strong>i</strong>mpure</li> <li>impim: <strong>im</strong>pure/<strong>p</strong>ure/<strong>im</strong>pure</li> </ul> and so on... </p> <p> I like <em>impureim</em> because the only <a href="https://en.wikipedia.org/wiki/Anagram">anagram</a> that I'm aware of is <em>imperium</em>. I therefore suggest that you pronounce it <em>impurium sandwich</em>. That'll work as a <a href="https://martinfowler.com/bliki/Neologism.html">neologic</a> <a href="https://en.wikipedia.org/wiki/Shibboleth">shibboleth</a>. </p> <h3 id="df74d63c013646aa9355b95e74fc3edc"> Summary <a href="#df74d63c013646aa9355b95e74fc3edc" title="permalink">#</a> </h3> <p> Functional architecture prohibits pure functions from invoking impure actions. On the other hand, a pure function is useless if you can't observe its result. A functional architecture, thus, must have an impure entry point that invokes a pure function and uses another impure action to act on the result. </p> <p> I suggest that we call such an <em>impure/pure/impure</em> interaction an <em>impureim sandwich</em>, and that we pronounce it an <em>impurium sandwich</em>. </p> </div> <div id="comments"> <hr> <h2 id="comments-header"> Comments </h2> <div class="comment" id="4d71311250a54b1ca558a8469acdf445"> <div class="comment-author"><a href="https://massivepixel.co">Toni Petrina</a></div> <div class="comment-content"> <p> I find this example slightly simplistic. What happens when the logic has to do cascade reads/validations as it is typically done? Then you get impureimpureim...? Or do you fetch all data upfront even though it might be...irrelevant? For example, you want to send a comment to a blog post, but that post has forbidden new comments? Wouldn't you want to validate first and then fetch blog post if necessary? </p> </div> <div class="comment-date">2020-03-02 07:45 UTC</div> </div> <div class="comment" id="3cfe29c36690499cab429040260d818e"> <div class="comment-author"><a href="/">Mark Seemann</a></div> <div class="comment-content"> <p> Toni, thank you for writing. As I write <a href="/2019/12/02/refactoring-registration-flow-to-functional-architecture">in another article</a>, <blockquote> <p> "It's my experience that it's conspicuously often possible to implement an impure/pure/impure sandwich." </p> </blockquote> On the other hand, I never claimed that you can <em>always</em> do this. The impureim sandwich is a design pattern. It gives a name to a <a href="https://en.wikipedia.org/wiki/Software_design_pattern">general, reusable solution to a commonly occurring problem within a given context</a>. </p> <p> In cases where you can't apply the impureim sandwich pattern, <a href="/2017/07/10/pure-interactions">other patterns are available</a>. </p> </div> <div class="comment-date">2020-03-02 8:54 UTC</div> </div> </div> <hr> This blog is totally free, but if you like it, please consider <a href="https://blog.ploeh.dk/support">supporting it</a>. Mark Seemann https://blog.ploeh.dk/2020/03/02/impureim-sandwich Discerning and maintaining purity https://blog.ploeh.dk/2020/02/24/discerning-and-maintaining-purity/ Mon, 24 Feb 2020 07:31:00 UTC <div id="post"> <p> <em>Functional programming depends on referential transparency, but identifying and keeping functions pure requires deliberate attention.</em> </p> <p> <a href="https://en.wikipedia.org/wiki/Referential_transparency">Referential transparency</a> is the essence of functional programming. Most other traits that people associate with functional programming emerge from it: immutability, recursion, <a href="https://en.wikipedia.org/wiki/Higher-order_function">higher-order functions</a>, <a href="/2018/03/22/functors">functors</a> and monads, etcetera. </p> <p> To summarise, a <a href="https://en.wikipedia.org/wiki/Pure_function">pure function</a> has to obey two rules: <ul> <li>The same input always produces the same output.</li> <li>Calling it causes no side effects.</li> </ul> While those rules are easy to understand and remember, in practice they're harder to follow than most people realise. </p> <h3 id="8435839fae0b484399d4ada9f06e695d"> Lack of abstraction <a href="#8435839fae0b484399d4ada9f06e695d" title="permalink">#</a> </h3> <p> Mainstream programming languages don't distinguish between pure functions and impure actions. I'll use C# for examples, but you can draw the same conclusions for Java, C, C++, Visual Basic .NET and so on - even for <a href="https://fsharp.org">F#</a> and <a href="https://clojure.org">Clojure</a>. </p> <p> Consider this line of code: </p> <p> <pre><span style="color:blue;">string</span>&nbsp;<span style="font-weight:bold;color:#1f377f;">validationMsg</span>&nbsp;=&nbsp;<span style="color:#2b91af;">Validator</span>.<span style="color:#74531f;">Validate</span>(<span style="font-weight:bold;color:#1f377f;">dto</span>);</pre> </p> <p> Is <code>Validate</code> a pure function? </p> <p> You might want to look at the method signature before you answer: </p> <p> <pre><span style="color:blue;">public</span>&nbsp;<span style="color:blue;">static</span>&nbsp;<span style="color:blue;">string</span>&nbsp;<span style="color:#74531f;">Validate</span>(<span style="color:#2b91af;">ReservationDto</span>&nbsp;<span style="font-weight:bold;color:#1f377f;">dto</span>)</pre> </p> <p> This is, unfortunately, not helpful. Will <code>Validate</code> always return the same <code>string</code> for the same <code>dto</code>? Can we guarantee that there's no side effects? </p> <p> You can't answer these questions only by examining the method signature. You'll have to go and <em>read</em> the code. </p> <p> This breaks <a href="/encapsulation-and-solid">encapsulation</a>. It ruins abstraction. It makes code harder to maintain. </p> <p> I can't stress this enough. This is what I've attempted to describe in my <a href="https://cleancoders.com/episode/humane-code-real-episode-1/show">Humane Code</a> video. We waste significant time <em>reading</em> existing code. Mostly because it's difficult to understand. It doesn't fit in our brains. </p> <p> <a href="http://amzn.to/19W4JHk">Agile Principles, Patterns, and Practices</a> defines an <em>abstraction</em> as <blockquote> <p> "the amplification of the essential and the elimination of the irrelevant" </p> <footer><cite>Robert C. Martin</cite></footer> </blockquote> This fits with the definition of encapsulation from <a href="http://amzn.to/1claOin">Object-Oriented Software Construction</a>. You should be able to interact with an object without knowledge of its implementation details. </p> <p> When you have to read the code of a method, it indicates a lack of abstraction and encapsulation. Unfortunately, that's the state of affairs when it comes to referential transparency in mainstream programming languages. </p> <h3 id="eabec7ed53c3482d86d1e4968101741f"> Manual analysis <a href="#eabec7ed53c3482d86d1e4968101741f" title="permalink">#</a> </h3> <p> If you read the source code of the <code>Validate</code> method, however, it's easy to figure out whether it's pure: </p> <p> <pre><span style="color:blue;">public</span>&nbsp;<span style="color:blue;">static</span>&nbsp;<span style="color:blue;">string</span>&nbsp;<span style="color:#74531f;">Validate</span>(<span style="color:#2b91af;">ReservationDto</span>&nbsp;<span style="font-weight:bold;color:#1f377f;">dto</span>) { &nbsp;&nbsp;&nbsp;&nbsp;<span style="font-weight:bold;color:#8f08c4;">if</span>&nbsp;(!<span style="color:#2b91af;">DateTime</span>.<span style="color:#74531f;">TryParse</span>(<span style="font-weight:bold;color:#1f377f;">dto</span>.Date,&nbsp;<span style="color:blue;">out</span>&nbsp;<span style="color:blue;">var</span>&nbsp;<span style="color:blue;">_</span>)) &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="font-weight:bold;color:#8f08c4;">return</span>&nbsp;<span style="color:#a31515;">$&quot;Invalid&nbsp;date:&nbsp;</span>{<span style="font-weight:bold;color:#1f377f;">dto</span>.Date}<span style="color:#a31515;">.&quot;</span>; &nbsp;&nbsp;&nbsp;&nbsp;<span style="font-weight:bold;color:#8f08c4;">return</span>&nbsp;<span style="color:#a31515;">&quot;&quot;</span>; }</pre> </p> <p> Is the method deterministic? It seems like it. In fact, in order to answer that question, you need to know if <code>DateTime.TryParse</code> is deterministic. Assume that it is. Apart from the <code>TryParse</code> call, you can easily reason about the rest of this method. There's no randomness or other sources of non-deterministic behaviour in the method, so it seems reasonable to conclude that it's deterministic. </p> <p> Does the method produce side effects? Again, you have to know about the behaviour of <code>DateTime.TryParse</code>, but I think it's safe to conclude that there's no side effects. </p> <p> In other words, <code>Validate</code> is a pure function. </p> <h3 id="58667892c58f45ebac8e50946a9f1f2a"> Testability <a href="#58667892c58f45ebac8e50946a9f1f2a" title="permalink">#</a> </h3> <p> Pure functions are <a href="/2015/05/07/functional-design-is-intrinsically-testable">intrinsically testable</a> because they depend exclusively on their input. </p> <p> <pre>[<span style="color:#2b91af;">Fact</span>] <span style="color:blue;">public</span>&nbsp;<span style="color:blue;">void</span>&nbsp;<span style="font-weight:bold;color:#74531f;">ValidDate</span>() { &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">var</span>&nbsp;<span style="font-weight:bold;color:#1f377f;">dto</span>&nbsp;=&nbsp;<span style="color:blue;">new</span>&nbsp;<span style="color:#2b91af;">ReservationDto</span>&nbsp;{&nbsp;Date&nbsp;=&nbsp;<span style="color:#a31515;">&quot;2021-12-21&nbsp;19:00&quot;</span>,&nbsp;Quantity&nbsp;=&nbsp;2&nbsp;}; &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">var</span>&nbsp;<span style="font-weight:bold;color:#1f377f;">actual</span>&nbsp;=&nbsp;<span style="color:#2b91af;">Validator</span>.<span style="color:#74531f;">Validate</span>(<span style="font-weight:bold;color:#1f377f;">dto</span>); &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:#2b91af;">Assert</span>.<span style="color:#74531f;">Empty</span>(<span style="font-weight:bold;color:#1f377f;">actual</span>); }</pre> </p> <p> This unit test creates a reservation <a href="https://en.wikipedia.org/wiki/Data_transfer_object">Data Transfer Object</a> (DTO) with a valid date string and a positive quantity. There's no error message to produce for a valid DTO. The test asserts that the error message is empty. It passes. </p> <p> You can with similar ease write a test that verifies what happens if you supply an invalid <code>Date</code> string. </p> <h3 id="de8e9b17b8c14448a76165337ebdc410"> Maintaining purity <a href="#de8e9b17b8c14448a76165337ebdc410" title="permalink">#</a> </h3> <p> The problem with manual analysis of purity is that any conclusion you reach only lasts until someone edits the code. Every time the code changes, you must re-evaluate. </p> <p> Imagine that you need to add a new validation rule. The system shouldn't accept reservations in the past, so you edit the <code>Validate</code> method: </p> <p> <pre><span style="color:blue;">public</span>&nbsp;<span style="color:blue;">static</span>&nbsp;<span style="color:blue;">string</span>&nbsp;<span style="color:#74531f;">Validate</span>(<span style="color:#2b91af;">ReservationDto</span>&nbsp;<span style="font-weight:bold;color:#1f377f;">dto</span>) { &nbsp;&nbsp;&nbsp;&nbsp;<span style="font-weight:bold;color:#8f08c4;">if</span>&nbsp;(!<span style="color:#2b91af;">DateTime</span>.<span style="color:#74531f;">TryParse</span>(<span style="font-weight:bold;color:#1f377f;">dto</span>.Date,&nbsp;<span style="color:blue;">out</span>&nbsp;<span style="color:blue;">var</span>&nbsp;<span style="font-weight:bold;color:#1f377f;">date</span>)) &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="font-weight:bold;color:#8f08c4;">return</span>&nbsp;<span style="color:#a31515;">$&quot;Invalid date: </span>{<span style="font-weight:bold;color:#1f377f;">dto</span>.Date}<span style="color:#a31515;">.&quot;</span>; &nbsp;&nbsp;&nbsp;&nbsp;<span style="font-weight:bold;color:#8f08c4;">if</span>&nbsp;(<span style="font-weight:bold;color:#1f377f;">date</span>&nbsp;<span style="font-weight:bold;color:#74531f;">&lt;</span>&nbsp;<span style="color:#2b91af;">DateTime</span>.Now) &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="font-weight:bold;color:#8f08c4;">return</span>&nbsp;<span style="color:#a31515;">$&quot;Invalid date: </span>{<span style="font-weight:bold;color:#1f377f;">dto</span>.Date}<span style="color:#a31515;">.&quot;</span>; &nbsp;&nbsp;&nbsp;&nbsp;<span style="font-weight:bold;color:#8f08c4;">return</span>&nbsp;<span style="color:#a31515;">&quot;&quot;</span>; }</pre> </p> <p> Is the method still pure? No, it's not. It's now non-deterministic. One way to observe this is to let time pass. Assume that you wrote the above unit test well before December 21, 2021. That test still passes when you make the change, but months go by. One day (on December 21, 2021 at 19:00) the test starts failing. No code changed, but now you have a failing test. </p> <p> I've made sure that the examples in this article are simple, so that they're easy to follow. This could mislead you to think that the shift from referential transparency to impurity isn't such a big deal. After all, the test is easy to read, and it's clear why it starts failing. </p> <p> Imagine, however, that the code is as complex as the code base you work with professionally. A subtle change to a method deep in the bowels of a system can have profound impact on the entire architecture. You thought that you had a <a href="/2018/11/19/functional-architecture-a-definition">functional architecture</a>, but you probably don't. </p> <p> Notice that no types changed. The method signature remains the same. It's surprisingly difficult to maintain purity in a code base, even if you explicitly set out to do so. There's no <a href="https://en.wikipedia.org/wiki/Poka-yoke">poka-yoke</a> here; constant vigilance is required. </p> <h3 id="dcf2b00c3b4f49d192a10f0cb269d427"> Automation attempts <a href="#dcf2b00c3b4f49d192a10f0cb269d427" title="permalink">#</a> </h3> <p> When I explain these issues, people typically suggest some sort of annotation mechanism. Couldn't we use attributes to identify pure functions? Perhaps like this: </p> <p> <pre>[<span style="color:#2b91af;">Pure</span>] <span style="color:blue;">public</span>&nbsp;<span style="color:blue;">static</span>&nbsp;<span style="color:blue;">string</span>&nbsp;<span style="color:#74531f;">Validate</span>(<span style="color:#2b91af;">ReservationDto</span>&nbsp;<span style="font-weight:bold;color:#1f377f;">dto</span>)</pre> </p> <p> This doesn't solve the problem, though, because this still still compiles: </p> <p> <pre>[<span style="color:#2b91af;">Pure</span>] <span style="color:blue;">public</span>&nbsp;<span style="color:blue;">static</span>&nbsp;<span style="color:blue;">string</span>&nbsp;<span style="color:#74531f;">Validate</span>(<span style="color:#2b91af;">ReservationDto</span>&nbsp;<span style="font-weight:bold;color:#1f377f;">dto</span>) { &nbsp;&nbsp;&nbsp;&nbsp;<span style="font-weight:bold;color:#8f08c4;">if</span>&nbsp;(!<span style="color:#2b91af;">DateTime</span>.<span style="color:#74531f;">TryParse</span>(<span style="font-weight:bold;color:#1f377f;">dto</span>.Date,&nbsp;<span style="color:blue;">out</span>&nbsp;<span style="color:blue;">var</span>&nbsp;<span style="font-weight:bold;color:#1f377f;">date</span>)) &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="font-weight:bold;color:#8f08c4;">return</span>&nbsp;<span style="color:#a31515;">$&quot;Invalid date: </span>{<span style="font-weight:bold;color:#1f377f;">dto</span>.Date}<span style="color:#a31515;">.&quot;</span>; &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; &nbsp;&nbsp;&nbsp;&nbsp;<span style="font-weight:bold;color:#8f08c4;">if</span>&nbsp;(<span style="font-weight:bold;color:#1f377f;">date</span>&nbsp;<span style="font-weight:bold;color:#74531f;">&lt;</span>&nbsp;<span style="color:#2b91af;">DateTime</span>.Now) &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="font-weight:bold;color:#8f08c4;">return</span>&nbsp;<span style="color:#a31515;">$&quot;Invalid date: </span>{<span style="font-weight:bold;color:#1f377f;">dto</span>.Date}<span style="color:#a31515;">.&quot;</span>; &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; &nbsp;&nbsp;&nbsp;&nbsp;<span style="font-weight:bold;color:#8f08c4;">return</span>&nbsp;<span style="color:#a31515;">&quot;&quot;</span>; }</pre> </p> <p> That's an impure action annotated with the <code>[Pure]</code> attribute. It still compiles and passes all tests (if you run them before December 21, 2021). The annotation is a lie. </p> <p> As I've already implied, you also have the compound problem that you need to know the purity (or lack thereof) of all APIs from the base library or third-party libraries. Can you be sure that no pure function becomes impure when you update a library from version 2.3.1 to 2.3.2? </p> <p> I'm not aware of any robust automated way to verify referential transparency in mainstream programming languages. </p> <h3 id="5413987a6af14316aee1b1de82aee73d"> Language support <a href="#5413987a6af14316aee1b1de82aee73d" title="permalink">#</a> </h3> <p> While no mainstream languages distinguish between pure functions and impure actions, there are languages that do. The most famous of these is <a href="https://www.haskell.org">Haskell</a>, but other examples include <a href="http://www.purescript.org">PureScript</a> and <a href="https://www.idris-lang.org">Idris</a>. </p> <p> I find Haskell useful for exactly that reason. The compiler enforces the functional interaction law. You can't call impure actions from pure functions. Thus, you wouldn't be able to make a change to a function like <code>Validate</code> without changing its type. That would break most consuming code, which is a good thing. </p> <p> You could write an equivalent to the original, pure version of <code>Validate</code> in Haskell like this: </p> <p> <pre><span style="color:#2b91af;">validateReservation</span>&nbsp;::&nbsp;<span style="color:blue;">ReservationDTO</span>&nbsp;<span style="color:blue;">-&gt;</span>&nbsp;<span style="color:#2b91af;">Either</span>&nbsp;<span style="color:#2b91af;">String</span>&nbsp;<span style="color:blue;">ReservationDTO</span> validateReservation&nbsp;r@(ReservationDTO&nbsp;_&nbsp;d&nbsp;_&nbsp;_&nbsp;_)&nbsp;= &nbsp;&nbsp;<span style="color:blue;">case</span>&nbsp;readMaybe&nbsp;d&nbsp;<span style="color:blue;">of</span> &nbsp;&nbsp;&nbsp;&nbsp;Nothing&nbsp;-&gt;&nbsp;Left&nbsp;$&nbsp;<span style="color:#a31515;">&quot;Invalid&nbsp;date:&nbsp;&quot;</span>&nbsp;++&nbsp;d&nbsp;++&nbsp;<span style="color:#a31515;">&quot;.&quot;</span> &nbsp;&nbsp;&nbsp;&nbsp;Just&nbsp;(_&nbsp;::&nbsp;LocalTime)&nbsp;-&gt;&nbsp;Right&nbsp;r</pre> </p> <p> This is a pure function, because all Haskell functions are pure by default. </p> <p> You can change it to also check for reservations in the past, but only if you also change the type: </p> <p> <pre><span style="color:#2b91af;">validateReservation</span>&nbsp;::&nbsp;<span style="color:blue;">ReservationDTO</span>&nbsp;<span style="color:blue;">-&gt;</span>&nbsp;<span style="color:#2b91af;">IO</span>&nbsp;(<span style="color:#2b91af;">Either</span>&nbsp;<span style="color:#2b91af;">String</span>&nbsp;<span style="color:blue;">ReservationDTO</span>) validateReservation&nbsp;r@(ReservationDTO&nbsp;_&nbsp;d&nbsp;_&nbsp;_&nbsp;_)&nbsp;= &nbsp;&nbsp;<span style="color:blue;">case</span>&nbsp;readMaybe&nbsp;d&nbsp;<span style="color:blue;">of</span> &nbsp;&nbsp;&nbsp;&nbsp;Nothing&nbsp;-&gt;&nbsp;<span style="color:blue;">return</span>&nbsp;$&nbsp;Left&nbsp;$&nbsp;<span style="color:#a31515;">&quot;Invalid&nbsp;date:&nbsp;&quot;</span>&nbsp;++&nbsp;d&nbsp;++&nbsp;<span style="color:#a31515;">&quot;.&quot;</span> &nbsp;&nbsp;&nbsp;&nbsp;Just&nbsp;date&nbsp;-&gt;&nbsp;<span style="color:blue;">do</span> &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;utcNow&nbsp;&lt;-&nbsp;getCurrentTime &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;tz&nbsp;&lt;-&nbsp;getCurrentTimeZone &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">let</span>&nbsp;now&nbsp;=&nbsp;utcToLocalTime&nbsp;tz&nbsp;utcNow &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">if</span>&nbsp;date&nbsp;&lt;&nbsp;now &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">then</span>&nbsp;<span style="color:blue;">return</span>&nbsp;$&nbsp;Left&nbsp;$&nbsp;<span style="color:#a31515;">&quot;Invalid&nbsp;date:&nbsp;&quot;</span>&nbsp;++&nbsp;d&nbsp;++&nbsp;<span style="color:#a31515;">&quot;.&quot;</span> &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">else</span>&nbsp;<span style="color:blue;">return</span>&nbsp;$&nbsp;Right&nbsp;r</pre> </p> <p> Notice that I had to change the return type from <code>Either String ReservationDTO</code> to <code>IO (Either String ReservationDTO)</code>. The presence of <code>IO</code> marks the 'function' as impure. If I hadn't changed the type, the code simply wouldn't have compiled, because <code>getCurrentTime</code> and <code>getCurrentTimeZone</code> are impure actions. These types ripple through entire code bases, enforcing the functional interaction law at every level of the code base. </p> <h3 id="938b7dc2db644b6b94f6a484d65bb320"> Pure date validation <a href="#938b7dc2db644b6b94f6a484d65bb320" title="permalink">#</a> </h3> <p> How would you validate, then, that a reservation is in the future? In Haskell, like this: </p> <p> <pre><span style="color:#2b91af;">validateReservation</span>&nbsp;::&nbsp;<span style="color:blue;">LocalTime</span>&nbsp;<span style="color:blue;">-&gt;</span>&nbsp;<span style="color:blue;">ReservationDTO</span>&nbsp;<span style="color:blue;">-&gt;</span>&nbsp;<span style="color:#2b91af;">Either</span>&nbsp;<span style="color:#2b91af;">String</span>&nbsp;<span style="color:blue;">ReservationDTO</span> validateReservation&nbsp;now&nbsp;r@(ReservationDTO&nbsp;_&nbsp;d&nbsp;_&nbsp;_&nbsp;_)&nbsp;= &nbsp;&nbsp;<span style="color:blue;">case</span>&nbsp;readMaybe&nbsp;d&nbsp;<span style="color:blue;">of</span> &nbsp;&nbsp;&nbsp;&nbsp;Nothing&nbsp;-&gt;&nbsp;Left&nbsp;$&nbsp;<span style="color:#a31515;">&quot;Invalid&nbsp;date:&nbsp;&quot;</span>&nbsp;++&nbsp;d&nbsp;++&nbsp;<span style="color:#a31515;">&quot;.&quot;</span> &nbsp;&nbsp;&nbsp;&nbsp;Just&nbsp;date&nbsp;-&gt; &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">if</span>&nbsp;date&nbsp;&lt;&nbsp;now &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">then</span>&nbsp;Left&nbsp;$&nbsp;<span style="color:#a31515;">&quot;Invalid&nbsp;date:&nbsp;&quot;</span>&nbsp;++&nbsp;d&nbsp;++&nbsp;<span style="color:#a31515;">&quot;.&quot;</span> &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">else</span>&nbsp;Right&nbsp;r</pre> </p> <p> This function remains pure, although it still changes type. It now takes an additional <code>now</code> argument that represents the current time. You can retrieve the current time as an impure action before you call <code>validateReservation</code>. Impure actions can always call pure functions. This enables you to keep your complex domain model pure, which makes it simpler, and easier to test. </p> <p> Translated to C#, that corresponds to this version of <code>Validate</code>: </p> <p> <pre><span style="color:blue;">public</span>&nbsp;<span style="color:blue;">static</span>&nbsp;<span style="color:blue;">string</span>&nbsp;<span style="color:#74531f;">Validate</span>(<span style="color:#2b91af;">DateTime</span>&nbsp;<span style="font-weight:bold;color:#1f377f;">now</span>,&nbsp;<span style="color:#2b91af;">ReservationDto</span>&nbsp;<span style="font-weight:bold;color:#1f377f;">dto</span>) { &nbsp;&nbsp;&nbsp;&nbsp;<span style="font-weight:bold;color:#8f08c4;">if</span>&nbsp;(!<span style="color:#2b91af;">DateTime</span>.<span style="color:#74531f;">TryParse</span>(<span style="font-weight:bold;color:#1f377f;">dto</span>.Date,&nbsp;<span style="color:blue;">out</span>&nbsp;<span style="color:blue;">var</span>&nbsp;<span style="font-weight:bold;color:#1f377f;">date</span>)) &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="font-weight:bold;color:#8f08c4;">return</span>&nbsp;<span style="color:#a31515;">$&quot;Invalid&nbsp;date:&nbsp;</span>{<span style="font-weight:bold;color:#1f377f;">dto</span>.Date}<span style="color:#a31515;">.&quot;</span>; &nbsp;&nbsp;&nbsp;&nbsp;<span style="font-weight:bold;color:#8f08c4;">if</span>&nbsp;(<span style="font-weight:bold;color:#1f377f;">date</span>&nbsp;<span style="font-weight:bold;color:#74531f;">&lt;</span>&nbsp;<span style="font-weight:bold;color:#1f377f;">now</span>) &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="font-weight:bold;color:#8f08c4;">return</span>&nbsp;<span style="color:#a31515;">$&quot;Invalid&nbsp;date:&nbsp;</span>{<span style="font-weight:bold;color:#1f377f;">dto</span>.Date}<span style="color:#a31515;">.&quot;</span>; &nbsp;&nbsp;&nbsp;&nbsp;<span style="font-weight:bold;color:#8f08c4;">return</span>&nbsp;<span style="color:#a31515;">&quot;&quot;</span>; }</pre> </p> <p> This version takes an additional <code>now</code> input parameter, but remains deterministic and free of side effects. Since it's pure, it's trivial to unit test. </p> <p> <pre>[<span style="color:#2b91af;">Theory</span>] [<span style="color:#2b91af;">InlineData</span>(<span style="color:#a31515;">&quot;2010-01-01&nbsp;00:01&quot;</span>,&nbsp;<span style="color:#a31515;">&quot;2011-09-11&nbsp;18:30&quot;</span>,&nbsp;3)] [<span style="color:#2b91af;">InlineData</span>(<span style="color:#a31515;">&quot;2019-11-26&nbsp;13:59&quot;</span>,&nbsp;<span style="color:#a31515;">&quot;2019-11-26&nbsp;19:00&quot;</span>,&nbsp;2)] [<span style="color:#2b91af;">InlineData</span>(<span style="color:#a31515;">&quot;2030-10-02&nbsp;23:33&quot;</span>,&nbsp;<span style="color:#a31515;">&quot;2030-10-03&nbsp;00:00&quot;</span>,&nbsp;2)] <span style="color:blue;">public</span>&nbsp;<span style="color:blue;">void</span>&nbsp;<span style="font-weight:bold;color:#74531f;">ValidDate</span>(<span style="color:blue;">string</span>&nbsp;<span style="font-weight:bold;color:#1f377f;">now</span>,&nbsp;<span style="color:blue;">string</span>&nbsp;<span style="font-weight:bold;color:#1f377f;">reservationDate</span>,&nbsp;<span style="color:blue;">int</span>&nbsp;<span style="font-weight:bold;color:#1f377f;">quantity</span>) { &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">var</span>&nbsp;<span style="font-weight:bold;color:#1f377f;">dto</span>&nbsp;=&nbsp;<span style="color:blue;">new</span>&nbsp;<span style="color:#2b91af;">ReservationDto</span>&nbsp;{&nbsp;Date&nbsp;=&nbsp;<span style="font-weight:bold;color:#1f377f;">reservationDate</span>,&nbsp;Quantity&nbsp;=&nbsp;<span style="font-weight:bold;color:#1f377f;">quantity</span>&nbsp;}; &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">var</span>&nbsp;<span style="font-weight:bold;color:#1f377f;">actual</span>&nbsp;=&nbsp;<span style="color:#2b91af;">Validator</span>.<span style="color:#74531f;">Validate</span>(<span style="color:#2b91af;">DateTime</span>.<span style="color:#74531f;">Parse</span>(<span style="font-weight:bold;color:#1f377f;">now</span>),&nbsp;<span style="font-weight:bold;color:#1f377f;">dto</span>); &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:#2b91af;">Assert</span>.<span style="color:#74531f;">Empty</span>(<span style="font-weight:bold;color:#1f377f;">actual</span>); }</pre> </p> <p> Notice that while the <code>now</code> parameter plays the <em>role</em> of the current time, the fact that it's just a value makes it trivial to run <em>simulations</em> of what would have happened if you ran this function in 2010, or what will happen when you run it in 2030. A test is really just a simulation by another name. </p> <h3 id="67101ecee7b94a849b24126ac01851fe"> Summary <a href="#67101ecee7b94a849b24126ac01851fe" title="permalink">#</a> </h3> <p> Most programming languages don't explicitly distinguish between pure and impure code. This doesn't make it impossible to do functional programming, but it makes it arduous. Since the language doesn't help you, you must constantly review changes to the code and its dependencies to evaluate whether code that's supposed to be pure remains pure. </p> <p> Tests can help, particularly if you employ <a href="/property-based-testing-intro">property-based testing</a>, but vigilance is still required. </p> <p> While Haskell isn't a mainstream programming language, I find that it helps me flush out my wrong assumptions about functional programming. I write many prototypes and proofs of concept in Haskell for that reason. </p> <p> Once you get the hang of it, it becomes easier to spot sources of impurity in other languages as well. <ul> <li>Anything with the <code>void</code> return type must be assumed to induce side effects.</li> <li>Everything that involves random numbers is non-deterministic.</li> <li>Everything that relies on the system clock is non-deterministic.</li> <li>Generating a GUID is non-deterministic.</li> <li>Everything that involves input/output is non-deterministic. That includes the file system and everything that involves network communication. In C# this implies that all <a href="/2016/04/11/async-as-surrogate-io">asynchronous APIs should be considered highly suspect</a>.</li> </ul> If you want to harvest the benefits of functional programming in a mainstream language, you must look out for such pitfalls. There's no tooling to assist you. </p> </div> <div id="comments"> <hr> <h2 id="comments-header"> Comments </h2> <div class="comment" id="1925963B8A194CF9BC44E0EB59E92C9C"> <div class="comment-author"><a href="http://criticalsoftwareblog.com">Yacoub Massad</a></div> <div class="comment-content"> <p> You might be interested in taking a look at <a href="https://github.com/ymassad/PurityAnalyzer">PurityAnalyzer</a>; An open source roslyn-based analyzer for C# that I started developing to help maintain pure C# code. </p> <p> Unfortunately, it is still not production-ready yet and I didn't have time to work on it in the last year. I was hoping contributors would help. </p> </div> <div class="comment-date">2020-02-24 08:16 UTC</div> </div> <div class="comment" id="50049d1906e04e1ab3811765ca5c3156"> <div class="comment-author"><a href="/">Mark Seemann</a></div> <div class="comment-content"> <p> Yacoub, thank you for writing. I wasn't aware of PurityAnalyzer. Do I understand it correctly that it's based mostly on a table of methods known (or assumed) to be pure? It also seems to look for certain attributes, under the assumption that if a <code>[Pure]</code> attribute is present, then one can trust it. Did I understand it correctly? </p> <p> The fundamental problems with such an approach aside, I can't think of a better solution for the current .NET platform. If you want contributors, though, you should edit the repository's readme-file so that it explains how the tool works, and how contributors could get involved. </p> </div> <div class="comment-date">2020-02-26 7:12 UTC</div> </div> <div class="comment" id="D45AAB9A9C2C4625BD949B2130416D79"> <div class="comment-author"><a href="http://criticalsoftwareblog.com">Yacoub Massad</a></div> <div class="comment-content"> <p >Here are the answers to your questions:</p> <p >1.it's based mostly on a table of methods known (or assumed) to be pure?</p> <p >This is true for compiled methods, e.g., methods in the .NET frameworks. There are lists maintained for .NET methods that are pure. The lists of course are still incomplete.</p> <p >For methods in the source code, the analyzer checks if they call impure methods, but it also checks other things like whether they access mutable state. The list of other things is not trivial. If you are interested in the details, see <a href="https://www.dotnetcurry.com/csharp/1464/pure-code-csharp"> this article</a>. It shows some of the details.</p> <p >2. It also seems to look for certain attributes, under the assumption that if a [Pure] attribute is present, then one can trust it. Did I understand it correctly?</p> <p >I don't use the [Pure] attribute because I think that the definition of pure used by Microsoft with this attribute is different than what I consider to be pure. I used a special [IsPure] attribute. There are also other attributes like [IsPureExceptLocally], [IsPureExceptReadLocally], [ReturnsNewObject], etc. The article I mentioned above explains some differences between these.</p> <p >I agree with you that I should work on readme file to explain details and ask for contributors.</p> </div> <div class="comment-date">2020-02-26 09:51 UTC</div> </div> <div class="comment" id="d28c24c07228400f9ed141f97b5c72b5"> <div class="comment-author"><a href="https://about.me/tysonwilliams">Tyson Williams</a></div> <div class="comment-content"> <p> I love this post and enthusiastically agree with all the points you made. </p> <blockquote> Is the method deterministic? It seems like it. In fact, in order to answer that question, you need to know if <code>DateTime.TryParse</code> is deterministic. Assume that it is. </blockquote> <p> For what its worth, that <a href="https://referencesource.microsoft.com/#mscorlib/system/datetime.cs,1466">overload of <code>DateTime.TryParse</code></a> is impure because it depends on <a href="https://referencesource.microsoft.com/#mscorlib/system/globalization/datetimeformatinfo.cs,d8a79667802e6102"><code>DateTimeFormatInfo.CurrentInfo</code></a>, which depends on <a href="https://docs.microsoft.com/en-us/dotnet/api/system.threading.thread.currentculture?view=netframework-4.8#System_Threading_Thread_CurrentCulture"><code>System.Threading.Thread.CurrentThread.CurrentCulture</code></a>, which is mutable. </p> <blockquote> There are lists maintained for .NET methods that are pure. </blockquote> <p> Yacoub, could you share some links to such lists? </p> </div> <div class="comment-date">2020-02-26 20:14 UTC</div> </div> <div class="comment" id="d2cd79f75b0c4904bd55f34887513b61"> <div class="comment-author"><a href="/">Mark Seemann</a></div> <div class="comment-content"> <p> Tyson, I actually knew that, but in order to keep the example simple and compelling, I chose to omit that fact. That's why I phrased the sentence "<em>Assume</em> that it is" (my emphasis) 😉 </p> </div> <div class="comment-date">2020-02-26 21:56 UTC</div> </div> <div class="comment" id="CED4372686884B47B7FCC4CC03A50C47"> <div class="comment-author"><a href="http://criticalsoftwareblog.com">Yacoub Massad</a></div> <div class="comment-content"> <p> Tyson, I meant lists maintained as part of the PurityAnalyzer project. You can find them <a href="https://github.com/ymassad/PurityAnalyzer/tree/master/PurityAnalyzer/Resources">here</a>. </p> </div> <div class="comment-date">2020-02-27 07:48 UTC</div> </div> <div class="comment" id="0d0c85170c1c4062addf406f189c0984"> <div class="comment-author"><a href="https://about.me/tysonwilliams">Tyson Williams</a></div> <div class="comment-content"> <blockquote> The [Haskell] compiler enforces the functional interaction law. You can't call impure actions from pure functions. </blockquote> <p> And in contrast, the C# compiler does not enfore the functional interaction law, right? </p> <p> For exampe, suppose <code>Foo</code> and <code>Bar</code> are pure functions such that <code>Foo</code> calls <code>Bar</code> and the code compiles. Then only change the implementation of <code>Bar</code> in such a way that it is now impure and the code still compiles, which is possible. So <code>Foo</code> is now also impure as well, but its implementation didn't change. Therefore, the C# compiler does not enfore the functional interaction law. </p> <p> Is this consistent with what you mean by the functional interaction law? </p> </div> <div class="comment-date">2020-03-07 12:59 UTC</div> </div> <div class="comment" id="2d47bc8c9c07456091f923ea5298cd7e"> <div class="comment-author"><a href="/">Mark Seemann</a></div> <div class="comment-content"> <p> Tyson, thank you for writing. The C# compiler doesn't help protect your <em>intent</em>, if your intent is to apply a functional architecture. </p> <p> In your example, <code>Foo</code> starts out pure, but becomes impure. That's a <em>result</em> of the law. The law itself isn't broken, but the relationships change. That's often not what you want, so you can say that the compiler doesn't help you maintain a functional architecture. </p> <p> A compiler like Haskell protects the intent of the law. If <code>foo</code> (Haskell functions <em>must</em> start with a lower-case letter) and <code>bar</code> both start out pure, <code>foo</code> can call <code>bar</code>. When <code>bar</code> later becomes impure, its type changes and <code>foo</code> can no longer invoke it. </p> <p> I can try to express the main assertion of the functional interaction law like this: <em>a pure function can't call an impure action.</em> This has different implications in different compiler contexts. In Haskell, functions can be statically declared to be either pure or impure. This means that the Haskell compiler can prevent pure functions from calling impure actions. In C#, there's no such distinction at the type level. The implication is therefore different: that if <code>Foo</code> calls <code>Bar</code> and <code>Bar</code> is impure, then <code>Foo</code> must also be impure. This follows by elimination, because a pure function can't call an impure action. Therefore, since <code>Foo</code> <em>can</em> call <code>Bar</code>, and <code>Bar</code> is impure, then <code>Foo</code> must also be impure. </p> <p> The causation is reversed, so to speak. </p> <p> Does that answer your question? </p> </div> <div class="comment-date">2020-03-08 11:32 UTC</div> </div> <div class="comment" id="32759f1428c34fd0860e57c077df2972"> <div class="comment-author"><a href="https://about.me/tysonwilliams">Tyson Williams</a></div> <div class="comment-content"> <p> Yes, that was a good answer. Thank you. </p> <blockquote> ...a pure function can't call an impure action. </blockquote> <p> We definitely want this to be true, but let's try to make sure it is. What do you think about the C# function <code>void Foo() =&gt; DateTime.Now;</code>? It has lots of good propertie: it alreays returns the same value (something isomorphic to <code>Unit</code>), and it does not mutate anything. However, it calls the impure property <code>DateTime.Now</code>. I think a reasonable person could argue that this function is pure. My guess is that you would say that it is impure. Am I right? I am willing to accept that. </p> <blockquote> ...a <a href="https://en.wikipedia.org/wiki/Pure_function">pure function</a> has to obey two rules: <ul> <li>The same input always produces the same output.</li> <li>Calling it causes no side effects.</li> </ul> </blockquote> <p> Is it possible for a function to violate the first rule but not violate the second rule? </p> </div> <div class="comment-date">2020-03-09 04:12 UTC</div> </div> <div class="comment" id="a7375c806c1147c1b37187834fb04153"> <div class="comment-author"><a href="/">Mark Seemann</a></div> <div class="comment-content"> <p> Tyson, I'm going to assume that you mean something like <code>void Foo() { var _ = DateTime.Now; }</code>, since the code you ask about doesn't compile 😉 </p> <p> That function is, indeed pure, because it has no observable side effects, and it always <a href="/2018/01/15/unit-isomorphisms">returns unit</a>. Purity is mostly a question of what we can observe if we consider the function a black box. </p> <p> Obviously, based on that criterion, we can refactor the function to <code>void Foo() { }</code> and we wouldn't be able to tell the difference. This version of <code>Foo</code> is clearly pure, although degenerate. <blockquote> Is it possible for a function to violate the first rule but not violate the second rule? </blockquote> Yes, the following method is non-deterministic, but has no side effects: <code>DateTime Foo() =&gt; DateTime.Now;</code> The input is always <em>unit</em>, but the return value can change. </p> </div> <div class="comment-date">2020-03-10 9:03 UTC</div> </div> <div class="comment" id="60eb2b1f83dd4b2fbc0be684d729af96"> <div class="comment-author"><a href="https://about.me/tysonwilliams">Tyson Williams</a></div> <div class="comment-content"> <p> I think I need to practice test driven comment writing ;) Thanks for seeing through my syntax errors again. </p> <p> Oh, you think that that function is pure. Interesting. It follows then that the functional interaction law (pure functions cannot call impure actions) does <i>not</i> follow from the definition of a pure function. It is possible, in theory and in practice, for a pure function to call an impure action. Instead, the functional interaction law is "just" a goal to aspire to when designing a programming language. Haskell achieved that goal while C# and F# did not. Do you agree with this? (This is really what I was driving towards in <a href="https://blog.ploeh.dk/2020/02/24/discerning-and-maintaining-purity/#0d0c85170c1c4062addf406f189c0984">this comment above</a>, but I was trying to approach this "blasphemous" claim slowly.) </p> <p> Just as you helped me distinguish between function purity and totality in <a href="https://blog.ploeh.dk/2015/05/07/functional-design-is-intrinsically-testable/#97e4ae29436e4828813bf445ee1c37dc">this comment</a>, I think it would be helpful for us to consider separately the two defining properties of a pure function. The first property is "the same input always produces the same output". Let's call this weak determinism. <a href="https://en.wikipedia.org/wiki/Deterministic_algorithm">Determinism</a> is could be defined as "the same input always produces the same sequence of states", which includes the state of the output, so determinism is indeed stronger than weak determinism. The second property is "causes no side effect". It seems to me that there is either a lack of consensus or a lack of clarity about what constitutes a side effect. One definition I like is mutation of state outside of the current stack frame. </p> <p> One reason the functional interaction law is false in general is because the corresponding interaction law for weak determinism also false in general. The function I gave above (that called <code>DateTime.Now</code> and then returned unit) is a trivial example of that. A nontrivial example is <a href="https://en.wikipedia.org/wiki/Quicksort">quicksort</a>. </p> <p> At this point, I wanted to claim that the side effect interaction law is true in general, but it is not. This law says that a function that is side-effect free cannot call a function that causes a side effect. A counterexample is <code>void Foo() { int i = 0; Bar(ref i); }</code> with <code>void Bar(ref int i) => i++;</code>. That is, <code>Bar</code> mutates state outside of its stack frame, namely in the stack frame of <code>Foo</code>, so it is not weakly deterministic, but <code>Foo</code> is. (And I promise that I tested that code for compiler errors.) </p> <p> I need to think more about that. Is there a better definition of side effect, one for which the side effect interaction law is true? </p> <p> I just realized something that I think is interesting. Purely functional programming languages enforce a property of functions stronger than purity. With respect to the first defining property of a pure function (aka weak determinism), purely functional programming languages enforce the stronger notion of determinism. Otherwise, the compiler would need to realize that functions like quicksort should be allowed (because it is weakly deterministic). This reminds me of the debate between static and dynamic programming languages. In the process of forbidding certain unsafe code, static languages end up forbidding some safe code as well. </p> </div> <div class="comment-date">2020-03-10 14:05 UTC</div> </div> <div class="comment" id="dd776b1b8b0d43c58171ff7fec311c2c"> <div class="comment-author"><a href="/">Mark Seemann</a></div> <div class="comment-content"> <p> Tyson, I disagree with your basic premise: <blockquote> "It follows then that the functional interaction law (pure functions cannot call impure actions) does not follow from the definition of a pure function." </blockquote> I don't think that this follows. </p> <p> The key is that your example is <em>degenerate</em>. The <code>Foo</code> function is only pure because <code>DateTime.Now</code> isn't used. The actual, underlying property that we're aiming for is <a href="https://en.wikipedia.org/wiki/Referential_transparency">referential transparency</a>. Can you replace <code>Foo</code> with its value? Yes, you can. </p> <p> Perhaps you think this is a hand-wavy attempt to dodge a bullet, but I don't think that it is. You can write the equivalent function in Haskell like this: </p> <p> <pre><span style="color:#2b91af;">foo</span>&nbsp;::&nbsp;()&nbsp;<span style="color:blue;">-&gt;</span>&nbsp;() foo&nbsp;<span style="color:blue;">()</span>&nbsp;= &nbsp;&nbsp;<span style="color:blue;">let</span>&nbsp;_&nbsp;=&nbsp;getCurrentTime &nbsp;&nbsp;<span style="color:blue;">in</span>&nbsp;<span style="color:blue;">()</span></pre> </p> <p> I don't recall if you're familiar with Haskell, but for the benefit of any reader who comes by and wishes to follow this discussion, here are the important points: <ul> <li>The function calls <code>getCurrentTime</code>, which is an impure action. Its type is <code>IO UTCTime</code>. The <code>IO</code> <a href="https://bartoszmilewski.com/2014/01/14/functors-are-containers">container</a> marks the action as impure.</li> <li>The underscore is a <em>wildcard</em> that tells Haskell to discard the value.</li> <li>The type of <code>foo</code> is <code>() -&gt; ()</code>. It takes <a href="/2018/01/15/unit-isomorphisms">unit</a> as input and returns <em>unit</em>. There's no <code>IO</code> container involved, so the function is pure.</li> </ul> This works because Haskell is a strictly functional language. Every expression is referentially transparent. The implication is that something like <code>IO UTCTime</code> is an <em>opaque</em> container of <code>UTCTime</code> values. A pure caller can see the container, but not its contents. A common interpretation of this is that <code>IO</code> represents the superposition of all possible values, just like <a href="https://en.wikipedia.org/wiki/Schr%C3%B6dinger%27s_cat">Schrödinger's box</a>. Also, since Haskell is a lazily evaluated language, actions are only evaluated when their values are needed for something. Since the value of <code>getCurrentTime</code> is discarded, the impure action never runs (the box is never opened). This may be clearer with this example: </p> <p> <pre><span style="color:#2b91af;">bar</span>&nbsp;::&nbsp;()&nbsp;<span style="color:blue;">-&gt;</span>&nbsp;() bar&nbsp;<span style="color:blue;">()</span>&nbsp;= &nbsp;&nbsp;<span style="color:blue;">let</span>&nbsp;_&nbsp;=&nbsp;<span style="color:blue;">putStrLn</span>&nbsp;<span style="color:#a31515;">&quot;Bar!&quot;</span> &nbsp;&nbsp;<span style="color:blue;">in</span>&nbsp;<span style="color:blue;">()</span></pre> </p> <p> Like <code>foo</code>, <code>bar</code> calls an impure action: <code>putStrLn</code>, which corresponds to <code>Console.WriteLine</code>. Having the type <code>String -&gt; IO ()</code> it's impure. It works like this: </p> <p> <pre>&gt; putStrLn "Example" Example</pre> </p> <p> None the less, because <code>bar</code> discards the <code>IO ()</code> return value after it calls <code>putStrLn</code>, it never evaluates: </p> <p> <pre>&gt; bar () ()</pre> </p> <p> Perhaps a subtle rephrasing of the functional interaction law would be more precise. Perhaps it should say that a pure function can't <em>evaluate</em> an impure action. </p> <p> Bringing this back to C#, we have to keep in mind that C# doesn't enforce the functional interaction law in any way. Thus, the law works ex-post, instead of in Haskell, where it works ex-ante. Is the <code>Foo</code> C# code pure? Yes, it is, because it's referentially transparent. </p> <p> Regarding the purity of QuickSort, you may find <a href="https://stackoverflow.com/q/7717691/126014">this discussion</a> interesting. </p> </div> <div class="comment-date">2020-03-12 7:40 UTC</div> </div> </div> <hr> This blog is totally free, but if you like it, please consider <a href="https://blog.ploeh.dk/support">supporting it</a>. Mark Seemann https://blog.ploeh.dk/2020/02/24/discerning-and-maintaining-purity Builder as a monoid https://blog.ploeh.dk/2020/02/17/builder-as-a-monoid/ Mon, 17 Feb 2020 07:18:00 UTC <div id="post"> <p> <em>Builder, particularly Fluent Builder, is one of the more useful design patterns. Here's why.</em> </p> <p> This article is part of <a href="/2018/03/05/some-design-patterns-as-universal-abstractions/">a series of articles about design patterns and their universal abstraction counterparts</a>. </p> <p> The <a href="https://en.wikipedia.org/wiki/Builder_pattern">Builder design pattern</a> is an occasionally useful pattern, but mostly in its Fluent Builder variation. I've already described that <a href="/2020/02/10/builder-isomorphisms">Builder, Fluent Builder, and Immutable Fluent Builder are isomorphic</a>. The Immutable Fluent Builder variation is a set of <a href="https://en.wikipedia.org/wiki/Pure_function">pure functions</a>, so among the three variations, it best fits the set of universal abstractions that I've so far discussed in <a href="/2017/10/04/from-design-patterns-to-category-theory">this article series</a>. </p> <p> <a href="http://amzn.to/XBYukB">Design Patterns</a> describes 23 patterns. Some of these are more useful than others. I first read the book in 2003, and while I initially used many of the patterns, after some years I settled into a routine where I'd reach for the same handful of patterns and ignore the rest. </p> <p> What makes some design patterns more universally useful than others? There's probably components of both subjectivity and chance, but I also believe that there's some correlation to universal abstractions. I consider abstractions universal when they are derived from universal truths (i.e. mathematics) instead of language features or 'just' experience. That's what the overall article series is about. In this article, you'll learn how the Builder pattern is an instance of a universal abstraction. Hopefully, this goes a long way towards explaining why it seems to be so universally useful. </p> <h3 id="6d834828809b4ac2b36f59bb244e5952"> Builder API, isolated <a href="#6d834828809b4ac2b36f59bb244e5952" title="permalink">#</a> </h3> <p> I'll start with the <code>HttpRequestMessageBuilder</code> from the article about <a href="/2020/02/10/builder-isomorphisms">Builder isomorphisms</a>, particularly its Immutable Fluent Builder incarnation. Start by isolating those methods that manipulate the Builder. These are the functions that had <code>void</code> return types in the original Builder incarnation. Imagine, for example, that you extract an interface of only those methods. What would such an interface look like? </p> <p> <pre><span style="color:blue;">public</span>&nbsp;<span style="color:blue;">interface</span>&nbsp;<span style="color:#2b91af;">IHttpRequestMessageBuilder</span> { &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:#2b91af;">HttpRequestMessageBuilder</span>&nbsp;<span style="font-weight:bold;color:#74531f;">AddJsonBody</span>(<span style="color:blue;">object</span>&nbsp;<span style="font-weight:bold;color:#1f377f;">jsonBody</span>); &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:#2b91af;">HttpRequestMessageBuilder</span>&nbsp;<span style="font-weight:bold;color:#74531f;">WithMethod</span>(<span style="color:#2b91af;">HttpMethod</span>&nbsp;<span style="font-weight:bold;color:#1f377f;">newMethod</span>); }</pre> </p> <p> Keep in mind that on all instance methods, <a href="/2018/02/12/object-isomorphisms">the instance itself can be viewed as 'argument 0'</a>. In that light, each of these methods take two arguments: a Builder and the formal argument (<code>jsonBody</code> and <code>newMethod</code>, respectively). Each method returns a Builder. I've <a href="/2019/01/28/better-abstractions-revisited#047886dcfa5a4a1398965138669e0ddc">already described how this is equivalent to an endomorphism</a>. An <a href="https://en.wikipedia.org/wiki/Endomorphism">endomorphism</a> is a function that returns the same type of output as its input, and <a href="/2017/11/13/endomorphism-monoid">it forms a monoid</a>. </p> <p> This can be difficult to see, so I'll make it explicit. The code that follows only exists to illustrate the point. In no way do I endorse that you write code in this way. </p> <h3 id="e022825850dc4fbf8d78b550bebb5d7c"> Explicit endomorphism <a href="#e022825850dc4fbf8d78b550bebb5d7c" title="permalink">#</a> </h3> <p> You can define a formal interface for an endomorphism: </p> <p> <pre><span style="color:blue;">public</span>&nbsp;<span style="color:blue;">interface</span>&nbsp;<span style="color:#2b91af;">IEndomorphism</span>&lt;<span style="color:#2b91af;">T</span>&gt; { &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:#2b91af;">T</span>&nbsp;<span style="font-weight:bold;color:#74531f;">Run</span>(<span style="color:#2b91af;">T</span>&nbsp;<span style="font-weight:bold;color:#1f377f;">x</span>); }</pre> </p> <p> Notice that it's completely generic. The <code>Run</code> method takes a value of the generic type <code>T</code> and returns a value of the type <code>T</code>. The identity of the <a href="/2017/10/06/monoids">monoid</a>, you may recall, is the eponymously named <em>identity</em> function which returns its input without modification. You can also define the monoidal combination of two endomorphisms: </p> <p> <pre><span style="color:blue;">public</span>&nbsp;<span style="color:blue;">class</span>&nbsp;<span style="color:#2b91af;">AppendEndomorphism</span>&lt;<span style="color:#2b91af;">T</span>&gt;&nbsp;:&nbsp;<span style="color:#2b91af;">IEndomorphism</span>&lt;<span style="color:#2b91af;">T</span>&gt; { &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">private</span>&nbsp;<span style="color:blue;">readonly</span>&nbsp;<span style="color:#2b91af;">IEndomorphism</span>&lt;<span style="color:#2b91af;">T</span>&gt;&nbsp;morphism1; &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">private</span>&nbsp;<span style="color:blue;">readonly</span>&nbsp;<span style="color:#2b91af;">IEndomorphism</span>&lt;<span style="color:#2b91af;">T</span>&gt;&nbsp;morphism2; &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">public</span>&nbsp;<span style="color:#2b91af;">AppendEndomorphism</span>(<span style="color:#2b91af;">IEndomorphism</span>&lt;<span style="color:#2b91af;">T</span>&gt;&nbsp;<span style="font-weight:bold;color:#1f377f;">morphism1</span>,&nbsp;<span style="color:#2b91af;">IEndomorphism</span>&lt;<span style="color:#2b91af;">T</span>&gt;&nbsp;<span style="font-weight:bold;color:#1f377f;">morphism2</span>) &nbsp;&nbsp;&nbsp;&nbsp;{ &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">this</span>.morphism1&nbsp;=&nbsp;<span style="font-weight:bold;color:#1f377f;">morphism1</span>; &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">this</span>.morphism2&nbsp;=&nbsp;<span style="font-weight:bold;color:#1f377f;">morphism2</span>; &nbsp;&nbsp;&nbsp;&nbsp;} &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">public</span>&nbsp;<span style="color:#2b91af;">T</span>&nbsp;<span style="font-weight:bold;color:#74531f;">Run</span>(<span style="color:#2b91af;">T</span>&nbsp;<span style="font-weight:bold;color:#1f377f;">x</span>) &nbsp;&nbsp;&nbsp;&nbsp;{ &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="font-weight:bold;color:#8f08c4;">return</span>&nbsp;morphism2.<span style="font-weight:bold;color:#74531f;">Run</span>(morphism1.<span style="font-weight:bold;color:#74531f;">Run</span>(<span style="font-weight:bold;color:#1f377f;">x</span>)); &nbsp;&nbsp;&nbsp;&nbsp;} }</pre> </p> <p> This implementation of <code>IEndomorphism&lt;T&gt;</code> composes two other <code>IEndomorphism&lt;T&gt;</code> objects. When its <code>Run</code> method is called, it first calls <code>Run</code> on <code>morphism1</code> and then uses the return value of that method call (still a <code>T</code> object) as input for <code>Run</code> on <code>morphism2</code>. </p> <p> If you need to combine more than two endomorphisms then that's also possible, because <a href="/2017/11/20/monoids-accumulate">monoids accumulate</a>. </p> <h3 id="5f10f8e180b349a0b0584812a0c62431"> Explicit endomorphism to change HTTP method <a href="#5f10f8e180b349a0b0584812a0c62431" title="permalink">#</a> </h3> <p> You can adapt the <code>WithMethod</code> method to the <code>IEndomorphism&lt;HttpRequestMessageBuilder&gt;</code> interface: </p> <p> <pre><span style="color:blue;">public</span>&nbsp;<span style="color:blue;">class</span>&nbsp;<span style="color:#2b91af;">ChangeMethodEndomorphism</span>&nbsp;:&nbsp;<span style="color:#2b91af;">IEndomorphism</span>&lt;<span style="color:#2b91af;">HttpRequestMessageBuilder</span>&gt; { &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">private</span>&nbsp;<span style="color:blue;">readonly</span>&nbsp;<span style="color:#2b91af;">HttpMethod</span>&nbsp;newMethod; &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">public</span>&nbsp;<span style="color:#2b91af;">ChangeMethodEndomorphism</span>(<span style="color:#2b91af;">HttpMethod</span>&nbsp;<span style="font-weight:bold;color:#1f377f;">newMethod</span>) &nbsp;&nbsp;&nbsp;&nbsp;{ &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">this</span>.newMethod&nbsp;=&nbsp;<span style="font-weight:bold;color:#1f377f;">newMethod</span>; &nbsp;&nbsp;&nbsp;&nbsp;} &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">public</span>&nbsp;<span style="color:#2b91af;">HttpRequestMessageBuilder</span>&nbsp;<span style="font-weight:bold;color:#74531f;">Run</span>(<span style="color:#2b91af;">HttpRequestMessageBuilder</span>&nbsp;<span style="font-weight:bold;color:#1f377f;">x</span>) &nbsp;&nbsp;&nbsp;&nbsp;{ &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="font-weight:bold;color:#8f08c4;">if</span>&nbsp;(<span style="font-weight:bold;color:#1f377f;">x</span>&nbsp;<span style="color:blue;">is</span>&nbsp;<span style="color:blue;">null</span>) &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="font-weight:bold;color:#8f08c4;">throw</span>&nbsp;<span style="color:blue;">new</span>&nbsp;<span style="color:#2b91af;">ArgumentNullException</span>(<span style="color:blue;">nameof</span>(<span style="font-weight:bold;color:#1f377f;">x</span>)); &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="font-weight:bold;color:#8f08c4;">return</span>&nbsp;<span style="font-weight:bold;color:#1f377f;">x</span>.<span style="font-weight:bold;color:#74531f;">WithMethod</span>(newMethod); &nbsp;&nbsp;&nbsp;&nbsp;} }</pre> </p> <p> In itself, this is simple code, but it does turn things on their head. The <code>newMethod</code> argument is now a class field (and constructor argument), while the <code>HttpRequestMessageBuilder</code> has been turned into a method argument. Keep in mind that I'm not doing this because I endorse this style of API design; I do it to demonstrate how the Immutable Fluent Builder pattern is an endomorphism. </p> <p> Since <code>ChangeMethodEndomorphism</code> is an <a href="https://en.wikipedia.org/wiki/Adapter_pattern">Adapter</a> between <code>IEndomorphism&lt;HttpRequestMessageBuilder&gt;</code> and the <code>WithMethod</code> method, I hope that this is becoming apparent. I'll show one more Adapter. </p> <h3 id="73a3f6e43a19457a937b36ed8682defa"> Explicit endomorphism to add a JSON body <a href="#73a3f6e43a19457a937b36ed8682defa" title="permalink">#</a> </h3> <p> In the example code, there's one more method that modifies an <code>HttpRequestMessageBuilder</code> object, and that's the <code>AddJsonBody</code> method. You can also create an Adapter over that method: </p> <p> <pre><span style="color:blue;">public</span>&nbsp;<span style="color:blue;">class</span>&nbsp;<span style="color:#2b91af;">AddJsonBodyEndomorphism</span>&nbsp;:&nbsp;<span style="color:#2b91af;">IEndomorphism</span>&lt;<span style="color:#2b91af;">HttpRequestMessageBuilder</span>&gt; { &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">private</span>&nbsp;<span style="color:blue;">readonly</span>&nbsp;<span style="color:blue;">object</span>&nbsp;jsonBody; &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">public</span>&nbsp;<span style="color:#2b91af;">AddJsonBodyEndomorphism</span>(<span style="color:blue;">object</span>&nbsp;<span style="font-weight:bold;color:#1f377f;">jsonBody</span>) &nbsp;&nbsp;&nbsp;&nbsp;{ &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">this</span>.jsonBody&nbsp;=&nbsp;<span style="font-weight:bold;color:#1f377f;">jsonBody</span>; &nbsp;&nbsp;&nbsp;&nbsp;} &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">public</span>&nbsp;<span style="color:#2b91af;">HttpRequestMessageBuilder</span>&nbsp;<span style="font-weight:bold;color:#74531f;">Run</span>(<span style="color:#2b91af;">HttpRequestMessageBuilder</span>&nbsp;<span style="font-weight:bold;color:#1f377f;">x</span>) &nbsp;&nbsp;&nbsp;&nbsp;{ &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="font-weight:bold;color:#8f08c4;">if</span>&nbsp;(<span style="font-weight:bold;color:#1f377f;">x</span>&nbsp;<span style="color:blue;">is</span>&nbsp;<span style="color:blue;">null</span>) &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="font-weight:bold;color:#8f08c4;">throw</span>&nbsp;<span style="color:blue;">new</span>&nbsp;<span style="color:#2b91af;">ArgumentNullException</span>(<span style="color:blue;">nameof</span>(<span style="font-weight:bold;color:#1f377f;">x</span>)); &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="font-weight:bold;color:#8f08c4;">return</span>&nbsp;<span style="font-weight:bold;color:#1f377f;">x</span>.<span style="font-weight:bold;color:#74531f;">AddJsonBody</span>(jsonBody); &nbsp;&nbsp;&nbsp;&nbsp;} }</pre> </p> <p> While the <code>AddJsonBody</code> method itself is more complicated than <code>WithMethod</code>, the Adapter is strikingly similar. </p> <h3 id="680c696032f542ae8cddcf7a520e84eb"> Running an explicit endomorphism <a href="#680c696032f542ae8cddcf7a520e84eb" title="permalink">#</a> </h3> <p> You can use the <code>IEndomorphism&lt;T&gt;</code> API to compose a pipeline of operations that will, for example, make an <code>HttpRequestMessageBuilder</code> build an HTTP <code>POST</code> request with a JSON body: </p> <p> <pre><span style="color:#2b91af;">IEndomorphism</span>&lt;<span style="color:#2b91af;">HttpRequestMessageBuilder</span>&gt;&nbsp;<span style="font-weight:bold;color:#1f377f;">morphism</span>&nbsp;=&nbsp;<span style="color:blue;">new</span>&nbsp;<span style="color:#2b91af;">AppendEndomorphism</span>&lt;<span style="color:#2b91af;">HttpRequestMessageBuilder</span>&gt;( &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">new</span>&nbsp;<span style="color:#2b91af;">ChangeMethodEndomorphism</span>(<span style="color:#2b91af;">HttpMethod</span>.Post), &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">new</span>&nbsp;<span style="color:#2b91af;">AddJsonBodyEndomorphism</span>(<span style="color:blue;">new</span> &nbsp;&nbsp;&nbsp;&nbsp;{ &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;id&nbsp;=&nbsp;<span style="color:#2b91af;">Guid</span>.<span style="color:#74531f;">NewGuid</span>(), &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;date&nbsp;=&nbsp;<span style="color:#a31515;">&quot;2020-03-22&nbsp;19:30:00&quot;</span>, &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;name&nbsp;=&nbsp;<span style="color:#a31515;">&quot;Ælfgifu&quot;</span>, &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;email&nbsp;=&nbsp;<span style="color:#a31515;">&quot;ælfgifu@example.net&quot;</span>, &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;quantity&nbsp;=&nbsp;1 &nbsp;&nbsp;&nbsp;&nbsp;}));</pre> </p> <p> You can then <code>Run</code> the endomorphism over a new <code>HttpRequestMessageBuilder</code> object to produce an HTTP request: </p> <p> <pre><span style="color:#2b91af;">HttpRequestMessage</span>&nbsp;<span style="font-weight:bold;color:#1f377f;">msg</span>&nbsp;=&nbsp;<span style="font-weight:bold;color:#1f377f;">morphism</span>.<span style="font-weight:bold;color:#74531f;">Run</span>(<span style="color:blue;">new</span>&nbsp;<span style="color:#2b91af;">HttpRequestMessageBuilder</span>(<span style="font-weight:bold;color:#1f377f;">url</span>)).<span style="font-weight:bold;color:#74531f;">Build</span>();</pre> </p> <p> The <code>msg</code> object represents an HTTP <code>POST</code> request with the supplied JSON body. </p> <p> Once again, I stress that the purpose of this little exercise is only to demonstrate how an Immutable Fluent Builder is an endomorphism, which is a monoid. </p> <h3 id="cfbf771a96144050ac21bf7c58333595"> Test Data Builder endomorphism <a href="#cfbf771a96144050ac21bf7c58333595" title="permalink">#</a> </h3> <p> You can give <a href="http://www.natpryce.com/articles/000714.html">Test Data Builders</a> the same treatment, again only to demonstrate that the reason they compose so well is because they're monoids. I'll use an immutable variation of the <code>AddressBuilder</code> from <a href="/2017/08/15/test-data-builders-in-c">this article</a>. </p> <p> For example, to modify a city, you can introduce an endomorphism like this: </p> <p> <pre><span style="color:blue;">public</span>&nbsp;<span style="color:blue;">class</span>&nbsp;<span style="color:#2b91af;">CityEndomorphism</span>&nbsp;:&nbsp;<span style="color:#2b91af;">IEndomorphism</span>&lt;<span style="color:#2b91af;">AddressBuilder</span>&gt; { &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">private</span>&nbsp;<span style="color:blue;">readonly</span>&nbsp;<span style="color:blue;">string</span>&nbsp;city; &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">public</span>&nbsp;<span style="color:#2b91af;">CityEndomorphism</span>(<span style="color:blue;">string</span>&nbsp;<span style="font-weight:bold;color:#1f377f;">city</span>) &nbsp;&nbsp;&nbsp;&nbsp;{ &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">this</span>.city&nbsp;=&nbsp;<span style="font-weight:bold;color:#1f377f;">city</span>; &nbsp;&nbsp;&nbsp;&nbsp;} &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">public</span>&nbsp;<span style="color:#2b91af;">AddressBuilder</span>&nbsp;<span style="font-weight:bold;color:#74531f;">Run</span>(<span style="color:#2b91af;">AddressBuilder</span>&nbsp;<span style="font-weight:bold;color:#1f377f;">x</span>) &nbsp;&nbsp;&nbsp;&nbsp;{ &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="font-weight:bold;color:#8f08c4;">return</span>&nbsp;<span style="font-weight:bold;color:#1f377f;">x</span>.<span style="font-weight:bold;color:#74531f;">WithCity</span>(city); &nbsp;&nbsp;&nbsp;&nbsp;} }</pre> </p> <p> You can use it to create an address in Paris like this: </p> <p> <pre><span style="color:#2b91af;">IEndomorphism</span>&lt;<span style="color:#2b91af;">AddressBuilder</span>&gt;&nbsp;<span style="font-weight:bold;color:#1f377f;">morphism</span>&nbsp;=&nbsp;<span style="color:blue;">new</span>&nbsp;<span style="color:#2b91af;">CityEndomorphism</span>(<span style="color:#a31515;">&quot;Paris&quot;</span>); <span style="color:#2b91af;">Address</span>&nbsp;<span style="font-weight:bold;color:#1f377f;">address</span>&nbsp;=&nbsp;<span style="font-weight:bold;color:#1f377f;">morphism</span>.<span style="font-weight:bold;color:#74531f;">Run</span>(<span style="color:blue;">new</span>&nbsp;<span style="color:#2b91af;">AddressBuilder</span>()).<span style="font-weight:bold;color:#74531f;">Build</span>();</pre> </p> <p> The <code>address</code> is fully populated with <code>Street</code>, <code>PostCode</code>, and so on, but apart from <code>City</code>, you know none of the values. </p> <h3 id="c5d669df78134e22a5910233da2cc813"> Sweet spot <a href="#c5d669df78134e22a5910233da2cc813" title="permalink">#</a> </h3> <p> Let's return to the question from the introduction to the article. What makes some design patterns useful? I don't think that there's a single answer to that question, but I find it intriguing that so many of the useful patterns turn out to be equivalent to universal abstractions. The Builder pattern is a monoid. From a programming perspective, the most useful characteristic of <a href="/2017/11/27/semigroups">semigroups</a> and monoids is that they enable you to treat many objects as one object. Monoids compose. </p> <p> Of the three Builder variations, the Immutable Fluent Builder is the most useful. It's also the variation that most clearly corresponds to the endomorphism monoid. Viewing it as an endomorphism reveals its strengths. When or where is a Builder most useful? </p> <p> Don't be mislead by <em>Design Patterns</em>, which states the intent of the Builder pattern like this: <blockquote> <p> "Separate the construction of a complex object from its representation so that the same construction process can create different representations." </p> <footer><cite>Gamma et al, Design Patterns, 1994</cite></footer> </blockquote> This may still be the case, but I don't find that this is the primary advantage offered by the pattern. We've learned much about the utility of each design pattern since 1994, so I don't blame the Gang of Four for not seeing this. I do think, however, that it's important to emphasise that the benefit you can derive from a pattern may differ from the original motivation. </p> <p> An endomorphism represents a modification of a value. You need a value to get started, and you get a modified value (of the same type) as output. </p> <p> <img src="/content/binary/single-step-endomorphism.png" alt="An object (a little circle) to the left, going into a horizontally oriented pipe, and coming out to the right in a different colour."> </p> <p> Sometimes, all you need is the initial object. </p> <p> <img src="/content/binary/single-object-depicted-as-a-circle.png" alt="An object represented as a little circle."> </p> <p> And sometimes, you need to compose several changes. </p> <p> <img src="/content/binary/double-step-endomorphism.png" alt="An object (a little circle) to the left, going into two horizontally oriented pipe, on after the other, and coming out to the right in a different colour."> </p> <p> To me, this makes the sweet spot for the pattern clear. Use an (Immutable) Fluent Builder when you have a basic object that's useful in itself, but where you want to give client code the option to make changes to the defaults. </p> <p> Sometimes, the initial object has self-contained default values. Test Data Builders are good examples of that: </p> <p> <pre><span style="color:blue;">public</span>&nbsp;<span style="color:#2b91af;">AddressBuilder</span>() { &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">this</span>.street&nbsp;=&nbsp;<span style="color:#a31515;">&quot;&quot;</span>; &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">this</span>.city&nbsp;=&nbsp;<span style="color:#a31515;">&quot;&quot;</span>; &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">this</span>.postCode&nbsp;=&nbsp;<span style="color:blue;">new</span>&nbsp;<span style="color:#2b91af;">PostCodeBuilder</span>().<span style="font-weight:bold;color:#74531f;">Build</span>(); }</pre> </p> <p> The <code>AddressBuilder</code> constructor fully initialises the object. You can use its <code>WithNoPostcode</code>, <code>WithStreet</code>, etcetera methods to make changes to it, but you can also use it as is. </p> <p> In other cases, client code must initialise the object to be built. The <code>HttpRequestMessageBuilder</code> is an example of that: </p> <p> <pre><span style="color:blue;">public</span>&nbsp;<span style="color:#2b91af;">HttpRequestMessageBuilder</span>(<span style="color:blue;">string</span>&nbsp;<span style="font-weight:bold;color:#1f377f;">url</span>)&nbsp;:&nbsp;<span style="color:blue;">this</span>(<span style="color:blue;">new</span>&nbsp;<span style="color:#2b91af;">Uri</span>(<span style="font-weight:bold;color:#1f377f;">url</span>))&nbsp;{&nbsp;} <span style="color:blue;">public</span>&nbsp;<span style="color:#2b91af;">HttpRequestMessageBuilder</span>(<span style="color:#2b91af;">Uri</span>&nbsp;<span style="font-weight:bold;color:#1f377f;">url</span>)&nbsp;:&nbsp;<span style="color:blue;">this</span>(<span style="font-weight:bold;color:#1f377f;">url</span>,&nbsp;<span style="color:#2b91af;">HttpMethod</span>.Get,&nbsp;<span style="color:blue;">null</span>)&nbsp;{&nbsp;} <span style="color:blue;">private</span>&nbsp;<span style="color:#2b91af;">HttpRequestMessageBuilder</span>(<span style="color:#2b91af;">Uri</span>&nbsp;<span style="font-weight:bold;color:#1f377f;">url</span>,&nbsp;<span style="color:#2b91af;">HttpMethod</span>&nbsp;<span style="font-weight:bold;color:#1f377f;">method</span>,&nbsp;<span style="color:blue;">object</span>?&nbsp;<span style="font-weight:bold;color:#1f377f;">jsonBody</span>) { &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">this</span>.url&nbsp;=&nbsp;<span style="font-weight:bold;color:#1f377f;">url</span>; &nbsp;&nbsp;&nbsp;&nbsp;Method&nbsp;=&nbsp;<span style="font-weight:bold;color:#1f377f;">method</span>; &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">this</span>.jsonBody&nbsp;=&nbsp;<span style="font-weight:bold;color:#1f377f;">jsonBody</span>; }</pre> </p> <p> While there's more than one constructor overload, client code must supply a <code>url</code> in one form or other. That's the precondition of this class. Given a valid <code>url</code>, though, an <code>HttpRequestMessageBuilder</code> object can be useful without further modification, but you can also modify it by calling its methods. </p> <p> You often see the Builder pattern used for configuration APIs. The ASP.NET Core <a href="https://docs.microsoft.com/dotnet/api/microsoft.aspnetcore.builder.iapplicationbuilder">IApplicationBuilder</a> is a prominent example of the Fluent Builder pattern. The <a href="https://docs.particular.net/samples/endpoint-configuration">NServiceBus endpoint configuration API</a>, on the other hand, is based on the classic Builder pattern. It makes sense to use an endomorphic design for framework configuration. Framework designers want to make it as easy to get started with their framework as possible. For this reason, it's important to provide a useful default configuration, so that you can get started with as little <a href="/2019/12/16/zone-of-ceremony">ceremony</a> as possible. On the other hand, a framework must be flexible. You need a way to tweak the configuration to support your particular needs. The Builder pattern supports both scenarios. </p> <p> Other examples include Test Data Builders, as well as specialised Builders such as <a href="https://docs.microsoft.com/dotnet/api/system.uribuilder">UriBuilder</a> and <a href="https://docs.microsoft.com/dotnet/api/system.data.sqlclient.sqlconnectionstringbuilder">SqlConnectionStringBuilder</a>. </p> <p> It's also worth noting that <a href="https://docs.microsoft.com/dotnet/fsharp/language-reference/copy-and-update-record-expressions">F# copy-and-update expressions</a> are endomorphisms. That's the reason that when you have immutable records, <a href="/2017/09/11/test-data-without-builders">you need no Test Data Builders</a>. </p> <h3 id="64b49f4143eb49fc80ab6344e247a0bd"> Summary <a href="#64b49f4143eb49fc80ab6344e247a0bd" title="permalink">#</a> </h3> <p> The Builder pattern comes in (at least) three variations: the Gang-of-Four Builder pattern, Fluent Builder, and Immutable Fluent Builder. All are isomorphic to each other, and are equivalent to the endomorphism monoid. </p> <p> Viewing Builders as endomorphisms may mostly be an academic exercise, but I think it highlights the sweet spot for the pattern. It's particularly useful when you wish to expose an API that offers simple defaults, while at the same time enabling client code to make changes to those defaults. When those changes involve several steps (as e.g. <code>AddJsonBody</code>) you can view each modifier method as a <a href="https://en.wikipedia.org/wiki/Facade_pattern">Facade</a>. </p> <p> <strong>Next:</strong> <a href="/2018/06/25/visitor-as-a-sum-type">Visitor as a sum type</a>. </p> </div><hr> This blog is totally free, but if you like it, please consider <a href="https://blog.ploeh.dk/support">supporting it</a>. Mark Seemann https://blog.ploeh.dk/2020/02/17/builder-as-a-monoid Builder isomorphisms https://blog.ploeh.dk/2020/02/10/builder-isomorphisms/ Mon, 10 Feb 2020 07:06:00 UTC <div id="post"> <p> <em>The Builder pattern is equivalent to the Fluent Builder pattern.</em> </p> <p> This article is part of <a href="/2018/01/08/software-design-isomorphisms">a series of articles about software design isomorphisms</a>. An isomorphism is when a bi-directional lossless translation exists between two representations. Such translations exist between the <a href="https://en.wikipedia.org/wiki/Builder_pattern">Builder</a> pattern and two variations of the <em>Fluent Builder</em> pattern. Since the names sound similar, this is hardly surprising. </p> <p> <img src="/content/binary/builder-fluent-builder-isomorphism.png" alt="isomorphism between Builder, Fluent Builder, and Immutable Fluent Builder."> </p> <p> Given an implementation that uses one of those three patterns, you can translate your design into one of the other options. This doesn't imply that each is of equal value. When it comes to composability, both versions of Fluent Builder are superior to the classic Builder pattern. </p> <h3 id="553fdf908eb84ccb86a7c7972d45bc77"> A critique of the Maze Builder example <a href="#553fdf908eb84ccb86a7c7972d45bc77" title="permalink">#</a> </h3> <p> In these articles, I usually first introduce the form presented in <a href="http://amzn.to/XBYukB">Design Patterns</a>. The code example given by the Gang of Four is, however, problematic. I'll start by pointing out the problems and then proceed to present a simpler, more useful example. </p> <p> The book presents an example centred on a <code>MazeBuilder</code> abstract class. The original example is in C++, but I here present my C# interpretation: </p> <p> <pre><span style="color:blue;">public</span>&nbsp;<span style="color:blue;">abstract</span>&nbsp;<span style="color:blue;">class</span>&nbsp;<span style="color:#2b91af;">MazeBuilder</span> { &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">public</span>&nbsp;<span style="color:blue;">virtual</span>&nbsp;<span style="color:blue;">void</span>&nbsp;<span style="font-weight:bold;color:#74531f;">BuildMaze</span>()&nbsp;{&nbsp;} &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">public</span>&nbsp;<span style="color:blue;">virtual</span>&nbsp;<span style="color:blue;">void</span>&nbsp;<span style="font-weight:bold;color:#74531f;">BuildRoom</span>(<span style="color:blue;">int</span>&nbsp;<span style="font-weight:bold;color:#1f377f;">room</span>)&nbsp;{&nbsp;} &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">public</span>&nbsp;<span style="color:blue;">virtual</span>&nbsp;<span style="color:blue;">void</span>&nbsp;<span style="font-weight:bold;color:#74531f;">BuildDoor</span>(<span style="color:blue;">int</span>&nbsp;<span style="font-weight:bold;color:#1f377f;">roomFrom</span>,&nbsp;<span style="color:blue;">int</span>&nbsp;<span style="font-weight:bold;color:#1f377f;">roomTo</span>)&nbsp;{&nbsp;} &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">public</span>&nbsp;<span style="color:blue;">virtual</span>&nbsp;<span style="color:#2b91af;">Maze</span>&nbsp;<span style="font-weight:bold;color:#74531f;">GetMaze</span>() &nbsp;&nbsp;&nbsp;&nbsp;{ &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="font-weight:bold;color:#8f08c4;">return</span>&nbsp;<span style="color:blue;">null</span>; &nbsp;&nbsp;&nbsp;&nbsp;} }</pre> </p> <p> As the book states, "the maze-building operations of MazeBuilder do nothing by default. They're not declared pure virtual to let derived classes override only those methods in which they're interested." This means that you could technically write a derived class that overrides only <code>BuildRoom</code>. That's unlikely to be useful, since <code>GetMaze</code> still returns <code>null</code>. </p> <p> Moreover, the presence of the <code>BuildMaze</code> method indicates <a href="https://en.wikipedia.org/wiki/Sequential_coupling">sequential coupling</a>. A client (a <em>Director</em>, in the pattern language of <em>Design Patterns</em>) is supposed to first call <code>BuildMaze</code> before calling any of the other methods. What happens if a client forgets to call <code>BuildMaze</code>? What happens if client code calls the method <em>after</em> some of the other methods. What happens if it calls it multiple times? </p> <p> Another issue with the sample code is that it's unclear how it accomplishes its stated goal of separating "the construction of a complex object from its representation." The <code>StandardMazeBuilder</code> presented seems tightly coupled to the <code>Maze</code> class to a degree where it's hard to see how to untangle the two. The book fails to make a compelling example by instead presenting a <code>CountingMazeBuilder</code> that never implements <code>GetMaze</code>. It never constructs the desired complex object. </p> <p> Don't interpret this critique as a sweeping dismissal of the pattern, or the book in general. As this article series implies, I've invested significant energy in it. I consider the book seminal, but we've learned much since its publication in 1994. A common experience is that not all of the patterns in the book are equally useful, and of those that are, some are useful for different reasons than the book gives. The Builder pattern is an example of that. </p> <p> The Builder pattern isn't useful only because it enables you to "separate the construction of a complex object from its representation." It's useful because it enables you to present an API that comes with good default behaviour, but which can be tweaked into multiple configurations. The pattern is useful even without polymorphism. </p> <h3 id="ed99bc3715f541be8b6b9239848395e3"> HTTP request Builder <a href="#ed99bc3715f541be8b6b9239848395e3" title="permalink">#</a> </h3> <p> The <a href="https://docs.microsoft.com/dotnet/api/system.net.http.httprequestmessage">HttpRequestMessage</a> class is a versatile API with good default behaviour, but it can be a bit awkward if you want to make an HTTP request with a body and particular headers. You can often get around the problem by using methods like <a href="https://docs.microsoft.com/dotnet/api/system.net.http.httpclient.postasync">PostAsync</a> on <a href="https://docs.microsoft.com/dotnet/api/system.net.http.httpclient">HttpClient</a>, but sometimes you need to drop down to <a href="https://docs.microsoft.com/dotnet/api/system.net.http.httpclient.sendasync">SendAsync</a>. When that happens, you need to build your own <code>HttpRequestMessage</code> objects. A Builder can encapsulate some of that work. </p> <p> <pre><span style="color:blue;">public</span>&nbsp;<span style="color:blue;">class</span>&nbsp;<span style="color:#2b91af;">HttpRequestMessageBuilder</span> { &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">private</span>&nbsp;<span style="color:blue;">readonly</span>&nbsp;<span style="color:#2b91af;">Uri</span>&nbsp;url; &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">private</span>&nbsp;<span style="color:blue;">object</span>?&nbsp;jsonBody; &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">public</span>&nbsp;<span style="color:#2b91af;">HttpRequestMessageBuilder</span>(<span style="color:blue;">string</span>&nbsp;<span style="font-weight:bold;color:#1f377f;">url</span>)&nbsp;:&nbsp;<span style="color:blue;">this</span>(<span style="color:blue;">new</span>&nbsp;<span style="color:#2b91af;">Uri</span>(<span style="font-weight:bold;color:#1f377f;">url</span>))&nbsp;{&nbsp;} &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">public</span>&nbsp;<span style="color:#2b91af;">HttpRequestMessageBuilder</span>(<span style="color:#2b91af;">Uri</span>&nbsp;<span style="font-weight:bold;color:#1f377f;">url</span>) &nbsp;&nbsp;&nbsp;&nbsp;{ &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">this</span>.url&nbsp;=&nbsp;<span style="font-weight:bold;color:#1f377f;">url</span>; &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;Method&nbsp;=&nbsp;<span style="color:#2b91af;">HttpMethod</span>.Get; &nbsp;&nbsp;&nbsp;&nbsp;} &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">public</span>&nbsp;<span style="color:#2b91af;">HttpMethod</span>&nbsp;Method&nbsp;{&nbsp;<span style="color:blue;">get</span>;&nbsp;<span style="color:blue;">set</span>;&nbsp;} &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">public</span>&nbsp;<span style="color:blue;">void</span>&nbsp;<span style="font-weight:bold;color:#74531f;">AddJsonBody</span>(<span style="color:blue;">object</span>&nbsp;<span style="font-weight:bold;color:#1f377f;">jsonBody</span>) &nbsp;&nbsp;&nbsp;&nbsp;{ &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">this</span>.jsonBody&nbsp;=&nbsp;<span style="font-weight:bold;color:#1f377f;">jsonBody</span>; &nbsp;&nbsp;&nbsp;&nbsp;} &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">public</span>&nbsp;<span style="color:#2b91af;">HttpRequestMessage</span>&nbsp;<span style="font-weight:bold;color:#74531f;">Build</span>() &nbsp;&nbsp;&nbsp;&nbsp;{ &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">var</span>&nbsp;<span style="font-weight:bold;color:#1f377f;">message</span>&nbsp;=&nbsp;<span style="color:blue;">new</span>&nbsp;<span style="color:#2b91af;">HttpRequestMessage</span>(Method,&nbsp;url); &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="font-weight:bold;color:#74531f;">BuildBody</span>(<span style="font-weight:bold;color:#1f377f;">message</span>); &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="font-weight:bold;color:#8f08c4;">return</span>&nbsp;<span style="font-weight:bold;color:#1f377f;">message</span>; &nbsp;&nbsp;&nbsp;&nbsp;} &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">private</span>&nbsp;<span style="color:blue;">void</span>&nbsp;<span style="font-weight:bold;color:#74531f;">BuildBody</span>(<span style="color:#2b91af;">HttpRequestMessage</span>&nbsp;<span style="font-weight:bold;color:#1f377f;">message</span>) &nbsp;&nbsp;&nbsp;&nbsp;{ &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="font-weight:bold;color:#8f08c4;">if</span>&nbsp;(jsonBody&nbsp;<span style="color:blue;">is</span>&nbsp;<span style="color:blue;">null</span>) &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="font-weight:bold;color:#8f08c4;">return</span>; &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">string</span>&nbsp;<span style="font-weight:bold;color:#1f377f;">json</span>&nbsp;=&nbsp;<span style="color:#2b91af;">JsonConvert</span>.<span style="color:#74531f;">SerializeObject</span>(jsonBody); &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="font-weight:bold;color:#1f377f;">message</span>.Content&nbsp;=&nbsp;<span style="color:blue;">new</span>&nbsp;<span style="color:#2b91af;">StringContent</span>(<span style="font-weight:bold;color:#1f377f;">json</span>); &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="font-weight:bold;color:#1f377f;">message</span>.Content.Headers.ContentType.MediaType&nbsp;=&nbsp;<span style="color:#a31515;">&quot;application/json&quot;</span>; &nbsp;&nbsp;&nbsp;&nbsp;} }</pre> </p> <p> Compared to <em>Design Patterns'</em> example, <code>HttpRequestMessageBuilder</code> isn't polymorphic. It doesn't inherit from a base class or implement an interface. As I pointed out in my critique of the <code>MazeBuilder</code> example, polymorphism doesn't seem to be the crux of the matter. You could easily introduce a base class or interface that defines the <code>Method</code>, <code>AddJsonBody</code>, and <code>Build</code> members, but what would be the point? Just like the <code>MazeBuilder</code> example fails to present a compelling <em>second</em> implementation, I can't think of another useful implementation of a hypothetical <code>IHttpRequestMessageBuilder</code> interface. </p> <p> Notice that I dropped the <em>Build</em> prefix from most of the Builder's members. Instead, I reserved the word <code>Build</code> for the method that actually creates the desired object. This is consistent with most modern Builder examples I've encountered. </p> <p> The <code>HttpRequestMessageBuilder</code> comes with a reasonable set of default behaviours. If you just want to make a <code>GET</code> request, you can easily do that: </p> <p> <pre><span style="color:blue;">var</span>&nbsp;<span style="font-weight:bold;color:#1f377f;">builder</span>&nbsp;=&nbsp;<span style="color:blue;">new</span>&nbsp;<span style="color:#2b91af;">HttpRequestMessageBuilder</span>(<span style="font-weight:bold;color:#1f377f;">url</span>); <span style="color:#2b91af;">HttpRequestMessage</span>&nbsp;<span style="font-weight:bold;color:#1f377f;">msg</span>&nbsp;=&nbsp;<span style="font-weight:bold;color:#1f377f;">builder</span>.<span style="font-weight:bold;color:#74531f;">Build</span>(); <span style="color:#2b91af;">HttpClient</span>&nbsp;<span style="font-weight:bold;color:#1f377f;">client</span>&nbsp;=&nbsp;<span style="font-weight:bold;color:#74531f;">GetClient</span>(); <span style="color:blue;">var</span>&nbsp;<span style="font-weight:bold;color:#1f377f;">response</span>&nbsp;=&nbsp;<span style="color:blue;">await</span>&nbsp;<span style="font-weight:bold;color:#1f377f;">client</span>.<span style="font-weight:bold;color:#74531f;">SendAsync</span>(<span style="font-weight:bold;color:#1f377f;">msg</span>);</pre> </p> <p> Since you only call the <code>builder</code>'s <code>Build</code> method, but never any of the other members, you get the default behaviour. A <code>GET</code> request with no body. </p> <p> Notice that the <code>HttpRequestMessageBuilder</code> protects its invariants. It follows the maxim that you should never be able to put an object into an invalid state. Contrary to <em>Design Patterns'</em> <code>StandardMazeBuilder</code>, it uses its constructors to enforce an invariant. Regardless of what sort of <code>HttpRequestMessage</code> you want to build, it must have a URL. Both constructor overloads require all clients to supply one. (In order to keep the code example as simple as possible, I've omitted all sorts of precondition checks, like checking that <code>url</code> isn't null, that it's a valid URL, and so on.) </p> <p> If you need to make a <code>POST</code> request with a JSON body, you can change the defaults: </p> <p> <pre><span style="color:blue;">var</span>&nbsp;<span style="font-weight:bold;color:#1f377f;">builder</span>&nbsp;=&nbsp;<span style="color:blue;">new</span>&nbsp;<span style="color:#2b91af;">HttpRequestMessageBuilder</span>(<span style="font-weight:bold;color:#1f377f;">url</span>); <span style="font-weight:bold;color:#1f377f;">builder</span>.Method&nbsp;=&nbsp;<span style="color:#2b91af;">HttpMethod</span>.Post; <span style="font-weight:bold;color:#1f377f;">builder</span>.<span style="font-weight:bold;color:#74531f;">AddJsonBody</span>(<span style="color:blue;">new</span>&nbsp;{ &nbsp;&nbsp;&nbsp;&nbsp;id&nbsp;=&nbsp;<span style="color:#2b91af;">Guid</span>.<span style="color:#74531f;">NewGuid</span>(), &nbsp;&nbsp;&nbsp;&nbsp;date&nbsp;=&nbsp;<span style="color:#a31515;">&quot;2020-03-22&nbsp;19:30:00&quot;</span>, &nbsp;&nbsp;&nbsp;&nbsp;name&nbsp;=&nbsp;<span style="color:#a31515;">&quot;Ælfgifu&quot;</span>, &nbsp;&nbsp;&nbsp;&nbsp;email&nbsp;=&nbsp;<span style="color:#a31515;">&quot;ælfgifu@example.net&quot;</span>, &nbsp;&nbsp;&nbsp;&nbsp;quantity&nbsp;=&nbsp;1&nbsp;}); <span style="color:#2b91af;">HttpRequestMessage</span>&nbsp;<span style="font-weight:bold;color:#1f377f;">msg</span>&nbsp;=&nbsp;<span style="font-weight:bold;color:#1f377f;">builder</span>.<span style="font-weight:bold;color:#74531f;">Build</span>(); <span style="color:#2b91af;">HttpClient</span>&nbsp;<span style="font-weight:bold;color:#1f377f;">client</span>&nbsp;=&nbsp;<span style="font-weight:bold;color:#74531f;">GetClient</span>(); <span style="color:blue;">var</span>&nbsp;<span style="font-weight:bold;color:#1f377f;">response</span>&nbsp;=&nbsp;<span style="color:blue;">await</span>&nbsp;<span style="font-weight:bold;color:#1f377f;">client</span>.<span style="font-weight:bold;color:#74531f;">SendAsync</span>(<span style="font-weight:bold;color:#1f377f;">msg</span>);</pre> </p> <p> Other combinations of <code>Method</code> and <code>AddJsonBody</code> are also possible. You could, for example, make a <code>DELETE</code> request without a body by only changing the <code>Method</code>. </p> <p> This incarnation of <code>HttpRequestMessageBuilder</code> is cumbersome to use. You must first create a <code>builder</code> object and then mutate it. Once you've invoked its <code>Build</code> method, you rarely need the object any longer, but the <code>builder</code> variable is still in scope. You can address those usage issues by refactoring a Builder to a Fluent Builder. </p> <h3 id="38b145cd45674bd989ebd37ca92b40f6"> HTTP request Fluent Builder <a href="#38b145cd45674bd989ebd37ca92b40f6" title="permalink">#</a> </h3> <p> In the Gang of Four Builder pattern, no methods return anything, except the method that creates the object you're building (<code>GetMaze</code> in the <code>MazeBuilder</code> example, <code>Build</code> in the <code>HttpRequestMessageBuilder</code> example). It's always possible to refactor such a Builder so that the <code>void</code> methods return something. They can always return the object itself: </p> <p> <pre><span style="color:blue;">public</span>&nbsp;<span style="color:#2b91af;">HttpMethod</span>&nbsp;Method&nbsp;{&nbsp;<span style="color:blue;">get</span>;&nbsp;<span style="color:blue;">private</span>&nbsp;<span style="color:blue;">set</span>;&nbsp;} <span style="color:blue;">public</span>&nbsp;<span style="color:#2b91af;">HttpRequestMessageBuilder</span>&nbsp;<span style="font-weight:bold;color:#74531f;">WithMethod</span>(<span style="color:#2b91af;">HttpMethod</span>&nbsp;<span style="font-weight:bold;color:#1f377f;">newMethod</span>) { &nbsp;&nbsp;&nbsp;&nbsp;Method&nbsp;=&nbsp;<span style="font-weight:bold;color:#1f377f;">newMethod</span>; &nbsp;&nbsp;&nbsp;&nbsp;<span style="font-weight:bold;color:#8f08c4;">return</span>&nbsp;<span style="color:blue;">this</span>; } <span style="color:blue;">public</span>&nbsp;<span style="color:#2b91af;">HttpRequestMessageBuilder</span>&nbsp;<span style="font-weight:bold;color:#74531f;">AddJsonBody</span>(<span style="color:blue;">object</span>&nbsp;<span style="font-weight:bold;color:#1f377f;">jsonBody</span>) { &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">this</span>.jsonBody&nbsp;=&nbsp;<span style="font-weight:bold;color:#1f377f;">jsonBody</span>; &nbsp;&nbsp;&nbsp;&nbsp;<span style="font-weight:bold;color:#8f08c4;">return</span>&nbsp;<span style="color:blue;">this</span>; }</pre> </p> <p> Changing <code>AddJsonBody</code> is as easy as changing its return type and returning <code>this</code>. Refactoring the <code>Method</code> property is a bit more involved. It's a language feature of C# (and a few other languages) that classes can have properties, so this concern isn't general. In languages without properties, things are simpler. In C#, however, I chose to make the property setter private and instead add a method that returns <code>HttpRequestMessageBuilder</code>. Perhaps it's a little confusing that the name of the method includes the word <em>method</em>, but keep in mind that the method in question is an HTTP method. </p> <p> You can now create a <code>GET</code> request with a one-liner: </p> <p> <pre><span style="color:#2b91af;">HttpRequestMessage</span>&nbsp;<span style="font-weight:bold;color:#1f377f;">msg</span>&nbsp;=&nbsp;<span style="color:blue;">new</span>&nbsp;<span style="color:#2b91af;">HttpRequestMessageBuilder</span>(<span style="font-weight:bold;color:#1f377f;">url</span>).<span style="font-weight:bold;color:#74531f;">Build</span>();</pre> </p> <p> You don't have to declare any <code>builder</code> variable to mutate. Even when you need to change the defaults, you can just start with a builder and keep on chaining method calls: </p> <p> <pre><span style="color:#2b91af;">HttpRequestMessage</span>&nbsp;<span style="font-weight:bold;color:#1f377f;">msg</span>&nbsp;=&nbsp;<span style="color:blue;">new</span>&nbsp;<span style="color:#2b91af;">HttpRequestMessageBuilder</span>(<span style="font-weight:bold;color:#1f377f;">url</span>) &nbsp;&nbsp;&nbsp;&nbsp;.<span style="font-weight:bold;color:#74531f;">WithMethod</span>(<span style="color:#2b91af;">HttpMethod</span>.Post) &nbsp;&nbsp;&nbsp;&nbsp;.<span style="font-weight:bold;color:#74531f;">AddJsonBody</span>(<span style="color:blue;">new</span>&nbsp;{ &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;id&nbsp;=&nbsp;<span style="color:#2b91af;">Guid</span>.<span style="color:#74531f;">NewGuid</span>(), &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;date&nbsp;=&nbsp;<span style="color:#a31515;">&quot;2020-03-22&nbsp;19:30:00&quot;</span>, &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;name&nbsp;=&nbsp;<span style="color:#a31515;">&quot;Ælfgifu&quot;</span>, &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;email&nbsp;=&nbsp;<span style="color:#a31515;">&quot;ælfgifu@example.net&quot;</span>, &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;quantity&nbsp;=&nbsp;1&nbsp;}) &nbsp;&nbsp;&nbsp;&nbsp;.<span style="font-weight:bold;color:#74531f;">Build</span>();</pre> </p> <p> This creates a <code>POST</code> request with a JSON message body. </p> <p> We can call this pattern <em>Fluent Builder</em> because this version of the Builder pattern has a <a href="https://www.martinfowler.com/bliki/FluentInterface.html">Fluent Interface</a>. </p> <p> This usually works well enough in practice, but is vulnerable to <a href="https://en.wikipedia.org/wiki/Aliasing_(computing)">aliasing</a>. What happens if you reuse an <code>HttpRequestMessageBuilder</code> object? </p> <p> <pre><span style="color:blue;">var</span>&nbsp;<span style="font-weight:bold;color:#1f377f;">builder</span>&nbsp;=&nbsp;<span style="color:blue;">new</span>&nbsp;<span style="color:#2b91af;">HttpRequestMessageBuilder</span>(<span style="font-weight:bold;color:#1f377f;">url</span>); <span style="color:blue;">var</span>&nbsp;<span style="font-weight:bold;color:#1f377f;">deleteMsg</span>&nbsp;=&nbsp;<span style="font-weight:bold;color:#1f377f;">builder</span>.<span style="font-weight:bold;color:#74531f;">WithMethod</span>(<span style="color:#2b91af;">HttpMethod</span>.Delete).<span style="font-weight:bold;color:#74531f;">Build</span>(); <span style="color:blue;">var</span>&nbsp;<span style="font-weight:bold;color:#1f377f;">getMsg</span>&nbsp;=&nbsp;<span style="font-weight:bold;color:#1f377f;">builder</span>.<span style="font-weight:bold;color:#74531f;">Build</span>();</pre> </p> <p> As the variable names imply, the programmer responsible for these three lines of code incorrectly believed that without the call to <code>WithMethod</code>, the <code>builder</code> will use its default behaviour when <code>Build</code> is called. The previous line of code, however, mutated the <code>builder</code> object. Its <code>Method</code> property remains <code>HttpMethod.Delete</code> until another line of code changes it! </p> <h3 id="a75c7962ece449f6b6161fe6ae7beb1e"> HTTP request Immutable Fluent Builder <a href="#a75c7962ece449f6b6161fe6ae7beb1e" title="permalink">#</a> </h3> <p> You can disarm the aliasing booby trap by making the Fluent Builder immutable. A good first step in that refactoring is making sure that all class fields are <code>readonly</code>: </p> <p> <pre><span style="color:blue;">private</span>&nbsp;<span style="color:blue;">readonly</span>&nbsp;<span style="color:#2b91af;">Uri</span>&nbsp;url; <span style="color:blue;">private</span>&nbsp;<span style="color:blue;">readonly</span>&nbsp;<span style="color:blue;">object</span>?&nbsp;jsonBody;</pre> </p> <p> The <code>url</code> field was already marked <code>readonly</code>, so the change only applies to the <code>jsonBody</code> field. In addition to the class fields, don't forget any automatic properties: </p> <p> <pre><span style="color:blue;">public</span>&nbsp;<span style="color:#2b91af;">HttpMethod</span>&nbsp;Method&nbsp;{&nbsp;<span style="color:blue;">get</span>;&nbsp;}</pre> </p> <p> The <code>HttpMethod</code> property previously had a <code>private</code> setter, but this is now gone. It's also strictly read only. </p> <p> Now that all data is read only, the only way you can 'change' values is via a constructor. Add a constructor overload that receives all data and chain the other constructors into it: </p> <p> <pre><span style="color:blue;">public</span>&nbsp;<span style="color:#2b91af;">HttpRequestMessageBuilder</span>(<span style="color:blue;">string</span>&nbsp;<span style="font-weight:bold;color:#1f377f;">url</span>)&nbsp;:&nbsp;<span style="color:blue;">this</span>(<span style="color:blue;">new</span>&nbsp;<span style="color:#2b91af;">Uri</span>(<span style="font-weight:bold;color:#1f377f;">url</span>))&nbsp;{&nbsp;} <span style="color:blue;">public</span>&nbsp;<span style="color:#2b91af;">HttpRequestMessageBuilder</span>(<span style="color:#2b91af;">Uri</span>&nbsp;<span style="font-weight:bold;color:#1f377f;">url</span>)&nbsp;:&nbsp;<span style="color:blue;">this</span>(<span style="font-weight:bold;color:#1f377f;">url</span>,&nbsp;<span style="color:#2b91af;">HttpMethod</span>.Get,&nbsp;<span style="color:blue;">null</span>)&nbsp;{&nbsp;} <span style="color:blue;">private</span>&nbsp;<span style="color:#2b91af;">HttpRequestMessageBuilder</span>(<span style="color:#2b91af;">Uri</span>&nbsp;<span style="font-weight:bold;color:#1f377f;">url</span>,&nbsp;<span style="color:#2b91af;">HttpMethod</span>&nbsp;<span style="font-weight:bold;color:#1f377f;">method</span>,&nbsp;<span style="color:blue;">object</span>?&nbsp;<span style="font-weight:bold;color:#1f377f;">jsonBody</span>) { &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">this</span>.url&nbsp;=&nbsp;<span style="font-weight:bold;color:#1f377f;">url</span>; &nbsp;&nbsp;&nbsp;&nbsp;Method&nbsp;=&nbsp;<span style="font-weight:bold;color:#1f377f;">method</span>; &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">this</span>.jsonBody&nbsp;=&nbsp;<span style="font-weight:bold;color:#1f377f;">jsonBody</span>; }</pre> </p> <p> I'm usually not keen on allowing <code>null</code> arguments, but I made the all-encompassing constructor <code>private</code>. In that way, at least no client code gets the wrong idea. </p> <p> The optional modification methods can now only do one thing: return a new object: </p> <p> <pre><span style="color:blue;">public</span>&nbsp;<span style="color:#2b91af;">HttpRequestMessageBuilder</span>&nbsp;<span style="font-weight:bold;color:#74531f;">WithMethod</span>(<span style="color:#2b91af;">HttpMethod</span>&nbsp;<span style="font-weight:bold;color:#1f377f;">newMethod</span>) { &nbsp;&nbsp;&nbsp;&nbsp;<span style="font-weight:bold;color:#8f08c4;">return</span>&nbsp;<span style="color:blue;">new</span>&nbsp;<span style="color:#2b91af;">HttpRequestMessageBuilder</span>(url,&nbsp;<span style="font-weight:bold;color:#1f377f;">newMethod</span>,&nbsp;jsonBody); } <span style="color:blue;">public</span>&nbsp;<span style="color:#2b91af;">HttpRequestMessageBuilder</span>&nbsp;<span style="font-weight:bold;color:#74531f;">AddJsonBody</span>(<span style="color:blue;">object</span>&nbsp;<span style="font-weight:bold;color:#1f377f;">jsonBody</span>) { &nbsp;&nbsp;&nbsp;&nbsp;<span style="font-weight:bold;color:#8f08c4;">return</span>&nbsp;<span style="color:blue;">new</span>&nbsp;<span style="color:#2b91af;">HttpRequestMessageBuilder</span>(url,&nbsp;Method,&nbsp;<span style="font-weight:bold;color:#1f377f;">jsonBody</span>); }</pre> </p> <p> The client code looks the same as before, but now you no longer have an aliasing problem: </p> <p> <pre><span style="color:blue;">var</span>&nbsp;<span style="font-weight:bold;color:#1f377f;">builder</span>&nbsp;=&nbsp;<span style="color:blue;">new</span>&nbsp;<span style="color:#2b91af;">HttpRequestMessageBuilder</span>(<span style="font-weight:bold;color:#1f377f;">url</span>); <span style="color:blue;">var</span>&nbsp;<span style="font-weight:bold;color:#1f377f;">deleteMsg</span>&nbsp;=&nbsp;<span style="font-weight:bold;color:#1f377f;">builder</span>.<span style="font-weight:bold;color:#74531f;">WithMethod</span>(<span style="color:#2b91af;">HttpMethod</span>.Delete).<span style="font-weight:bold;color:#74531f;">Build</span>(); <span style="color:blue;">var</span>&nbsp;<span style="font-weight:bold;color:#1f377f;">getMsg</span>&nbsp;=&nbsp;<span style="font-weight:bold;color:#1f377f;">builder</span>.<span style="font-weight:bold;color:#74531f;">Build</span>();</pre> </p> <p> Now <code>deleteMsg</code> represents a <code>Delete</code> request, and <code>getMsg</code> truly represents a <code>GET</code> request. </p> <p> Since this variation of the Fluent Builder pattern is immutable, it's natural to call it an <em>Immutable Fluent Builder</em>. </p> <p> You've now seen how to refactor from Builder via Fluent Builder to Immutable Fluent Builder. If these three pattern variations are truly isomorphic, it should also be possible to move in the other direction. I'll leave it as an exercise for the reader to do this with the HTTP request Builder example. Instead, I will briefly discuss another example that starts at the Fluent Builder pattern. </p> <h3 id="87464a8b3f4d4922b3929c50e098c344"> Test Data Fluent Builder <a href="#87464a8b3f4d4922b3929c50e098c344" title="permalink">#</a> </h3> <p> A prominent example of the Fluent Builder pattern would be the set of all <a href="http://www.natpryce.com/articles/000714.html">Test Data Builders</a>. I'm going to use the example I've <a href="/2017/08/15/test-data-builders-in-c">already covered</a>. You can visit the previous article for all details, but in summary, you can, for example, write code like this: </p> <p> <pre><span style="color:#2b91af;">Address</span>&nbsp;<span style="font-weight:bold;color:#1f377f;">address</span>&nbsp;=&nbsp;<span style="color:blue;">new</span>&nbsp;<span style="color:#2b91af;">AddressBuilder</span>().<span style="font-weight:bold;color:#74531f;">WithCity</span>(<span style="color:#a31515;">&quot;Paris&quot;</span>).<span style="font-weight:bold;color:#74531f;">Build</span>();</pre> </p> <p> This creates an <code>Address</code> object with the <code>City</code> property set to <code>"Paris"</code>. The <code>Address</code> class comes with other properties. You can trust that the <code>AddressBuilder</code> gave them values, but you don't know what they are. You can use this pattern in unit tests when you need an <code>Address</code> in <a href="https://en.wikipedia.org/wiki/Paris">Paris</a>, but you don't care about any of the other data. </p> <p> In my previous article, I implemented <code>AddressBuilder</code> as a Fluent Builder. I did that in order to stay as true to <a href="http://www.natpryce.com">Nat Pryce</a>'s original example as possible. Whenever I use the Test Data Builder pattern in earnest, however, I use the immutable variation so that I avoid the aliasing issue. </p> <h3 id="4274fe6c008e41bd8d4e596b9cc11762"> Test Data Builder as a Gang-of-Four Builder <a href="#4274fe6c008e41bd8d4e596b9cc11762" title="permalink">#</a> </h3> <p> You can easily refactor a typical Test Data Builder like <code>AddressBuilder</code> to a shape more reminiscent of the Builder pattern presented in <em>Design Patterns</em>. Apart from the <code>Build</code> method that produces the object being built, change all other methods to <code>void</code> methods: </p> <p> <pre><span style="color:blue;">public</span>&nbsp;<span style="color:blue;">class</span>&nbsp;<span style="color:#2b91af;">AddressBuilder</span> { &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">private</span>&nbsp;<span style="color:blue;">string</span>&nbsp;street; &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">private</span>&nbsp;<span style="color:blue;">string</span>&nbsp;city; &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">private</span>&nbsp;<span style="color:#2b91af;">PostCode</span>&nbsp;postCode; &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">public</span>&nbsp;<span style="color:#2b91af;">AddressBuilder</span>() &nbsp;&nbsp;&nbsp;&nbsp;{ &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">this</span>.street&nbsp;=&nbsp;<span style="color:#a31515;">&quot;&quot;</span>; &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">this</span>.city&nbsp;=&nbsp;<span style="color:#a31515;">&quot;&quot;</span>; &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">this</span>.postCode&nbsp;=&nbsp;<span style="color:blue;">new</span>&nbsp;<span style="color:#2b91af;">PostCodeBuilder</span>().<span style="font-weight:bold;color:#74531f;">Build</span>(); &nbsp;&nbsp;&nbsp;&nbsp;} &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">public</span>&nbsp;<span style="color:blue;">void</span>&nbsp;<span style="font-weight:bold;color:#74531f;">WithStreet</span>(<span style="color:blue;">string</span>&nbsp;<span style="font-weight:bold;color:#1f377f;">newStreet</span>) &nbsp;&nbsp;&nbsp;&nbsp;{ &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">this</span>.street&nbsp;=&nbsp;<span style="font-weight:bold;color:#1f377f;">newStreet</span>; &nbsp;&nbsp;&nbsp;&nbsp;} &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">public</span>&nbsp;<span style="color:blue;">void</span>&nbsp;<span style="font-weight:bold;color:#74531f;">WithCity</span>(<span style="color:blue;">string</span>&nbsp;<span style="font-weight:bold;color:#1f377f;">newCity</span>) &nbsp;&nbsp;&nbsp;&nbsp;{ &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">this</span>.city&nbsp;=&nbsp;<span style="font-weight:bold;color:#1f377f;">newCity</span>; &nbsp;&nbsp;&nbsp;&nbsp;} &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">public</span>&nbsp;<span style="color:blue;">void</span>&nbsp;<span style="font-weight:bold;color:#74531f;">WithPostCode</span>(<span style="color:#2b91af;">PostCode</span>&nbsp;<span style="font-weight:bold;color:#1f377f;">newPostCode</span>) &nbsp;&nbsp;&nbsp;&nbsp;{ &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">this</span>.postCode&nbsp;=&nbsp;<span style="font-weight:bold;color:#1f377f;">newPostCode</span>; &nbsp;&nbsp;&nbsp;&nbsp;} &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">public</span>&nbsp;<span style="color:blue;">void</span>&nbsp;<span style="font-weight:bold;color:#74531f;">WithNoPostcode</span>() &nbsp;&nbsp;&nbsp;&nbsp;{ &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">this</span>.postCode&nbsp;=&nbsp;<span style="color:blue;">new</span>&nbsp;<span style="color:#2b91af;">PostCode</span>(); &nbsp;&nbsp;&nbsp;&nbsp;} &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">public</span>&nbsp;<span style="color:#2b91af;">Address</span>&nbsp;<span style="font-weight:bold;color:#74531f;">Build</span>() &nbsp;&nbsp;&nbsp;&nbsp;{ &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="font-weight:bold;color:#8f08c4;">return</span>&nbsp;<span style="color:blue;">new</span>&nbsp;<span style="color:#2b91af;">Address</span>(<span style="color:blue;">this</span>.street,&nbsp;<span style="color:blue;">this</span>.city,&nbsp;<span style="color:blue;">this</span>.postCode); &nbsp;&nbsp;&nbsp;&nbsp;} }</pre> </p> <p> You can still build a test address in Paris, but it's now more inconvenient. </p> <p> <pre><span style="color:blue;">var</span>&nbsp;<span style="font-weight:bold;color:#1f377f;">addressBuilder</span>&nbsp;=&nbsp;<span style="color:blue;">new</span>&nbsp;<span style="color:#2b91af;">AddressBuilder</span>(); <span style="font-weight:bold;color:#1f377f;">addressBuilder</span>.<span style="font-weight:bold;color:#74531f;">WithCity</span>(<span style="color:#a31515;">&quot;Paris&quot;</span>); <span style="color:#2b91af;">Address</span>&nbsp;<span style="font-weight:bold;color:#1f377f;">address</span>&nbsp;=&nbsp;<span style="font-weight:bold;color:#1f377f;">addressBuilder</span>.<span style="font-weight:bold;color:#74531f;">Build</span>();</pre> </p> <p> You can still use multiple Test Data Builders to build more complex test data, but the classic Builder pattern doesn't compose well. </p> <p> <pre><span style="color:blue;">var</span>&nbsp;<span style="font-weight:bold;color:#1f377f;">invoiceBuilder</span>&nbsp;=&nbsp;<span style="color:blue;">new</span>&nbsp;<span style="color:#2b91af;">InvoiceBuilder</span>(); <span style="color:blue;">var</span>&nbsp;<span style="font-weight:bold;color:#1f377f;">recipientBuilder</span>&nbsp;=&nbsp;<span style="color:blue;">new</span>&nbsp;<span style="color:#2b91af;">RecipientBuilder</span>(); <span style="color:blue;">var</span>&nbsp;<span style="font-weight:bold;color:#1f377f;">addressBuilder</span>&nbsp;=&nbsp;<span style="color:blue;">new</span>&nbsp;<span style="color:#2b91af;">AddressBuilder</span>(); <span style="font-weight:bold;color:#1f377f;">addressBuilder</span>.<span style="font-weight:bold;color:#74531f;">WithNoPostcode</span>(); <span style="font-weight:bold;color:#1f377f;">recipientBuilder</span>.<span style="font-weight:bold;color:#74531f;">WithAddress</span>(<span style="font-weight:bold;color:#1f377f;">addressBuilder</span>.<span style="font-weight:bold;color:#74531f;">Build</span>()); <span style="font-weight:bold;color:#1f377f;">invoiceBuilder</span>.<span style="font-weight:bold;color:#74531f;">WithRecipient</span>(<span style="font-weight:bold;color:#1f377f;">recipientBuilder</span>.<span style="font-weight:bold;color:#74531f;">Build</span>()); <span style="color:#2b91af;">Invoice</span>&nbsp;<span style="font-weight:bold;color:#1f377f;">invoice</span>&nbsp;=&nbsp;<span style="font-weight:bold;color:#1f377f;">invoiceBuilder</span>.<span style="font-weight:bold;color:#74531f;">Build</span>();</pre> </p> <p> These seven lines of code creates an <code>Invoice</code> object with a address without a post code. Compare that with the Fluent Builder <a href="/2017/08/15/test-data-builders-in-c#de2e6fb74f6f4319a0fef86dcd9b839e">example in the previous article</a>. This is a clear example that while the variations are isomorphic, they aren't equally useful. The classic Builder pattern isn't as practical as one of the Fluent variations. </p> <p> You might protest that this variation of <code>AddressBuilder</code>, <code>InvoiceBuilder</code>, etcetera isn't equivalent to the Builder pattern. After all, the Builder shown in <em>Design Patterns</em> is polymorphic. That's really not an issue, though. Just extract an interface from the concrete builder: </p> <p> <pre><span style="color:blue;">public</span>&nbsp;<span style="color:blue;">interface</span>&nbsp;<span style="color:#2b91af;">IAddressBuilder</span> { &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:#2b91af;">Address</span>&nbsp;<span style="font-weight:bold;color:#74531f;">Build</span>(); &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">void</span>&nbsp;<span style="font-weight:bold;color:#74531f;">WithCity</span>(<span style="color:blue;">string</span>&nbsp;<span style="font-weight:bold;color:#1f377f;">newCity</span>); &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">void</span>&nbsp;<span style="font-weight:bold;color:#74531f;">WithNoPostcode</span>(); &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">void</span>&nbsp;<span style="font-weight:bold;color:#74531f;">WithPostCode</span>(<span style="color:#2b91af;">PostCode</span>&nbsp;<span style="font-weight:bold;color:#1f377f;">newPostCode</span>); &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">void</span>&nbsp;<span style="font-weight:bold;color:#74531f;">WithStreet</span>(<span style="color:blue;">string</span>&nbsp;<span style="font-weight:bold;color:#1f377f;">newStreet</span>); }</pre> </p> <p> Make the concrete class implement the interface: </p> <p> <pre><span style="color:blue;">public</span>&nbsp;<span style="color:blue;">class</span>&nbsp;<span style="color:#2b91af;">AddressBuilder</span>&nbsp;:&nbsp;<span style="color:#2b91af;">IAddressBuilder</span></pre> </p> <p> You could argue that this adds no value. You'd be right. This goes contrary to the <a href="http://www.codemanship.co.uk/parlezuml/blog/?postid=934">Reused Abstractions Principle</a>. I think that the same criticism applies to <em>Design Patterns</em>' original description of the pattern, as I've already pointed out. The utility in the pattern comes from how it gives client code good defaults that it can then tweak as necessary. </p> <h3 id="a1e866bafec74def9a66f5ba96a0cca4"> Summary <a href="#a1e866bafec74def9a66f5ba96a0cca4" title="permalink">#</a> </h3> <p> The Builder pattern was originally described in <em>Design Patterns</em>. Later, smart people like Nat Pryce figured out that by letting each mutating operation return the (mutated) Builder, such a Fluent API offered superior composability. A further improvement to the Fluent Builder pattern makes the Builder immutable in order to avoid aliasing issues. </p> <p> All three variations are isomorphic. Work that one of these variations afford is also afforded by the other variations. </p> <p> On the other hand, the variations aren't equally useful. Fluent APIs offer superior composability. </p> <p> <strong>Next:</strong> <a href="/2018/05/22/church-encoding">Church encoding</a>. </p> </div> <div id="comments"> <hr> <h2 id="comments-header"> Comments </h2> <div class="comment" id="f3f59d590234452aa6a9cd7ba56779f0"> <div class="comment-author"><a href="https://about.me/tysonwilliams">Tyson Williams</a></div> <div class="comment-content"> <blockquote> <p> You can now[, with the fluent builder implementation,] create a <code>GET</code> request with a one-liner: </p> <p> <pre><span style="color:#2b91af;">HttpRequestMessage</span>&nbsp;<span style="font-weight:bold;color:#1f377f;">msg</span>&nbsp;=&nbsp;<span style="color:blue;">new</span>&nbsp;<span style="color:#2b91af;">HttpRequestMessageBuilder</span>(<span style="font-weight:bold;color:#1f377f;">url</span>).<span style="font-weight:bold;color:#74531f;">Build</span>();</pre> </p> </blockquote> <p> It is also possible to write that one-liner with the original (non-fluent) builder implementation. Did you mean to show how it is possible with the fluent builder implementation to create a <code>DELETE</code> request with a one-liner? You have such an example two code blocks later. </p> </div> <div class="comment-date">2020-02-25 02:18 UTC</div> </div> <div class="comment" id="c12cb112352645a293bc5ecaf7d9c9aa"> <div class="comment-author"><a href="/">Mark Seemann</a></div> <div class="comment-content"> <p> Tyson, you are, of course, right. The default behaviour could also have been a one-liner with the non-fluent design. Every other configuration, however, can't be a one-liner with the Gang-of-Four pattern, while it can in the Fluent guise. </p> </div> <div class="comment-date">2020-02-25 6:44 UTC</div> </div> <div class="comment" id="ecec868120f644c28381b188ee2e75e4"> <div class="comment-author"><a href="https://about.me/tysonwilliams">Tyson Williams</a></div> <div class="comment-content"> <p> Among the example uses of your <code>HttpRequestMessageBuilder</code>, I see three HTTP verbs used: <code>GET</code>, <code>DELETE</code>, and <code>POST</code>. Furthermore, a body is added if and only if the method is <code>POST</code>. This matches my expectations gained from my limited experience doing web programming. If a <code>GET</code> or <code>DELETE</code> request had a body or if a <code>POST</code> request did not have a body, then I would suspect that such behavior was a bug. </p> <p> For the sake of a question that I would like to ask, let's suppose that a body must be added if and only if the method is <code>POST</code>. Under this assumption, <code>HttpRequestMessageBuilder</code> can create invalid messages. For example, it can create a <code>GET</code> request with a body, and it can create a <code>POST</code> request without a body. Under this assumption, how would you modify your design so that only valid messages can be created? </p> </div> <div class="comment-date">2020-02-25 14:34 UTC</div> </div> <div class="comment" id="1a3c2d6c7d484c5da92e49ce81c8755d"> <div class="comment-author"><a href="/">Mark Seemann</a></div> <div class="comment-content"> <p> Tyson, thank you for another inspiring question! It gives me a good motivation to write about polymorphic Builders. I'll try to address this question in a future article. </p> </div> <div class="comment-date">2020-03-02 8:40 UTC</div> </div> <div class="comment" id="484b7f2bd2714a2d8c08adece0955668"> <div class="comment-author"><a href="/">Mark Seemann</a></div> <div class="comment-content"> <p> Tyson, I've now attempted to answer your question in <a href="/2020/03/09/polymorphic-builder">a new article</a>. </p> </div> <div class="comment-date">2020-03-09 6:53 UTC</div> </div> </div><hr> This blog is totally free, but if you like it, please consider <a href="https://blog.ploeh.dk/support">supporting it</a>. Mark Seemann https://blog.ploeh.dk/2020/02/10/builder-isomorphisms Non-exceptional averages https://blog.ploeh.dk/2020/02/03/non-exceptional-averages/ Mon, 03 Feb 2020 06:38:00 UTC <div id="post"> <p> <em>How do you code without exceptions? Here's one example.</em> </p> <p> Encouraging object-oriented programmers to <a href="https://hackernoon.com/the-throw-keyword-was-a-mistake-l9e532di">avoid throwing exceptions</a> is as fun as telling them to renounce null references. To be fair, exception-throwing is such an ingrained feature of C#, Java, C++, etcetera that it can be hard to see how to do without it. </p> <p> To be clear, I don't insist that you pretend that exceptions don't exist in languages that have them. I'm also <a href="https://eiriktsarpalis.wordpress.com/2017/02/19/youre-better-off-using-exceptions">not advocating that you catch all exceptions in order to resurface them as railway-oriented programming</a>. On the other hand, I do endorse the generally good advice that you shouldn't use exceptions for <a href="https://en.wikipedia.org/wiki/Control_flow">control flow</a>. </p> <p> What can you do instead? Despite <a href="https://fsharpforfunandprofit.com/posts/against-railway-oriented-programming">all the warnings against railway-oriented programming</a>, <a href="/2018/06/11/church-encoded-either">Either</a> is still a good choice for a certain kind of control flow. Exceptions are for <em>exceptional</em> situations, such as network partitions, running out of memory, disk failures, and so on. Many run-time errors are both foreseeable and preventable. Prefer code that prevents errors. </p> <p> There's a few ways you can do that. One of them is to protect invariants by enforcing pre-conditions. If you have a static type system, you can use the type system to prevent errors. </p> <h3 id="ccb791521ac0417f870a2fe4dac946c7"> Average duration <a href="#ccb791521ac0417f870a2fe4dac946c7" title="permalink">#</a> </h3> <p> How would you calculate the average of a set of durations? You might, for example, <a href="/2017/06/27/pure-times">need to calculate average duration of message handling for a polling consumer</a>. C# offers many built-in overloads of the <a href="https://docs.microsoft.com/dotnet/api/system.linq.enumerable.average">Average</a> extension method, but none that calculates the average of <a href="https://docs.microsoft.com/dotnet/api/system.timespan">TimeSpan</a> values. </p> <p> How would you write that method yourself? </p> <p> It's not a trick question. </p> <p> Based on my experience coaching development teams, this is a representative example: </p> <p> <pre><span style="color:blue;">public</span>&nbsp;<span style="color:blue;">static</span>&nbsp;<span style="color:#2b91af;">TimeSpan</span>&nbsp;<span style="color:#74531f;">Average</span>(<span style="color:blue;">this</span>&nbsp;<span style="color:#2b91af;">IEnumerable</span>&lt;<span style="color:#2b91af;">TimeSpan</span>&gt;&nbsp;<span style="font-weight:bold;color:#1f377f;">timeSpans</span>) { &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">var</span>&nbsp;<span style="font-weight:bold;color:#1f377f;">sum</span>&nbsp;=&nbsp;<span style="color:#2b91af;">TimeSpan</span>.Zero; &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">var</span>&nbsp;<span style="font-weight:bold;color:#1f377f;">count</span>&nbsp;=&nbsp;0; &nbsp;&nbsp;&nbsp;&nbsp;<span style="font-weight:bold;color:#8f08c4;">foreach</span>&nbsp;(<span style="color:blue;">var</span>&nbsp;<span style="font-weight:bold;color:#1f377f;">ts</span>&nbsp;<span style="font-weight:bold;color:#8f08c4;">in</span>&nbsp;<span style="font-weight:bold;color:#1f377f;">timeSpans</span>) &nbsp;&nbsp;&nbsp;&nbsp;{ &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="font-weight:bold;color:#1f377f;">sum</span>&nbsp;<span style="font-weight:bold;color:#74531f;">+=</span>&nbsp;<span style="font-weight:bold;color:#1f377f;">ts</span>; &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="font-weight:bold;color:#1f377f;">count</span>++; &nbsp;&nbsp;&nbsp;&nbsp;} &nbsp;&nbsp;&nbsp;&nbsp;<span style="font-weight:bold;color:#8f08c4;">return</span>&nbsp;<span style="font-weight:bold;color:#1f377f;">sum</span>&nbsp;<span style="font-weight:bold;color:#74531f;">/</span>&nbsp;<span style="font-weight:bold;color:#1f377f;">count</span>; }</pre> </p> <p> This gets the job done in most situations, but it has two error modes. It doesn't work if <code>timeSpans</code> is empty, and it doesn't work if it's infinite. </p> <p> When the input collection is empty, you'll be trying to divide by zero, which isn't allowed. How do you deal with that? Most programmers I've met just shrug and say: <em>don't call the method with an empty collection.</em> Apparently, it's your responsibility as the caller. You have to memorise that this particular <code>Average</code> method has that particular precondition. </p> <p> I don't think that's a professional position. This puts the burden on client developers. In a world like that, you have to learn by rote the preconditions of thousands of APIs. </p> <p> What can you do? You could add a <a href="https://en.wikipedia.org/wiki/Guard_(computer_science)">Guard Clause</a> to the method. </p> <h3 id="38f629930c7845c0af1c50c586dfcb82"> Guard Clause <a href="#38f629930c7845c0af1c50c586dfcb82" title="permalink">#</a> </h3> <p> Adding a Guard Clause doesn't really make the method much easier to reason about for client developers, but at least it protects an invariant. </p> <p> <pre><span style="color:blue;">public</span>&nbsp;<span style="color:blue;">static</span>&nbsp;<span style="color:#2b91af;">TimeSpan</span>&nbsp;<span style="color:#74531f;">Average</span>(<span style="color:blue;">this</span>&nbsp;<span style="color:#2b91af;">IEnumerable</span>&lt;<span style="color:#2b91af;">TimeSpan</span>&gt;&nbsp;<span style="font-weight:bold;color:#1f377f;">timeSpans</span>) { &nbsp;&nbsp;&nbsp;&nbsp;<span style="font-weight:bold;color:#8f08c4;">if</span>&nbsp;(!<span style="font-weight:bold;color:#1f377f;">timeSpans</span>.<span style="font-weight:bold;color:#74531f;">Any</span>()) &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="font-weight:bold;color:#8f08c4;">throw</span>&nbsp;<span style="color:blue;">new</span>&nbsp;<span style="color:#2b91af;">ArgumentOutOfRangeException</span>( &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">nameof</span>(<span style="font-weight:bold;color:#1f377f;">timeSpans</span>), &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:#a31515;">&quot;Can&#39;t&nbsp;calculate&nbsp;the&nbsp;average&nbsp;of&nbsp;an&nbsp;empty&nbsp;collection.&quot;</span>); &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">var</span>&nbsp;<span style="font-weight:bold;color:#1f377f;">sum</span>&nbsp;=&nbsp;<span style="color:#2b91af;">TimeSpan</span>.Zero; &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">var</span>&nbsp;<span style="font-weight:bold;color:#1f377f;">count</span>&nbsp;=&nbsp;0; &nbsp;&nbsp;&nbsp;&nbsp;<span style="font-weight:bold;color:#8f08c4;">foreach</span>&nbsp;(<span style="color:blue;">var</span>&nbsp;<span style="font-weight:bold;color:#1f377f;">ts</span>&nbsp;<span style="font-weight:bold;color:#8f08c4;">in</span>&nbsp;<span style="font-weight:bold;color:#1f377f;">timeSpans</span>) &nbsp;&nbsp;&nbsp;&nbsp;{ &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="font-weight:bold;color:#1f377f;">sum</span>&nbsp;<span style="font-weight:bold;color:#74531f;">+=</span>&nbsp;<span style="font-weight:bold;color:#1f377f;">ts</span>; &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="font-weight:bold;color:#1f377f;">count</span>++; &nbsp;&nbsp;&nbsp;&nbsp;} &nbsp;&nbsp;&nbsp;&nbsp;<span style="font-weight:bold;color:#8f08c4;">return</span>&nbsp;<span style="font-weight:bold;color:#1f377f;">sum</span>&nbsp;<span style="font-weight:bold;color:#74531f;">/</span>&nbsp;<span style="font-weight:bold;color:#1f377f;">count</span>; }</pre> </p> <p> Don't get me wrong. I often write code like this because it makes it easier for me as a library developer to reason about the rest of the method body. On the other hand, it basically just replaces one run-time exception with another. Before I added the Guard Clause, calling <code>Average</code> with an empty collection would cause it to throw an <code>OverflowException</code>; now it throws an <code>ArgumentOutOfRangeException</code>. </p> <p> From client developers' perspective, this is only a marginal improvement. You're still getting no help from the type system, but at least the run-time error is a bit more informative. Sometimes, that's the best you can do. </p> <h3 id="3825bb6fb4db4cd28b9134763d202b3a"> Finite collections <a href="#3825bb6fb4db4cd28b9134763d202b3a" title="permalink">#</a> </h3> <p> The <code>Average</code> method has two preconditions, but we've only addressed one. The other precondition is that the input <code>timeSpans</code> must be finite. Unfortunately, this compiles: </p> <p> <pre><span style="color:blue;">static</span>&nbsp;<span style="color:#2b91af;">IEnumerable</span>&lt;<span style="color:#2b91af;">T</span>&gt;&nbsp;<span style="font-weight:bold;color:#74531f;">InfinitelyRepeat</span>&lt;<span style="color:#2b91af;">T</span>&gt;(<span style="color:#2b91af;">T</span>&nbsp;<span style="font-weight:bold;color:#1f377f;">x</span>) { &nbsp;&nbsp;&nbsp;&nbsp;<span style="font-weight:bold;color:#8f08c4;">while</span>&nbsp;(<span style="color:blue;">true</span>)&nbsp;<span style="font-weight:bold;color:#8f08c4;">yield</span>&nbsp;<span style="font-weight:bold;color:#8f08c4;">return</span>&nbsp;<span style="font-weight:bold;color:#1f377f;">x</span>; } <span style="color:blue;">var</span>&nbsp;<span style="font-weight:bold;color:#1f377f;">ts</span>&nbsp;=&nbsp;<span style="color:blue;">new</span>&nbsp;<span style="color:#2b91af;">TimeSpan</span>(1,&nbsp;2,&nbsp;3,&nbsp;4); <span style="color:blue;">var</span>&nbsp;<span style="font-weight:bold;color:#1f377f;">tss</span>&nbsp;=&nbsp;<span style="font-weight:bold;color:#74531f;">InfinitelyRepeat</span>(<span style="font-weight:bold;color:#1f377f;">ts</span>); <span style="color:blue;">var</span>&nbsp;<span style="font-weight:bold;color:#1f377f;">avg</span>&nbsp;=&nbsp;<span style="font-weight:bold;color:#1f377f;">tss</span>.<span style="font-weight:bold;color:#74531f;">Average</span>();</pre> </p> <p> Since <code>tss</code> infinitely repeats <code>ts</code>, the <code>Average</code> method call (theoretically) loops forever; in fact it quickly overflows because it keeps adding <code>TimeSpan</code> values together. </p> <p> Infinite collections aren't allowed. Can you make that precondition explicit? </p> <p> I don't know of a way to test that <code>timeSpans</code> is finite at run time, but I can change the input type: </p> <p> <pre><span style="color:blue;">public</span>&nbsp;<span style="color:blue;">static</span>&nbsp;<span style="color:#2b91af;">TimeSpan</span>&nbsp;<span style="color:#74531f;">Average</span>(<span style="color:blue;">this</span>&nbsp;<span style="color:#2b91af;">IReadOnlyCollection</span>&lt;<span style="color:#2b91af;">TimeSpan</span>&gt;&nbsp;<span style="font-weight:bold;color:#1f377f;">timeSpans</span>) { &nbsp;&nbsp;&nbsp;&nbsp;<span style="font-weight:bold;color:#8f08c4;">if</span>&nbsp;(!<span style="font-weight:bold;color:#1f377f;">timeSpans</span>.<span style="font-weight:bold;color:#74531f;">Any</span>()) &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="font-weight:bold;color:#8f08c4;">throw</span>&nbsp;<span style="color:blue;">new</span>&nbsp;<span style="color:#2b91af;">ArgumentOutOfRangeException</span>( &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">nameof</span>(<span style="font-weight:bold;color:#1f377f;">timeSpans</span>), &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="color:#a31515;">&quot;Can&#39;t&nbsp;calculate&nbsp;the&nbsp;average&nbsp;of&nbsp;an&nbsp;empty&nbsp;collection.&quot;</span>); &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">var</span>&nbsp;<span style="font-weight:bold;color:#1f377f;">sum</span>&nbsp;=&nbsp;<span style="color:#2b91af;">TimeSpan</span>.Zero; &nbsp;&nbsp;&nbsp;&nbsp;<span style="font-weight:bold;color:#8f08c4;">foreach</span>&nbsp;(<span style="color:blue;">var</span>&nbsp;<span style="font-weight:bold;color:#1f377f;">ts</span>&nbsp;<span style="font-weight:bold;color:#8f08c4;">in</span>&nbsp;<span style="font-weight:bold;color:#1f377f;">timeSpans</span>) &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="font-weight:bold;color:#1f377f;">sum</span>&nbsp;<span style="font-weight:bold;color:#74531f;">+=</span>&nbsp;<span style="font-weight:bold;color:#1f377f;">ts</span>; &nbsp;&nbsp;&nbsp;&nbsp;<span style="font-weight:bold;color:#8f08c4;">return</span>&nbsp;<span style="font-weight:bold;color:#1f377f;">sum</span>&nbsp;<span style="font-weight:bold;color:#74531f;">/</span>&nbsp;<span style="font-weight:bold;color:#1f377f;">timeSpans</span>.Count; }</pre> </p> <p> Instead of accepting any <code>IEnumerable&lt;TimeSpan&gt;</code> as an input argument, I've now constrained <code>timeSpans</code> to an <code>IReadOnlyCollection&lt;TimeSpan&gt;</code>. <a href="https://docs.microsoft.com/dotnet/api/system.collections.generic.ireadonlycollection-1">This interface</a> has been in .NET since .NET 4.5 (<a href="/2013/07/20/linq-versus-the-lsp">I think</a>), but it lives a quiet existence. Few people know of it. </p> <p> It's just <code>IEnumerable&lt;T&gt;</code> with an extra constraint: </p> <p> <pre><span style="color:blue;">public</span>&nbsp;<span style="color:blue;">interface</span>&nbsp;<span style="color:#2b91af;">IReadOnlyCollection</span>&lt;<span style="color:#2b91af;">T</span>&gt;&nbsp;:&nbsp;<span style="color:#2b91af;">IEnumerable</span>&lt;<span style="color:#2b91af;">T</span>&gt; { &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">int</span>&nbsp;Count&nbsp;{&nbsp;<span style="color:blue;">get</span>;&nbsp;} }</pre> </p> <p> The <code>Count</code> property strongly implies that the <code>IEnumerable&lt;T&gt;</code> is finite. Also, that the value is an <code>int</code> implies that the maximum size of the collection is 2,147,483,647. That's probably going to be enough for most day-to-day use. </p> <p> You can no longer pass an infinite stream of values to the <code>Average</code> method. It's simply not going to compile. That both communicates and protects the invariant that infinite collections aren't allowed. It also makes the implementation code simpler, since the method doesn't have to count the elements. That information is already available from <code>timeSpans.Count</code>. </p> <p> If a type can address one invariant, can it also protect the other? </p> <h3 id="b1464fa0dafc42838b6f7db24d8356c8"> Non-empty collection <a href="#b1464fa0dafc42838b6f7db24d8356c8" title="permalink">#</a> </h3> <p> You can change the input type again. Here I've used <a href="/2017/12/11/semigroups-accumulate">this NotEmptyCollection&lt;T&gt; implementation</a>: </p> <p> <pre><span style="color:blue;">public</span>&nbsp;<span style="color:blue;">static</span>&nbsp;<span style="color:#2b91af;">TimeSpan</span>&nbsp;<span style="color:#74531f;">Average</span>(<span style="color:blue;">this</span>&nbsp;<span style="color:#2b91af;">NotEmptyCollection</span>&lt;<span style="color:#2b91af;">TimeSpan</span>&gt;&nbsp;<span style="font-weight:bold;color:#1f377f;">timeSpans</span>) { &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">var</span>&nbsp;<span style="font-weight:bold;color:#1f377f;">sum</span>&nbsp;=&nbsp;<span style="font-weight:bold;color:#1f377f;">timeSpans</span>.Head; &nbsp;&nbsp;&nbsp;&nbsp;<span style="font-weight:bold;color:#8f08c4;">foreach</span>&nbsp;(<span style="color:blue;">var</span>&nbsp;<span style="font-weight:bold;color:#1f377f;">ts</span>&nbsp;<span style="font-weight:bold;color:#8f08c4;">in</span>&nbsp;<span style="font-weight:bold;color:#1f377f;">timeSpans</span>.Tail) &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="font-weight:bold;color:#1f377f;">sum</span>&nbsp;<span style="font-weight:bold;color:#74531f;">+=</span>&nbsp;<span style="font-weight:bold;color:#1f377f;">ts</span>; &nbsp;&nbsp;&nbsp;&nbsp;<span style="font-weight:bold;color:#8f08c4;">return</span>&nbsp;<span style="font-weight:bold;color:#1f377f;">sum</span>&nbsp;<span style="font-weight:bold;color:#74531f;">/</span>&nbsp;<span style="font-weight:bold;color:#1f377f;">timeSpans</span>.Count; }</pre> </p> <p> Now client code can no longer call the <code>Average</code> method with an empty collection. That's also not going to compile. </p> <p> You've replaced a run-time check with a compile-time check. It's now clear to client developers who want to call the method that they must supply a <code>NotEmptyCollection&lt;TimeSpan&gt;</code>, instead of just any <code>IReadOnlyCollection&lt;TimeSpan&gt;</code>. </p> <p> You can also simplify the implementation code: </p> <p> <pre><span style="color:blue;">public</span>&nbsp;<span style="color:blue;">static</span>&nbsp;<span style="color:#2b91af;">TimeSpan</span>&nbsp;<span style="color:#74531f;">Average</span>(<span style="color:blue;">this</span>&nbsp;<span style="color:#2b91af;">NotEmptyCollection</span>&lt;<span style="color:#2b91af;">TimeSpan</span>&gt;&nbsp;<span style="font-weight:bold;color:#1f377f;">timeSpans</span>) { &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">var</span>&nbsp;<span style="font-weight:bold;color:#1f377f;">sum</span>&nbsp;=&nbsp;<span style="font-weight:bold;color:#1f377f;">timeSpans</span>.<span style="font-weight:bold;color:#74531f;">Aggregate</span>((<span style="font-weight:bold;color:#1f377f;">x</span>,&nbsp;<span style="font-weight:bold;color:#1f377f;">y</span>)&nbsp;=&gt;&nbsp;<span style="font-weight:bold;color:#1f377f;">x</span>&nbsp;<span style="font-weight:bold;color:#74531f;">+</span>&nbsp;<span style="font-weight:bold;color:#1f377f;">y</span>); &nbsp;&nbsp;&nbsp;&nbsp;<span style="font-weight:bold;color:#8f08c4;">return</span>&nbsp;<span style="font-weight:bold;color:#1f377f;">sum</span>&nbsp;<span style="font-weight:bold;color:#74531f;">/</span>&nbsp;<span style="font-weight:bold;color:#1f377f;">timeSpans</span>.Count; }</pre> </p> <p> How do we know that <code>NotEmptyCollection&lt;T&gt;</code> contains at least one element? The constructor enforces that constraint: </p> <p> <pre><span style="color:blue;">public</span>&nbsp;<span style="color:#2b91af;">NotEmptyCollection</span>(<span style="color:#2b91af;">T</span>&nbsp;<span style="font-weight:bold;color:#1f377f;">head</span>,&nbsp;<span style="color:blue;">params</span>&nbsp;<span style="color:#2b91af;">T</span>[]&nbsp;<span style="font-weight:bold;color:#1f377f;">tail</span>) { &nbsp;&nbsp;&nbsp;&nbsp;<span style="font-weight:bold;color:#8f08c4;">if</span>&nbsp;(<span style="font-weight:bold;color:#1f377f;">head</span>&nbsp;==&nbsp;<span style="color:blue;">null</span>) &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="font-weight:bold;color:#8f08c4;">throw</span>&nbsp;<span style="color:blue;">new</span>&nbsp;<span style="color:#2b91af;">ArgumentNullException</span>(<span style="color:blue;">nameof</span>(<span style="font-weight:bold;color:#1f377f;">head</span>)); &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">this</span>.Head&nbsp;=&nbsp;<span style="font-weight:bold;color:#1f377f;">head</span>; &nbsp;&nbsp;&nbsp;&nbsp;<span style="color:blue;">this</span>.Tail&nbsp;=&nbsp;<span style="font-weight:bold;color:#1f377f;">tail</span>; }</pre> </p> <p> But wait, there's a Guard Clause and a <code>throw</code> there! Have we even accomplished anything, or did we just move the <code>throw</code> around? </p> <h3 id="ef73390937dc4f88997c7d42496b591e"> Parse, don't validate <a href="#ef73390937dc4f88997c7d42496b591e" title="permalink">#</a> </h3> <p> A Guard Clause is a kind of validation. It validates that input fulfils preconditions. The problem with validation is that you have to repeat it in various different places. Every time you receive some data as an input argument, it may or may not have been validated. A receiving method can't tell. There's no flag on a string, or a number, or a collection, which is set when data has been validated. </p> <p> Every method that receives such an input will have to perform validation, just to be sure that the preconditions hold. This leads to validation code being duplicated over a code base. When you duplicate code, you later update it in most of the places it appears, but forget to update it in a few places. Even if you're meticulous, a colleague may not know about the proper way of validating a piece of data. This leads to bugs. </p> <p> As <a href="https://lexi-lambda.github.io">Alexis King</a> explains in her <a href="https://lexi-lambda.github.io/blog/2019/11/05/parse-don-t-validate">Parse, don’t validate</a> article, 'parsing' is the process of validating input of weaker type into a value of a stronger type. The stronger type indicates that validation has happened. It's like a Boolean flag that indicates that, yes, the data contained in the type has been through validation, and found to hold. </p> <p> This is also the case of <code>NotEmptyCollection&lt;T&gt;</code>. If you have an object of that type, you know that it has already been validated. You know that the collection isn't empty. Even if you think that it looks like we've just replaced one exception with another, that's not the point. The point is that we've replaced scattered and unsystematic validation code with a single verification step. </p> <p> You may still be left with the nagging doubt that I didn't really avoid throwing an exception. I think that the <code>NotEmptyCollection&lt;T&gt;</code> constructor strikes a pragmatic balance. If you look only at the information revealed by the type (i.e. what an <a href="https://en.wikipedia.org/wiki/Integrated_development_environment">IDE</a> would display), you'll see this when you program against the class: </p> <p> <pre><span style="color:blue;">public</span>&nbsp;<span style="color:#2b91af;">NotEmptyCollection</span>(<span style="color:#2b91af;">T</span>&nbsp;<span style="font-weight:bold;color:#1f377f;">head</span>,&nbsp;<span style="color:blue;">params</span>&nbsp;<span style="color:#2b91af;">T</span>[]&nbsp;<span style="font-weight:bold;color:#1f377f;">tail</span>)</pre> </p> <p> While you could, technically, pass <code>null</code> as the <code>head</code> parameter, it should be clear to you that you're trying to do something you're not supposed to do: <code>head</code> is <em>not</em> an optional argument. Had it been optional, the API designer should have provided an overload that you could call without any value. Such a constructor overload isn't available here, so if you try to cheat the compiler by passing <code>null</code>, don't be surprised to get a run-time exception. </p> <p> For what it's worth, I believe that you can only be pragmatic if you know how to be dogmatic. Is it possible to protect <code>NotEmptyCollection&lt;T&gt;</code>'s invariants without throwing exceptions? </p> <p> Yes, you could do that by making the constructor <code>private</code> and instead afford a static factory method that returns a <a href="/2018/03/26/the-maybe-functor">Maybe</a> or <a href="/2018/06/11/church-encoded-either">Either</a> value. In <a href="https://www.haskell.org">Haskell</a>, this is typically called a <em>smart constructor</em>. It's only a few lines of code, so I could easily show it here. I chose not to, though, because I'm concerned that readers will interpret this article the wrong way. I like Maybe and Either a lot, but I agree with the above critics that it may not be <a href="/2015/08/03/idiomatic-or-idiosyncratic">idiomatic</a> in object-oriented languages. </p> <h3 id="737101b053e847f08124d49659804bf6"> Summary <a href="#737101b053e847f08124d49659804bf6" title="permalink">#</a> </h3> <p> <em>Encapsulation</em> is central to object-oriented design. It's the notion that it's an object's own responsibility to protect its invariants. In statically typed object-oriented programming languages, objects are instances of classes. Classes are types. Types encapsulate invariants; they carry with them guarantees. </p> <p> You can sometimes model invariants by using types. Instead of performing a run-time check on input arguments, you can declare constructors and methods in such a way that they only take arguments that are already guaranteed to be valid. </p> <p> That's one way to reduce the amount of exceptions that your code throws. </p> </div> <div id="comments"> <hr> <h2 id="comments-header"> Comments </h2> <div class="comment" id="127722bf00aa49c8aa467df2200028f6"> <div class="comment-author"><a href="https://about.me/tysonwilliams">Tyson Williams</a></div> <div class="comment-content"> <p> Great post. I too prefer to avoid exceptions by strengthening preconditions using types. </p> <blockquote> Since <code>tss</code> infinitely repeats <code>ts</code>, the <code>Average</code> method call (theoretically) loops forever; in fact it quickly overflows because it keeps adding <code>TimeSpan</code> values together. </blockquote> <p> I am not sure what you mean here.  My best guess is that you are saying that this code would execute forever except that it will overflow, which will halt the execution.  However, I think the situation is ambiguous.  This code is impure because, as the <a href="https://docs.microsoft.com/en-us/dotnet/csharp/language-reference/keywords/checked-and-unchecked">Checked and Unchecked documentation</a> says, its behavior depends on whether or not the <code>-checked</code> compiler option is given.  This dependency on the compiler option can be removed by wrapping this code in a <a href="https://docs.microsoft.com/en-us/dotnet/csharp/language-reference/keywords/checked">checked</a> or <a href="https://docs.microsoft.com/en-us/dotnet/csharp/language-reference/keywords/unchecked">unchecked</a> block, which would either result in a thrown exception or an infinite loop respectively. </p> <blockquote> This gets the job done in most situations, but it has two error modes. It doesn't work if <code>timeSpans</code> is empty, and it doesn't work if it's infinite. </blockquote> <p> There is a third error mode, and it exists in every implementation you gave.  The issue of overflow is not restricted to the case of infinitely many <code>TimeSpan</code>s.  It only takes two.  I know of or remember this bug as <a href="https://thebittheories.com/the-curious-case-of-binary-search-the-famous-bug-that-remained-undetected-for-20-years-973e89fc212">"the last binary search bug"</a>.  That article shows how to correctly compute the average of two integers without overflowing.  A correct implementation for computing the average of more than two integers is to map each element to a mixed fraction with the count as the divisor and then appropriately aggregate those values.  The implementation given in <a href="https://www.quora.com/How-can-I-compute-the-average-of-a-large-array-of-integers-without-running-into-overflow/answer/Mark-Gordon-6">this Quora answer</a> seems correct to me. </p> <p> I know all this is unrelated to the topic of your post, but I also know how much you prefer to use examples that avoid this kind of accidental complexity.  Me too!  However, I still like your example and can't think of a better one at the moment. </p> </div> <div class="comment-date">2020-02-05 14:13 UTC</div> </div> <div class="comment" id="0bf86e75e130497dbc8384a235f100f5"> <div class="comment-author"><a href="/">Mark Seemann</a></div> <div class="comment-content"> <p> Tyson, thank you for writing. Given an infinite stream of values, the method throws an <code>OverflowException</code>. This is because <code>TimeSpan</code> addition explicitly does that: </p> <p> <pre>&gt; <span style="color:#2b91af;">TimeSpan</span>.MaxValue&nbsp;<span style="font-weight:bold;color:#74531f;">+</span>&nbsp;<span style="color:blue;">new</span>&nbsp;<span style="color:#2b91af;">TimeSpan</span>(1) <span style="color:red">System.OverflowException: TimeSpan overflowed because the duration is too long. + System.TimeSpan.Add(System.TimeSpan) + System.TimeSpan.op_Addition(System.TimeSpan, System.TimeSpan)</span></pre> </p> <p> This little snippet from <em>C# Interactive</em> also illustrates the third error mode that I hadn't considered. Good point, that. </p> </div> <div class="comment-date">2020-02-06 6:47 UTC</div> </div> <div class="comment" id="d3727f9523f24793adb6c632d1a93a67"> <div class="comment-author"><a href="https://about.me/tysonwilliams">Tyson Williams</a></div> <div class="comment-content"> <p> Ah, yes. You are correct. Thanks for pointing out my mistake. Another way to verify this is inspecting <a href="https://referencesource.microsoft.com/#mscorlib/system/timespan.cs,153"><code>TimeSpan.Add</code> in Mircosoft's reference source</a>. I should have done those checks before posting. Thanks again! </p> </div> <div class="comment-date">2020-02-06 13:33 UTC</div> </div> </div><hr> This blog is totally free, but if you like it, please consider <a href="https://blog.ploeh.dk/support">supporting it</a>. Mark Seemann https://blog.ploeh.dk/2020/02/03/non-exceptional-averages The Maître d' kata https://blog.ploeh.dk/2020/01/27/the-maitre-d-kata/ Mon, 27 Jan 2020 06:45:00 UTC <div id="post"> <p> <em>A programming kata.</em> </p> <p> I <a href="/2020/01/13/on-doing-katas">recently wrote about doing programming katas</a>. You can find katas in many different places. Some sites exist exclusively for that purpose, such as the <a href="http://bit.ly/codekatas">Coding Dojo</a> or <a href="http://codekata.com">CodeKata</a>. In other cases, you can find individual katas on blogs; one of my favourites is the <a href="http://claysnow.co.uk/recycling-tests-in-tdd">Diamond kata</a>. You can also lift exercises from other sources and treat them as katas. For example, I recently followed <a href="https://github.com/mikehadlow/Journeys">Mike Hadlow's lead</a> and <a href="/2019/10/28/a-basic-haskell-solution-to-the-robot-journeys-coding-exercise">turned a job applicant test into a programming exercise</a>. I've also taken exercises from books and repurposed them. For example, <a href="/2017/10/23/convex-hull-monoid">I've implemented the Graham Scan algorithm for finding convex hulls</a> a couple of times. </p> <p> In this article, I'll share an exercise that I've found inspiring myself. I'll call it <em>the Ma&icirc;tre d' kata</em>. </p> <p> I present no code in this article. Part of what makes the exercise interesting, I think, is to figure out how to model the problem domain. I will, however, later publish one of my attempts at the kata. </p> <h3 id="73c0d7c81c1047d598cb6dbc8a49c99b"> Problem statement <a href="#73c0d7c81c1047d598cb6dbc8a49c99b" title="permalink">#</a> </h3> <p> Imagine that you're developing an online restaurant reservation system. Part of the behaviour of such a system is to decide whether or not to accept a reservation. At a real restaurant, employees fill various roles required to make it work. In a high-end restaurant, the <a href="https://en.wikipedia.org/wiki/Ma%C3%AEtre_d%27h%C3%B4tel">ma&icirc;tre d'</a> is responsible for taking reservations. I've named the kata after this role. If you're practising <a href="https://en.wikipedia.org/wiki/Domain-driven_design">domain-driven design</a>, you might want to name your object, class, or module <code>Ma&icirc;treD</code> or some such. </p> <p> The objective of the exercise is to implement the <code>Ma&icirc;treD</code> decision logic. </p> <p> Reservations are accepted on a first-come, first-served basis. As long as the restaurant has available seats for the desired reservation, it'll accept it. </p> <p> A reservation contains, at a minimum, a date and time as well as a positive quantity. Here's some examples: <table> <thead> <tr> <td>Date</td> <td style="text-align:right">Quantity</td> </tr> </thead> <tbody> <tr> <td>August 8, 2050 at 19:30</td> <td style="text-align:right">3</td> </tr> <tr> <td>November 27, 2022 at 18:45</td> <td style="text-align:right">4</td> </tr> <tr> <td>February 27, 2014 at 13:22</td> <td style="text-align:right">12</td> </tr> </tbody> </table> </p> <p> Notice that dates can be in your future or past. You might want to assume that the ma&icirc;tre d' would reject reservations in the past, but you can't assume <em>when</em> the code runs (or ran), so don't worry about that. Notice also that quantities are positive integers. While a quantity shouldn't be negative or zero, it could conceivably be large. I find it realistic, however, to keep quantities at low two-digit numbers or less. </p> <p> A reservation will likely contain other data, such as the name of the person making the reservation, contact information such as email or phone number, possibly also an ID, and so on. You may add these details if you want to make the exercise more realistic, but they're not required. </p> <p> I'm going to present one feature requirement at a time. If you read the entire article before you do the exercise, it'd correspond to gathering detailed requirements before starting to code. Alternatively, you could read the first requirement, do the exercise, read the next requirement, refactor your code, and so on. This would simulate a situation where your organisation gradually uncovers how the system ought to work. </p> <h3 id="f538ee06b5c54215bae10f661385893c"> Boutique restaurant <a href="#f538ee06b5c54215bae10f661385893c" title="permalink">#</a> </h3> <p> As readers of <a href="/dippp">my book</a> may have detected, I'm a foodie. Some years ago I ate at <a href="https://www.blancanyc.com">Blanca</a> in Brooklyn. That restaurant has one communal bar where everyone sits. There was room for twelve people, and dinner started at 19:00 whether you arrived on time or not. Such restaurants actually exist. It's an easy first step for the kata. Assume that the restaurant is only open for dinner, has no second seating, and a single shared table. This implies that the time of day of reservations doesn't matter, while the date still matters. Some possible test cases could be: <table> <thead> <tr> <td style="text-align:right">Table size</td> <td>Existing reservations</td> <td>Candidate reservation</td> <td>Expected outcome</td> </tr> </thead> <tbody> <tr> <td style="text-align:right">12</td> <td><em>none</em></td> <td>Quantity: 1</td> <td>Accepted</td> </tr> <tr> <td style="text-align:right">12</td> <td><em>none</em></td> <td>Quantity: 13</td> <td>Rejected</td> </tr> <tr> <td style="text-align:right">12</td> <td><em>none</em></td> <td>Quantity: 12</td> <td>Accepted</td> </tr> <tr> <td style="text-align:right">4</td> <td>Quantity: 2, Date: 2023-09-14</td> <td>Quantity: 3, Date: 2023-09-14</td> <td>Rejected</td> </tr> <tr> <td style="text-align:right">10</td> <td>Quantity: 2, Date: 2023-09-14</td> <td>Quantity: 3, Date: 2023-09-14</td> <td>Accepted</td> </tr> <tr> <td style="text-align:right">10</td> <td> Quantity: 3, Date: 2023-09-14<br> Quantity: 2, Date: 2023-09-14<br> Quantity: 3, Date: 2023-09-14 </td> <td>Quantity: 3, Date: 2023-09-14</td> <td>Rejected</td> </tr> <tr> <td style="text-align:right">4</td> <td>Quantity: 2, Date: 2023-09-15</td> <td>Quantity: 3, Date: 2023-09-14</td> <td>Accepted</td> </tr> </tbody> </table> </p> <p> This may not be an exhaustive set of test cases, but hopefully illustrates the desired behaviour. Try using the <a href="/2019/10/07/devils-advocate">Devil's Advocate technique</a> or <a href="/property-based-testing-intro">property-based testing</a> to identify more test cases. </p> <h3 id="05f0ec26d90044288845f5ad308742c2"> Haute cuisine <a href="#05f0ec26d90044288845f5ad308742c2" title="permalink">#</a> </h3> <p> The single-shared-table configuration is unusual. Most restaurants have separate tables. High-end restaurants like those on the <a href="https://www.theworlds50best.com">World's 50 best</a> list, or those with <a href="https://en.wikipedia.org/wiki/Michelin_Guide">Michelin stars</a> often have only a single seating. This is a good expansion of the domain logic. </p> <p> Assume that a restaurant has several tables, perhaps of different sizes. A table for four will seat one, two, three, or four people. Once a table is reserved, however, all the seats at that table are reserved. A reservation for three people will occupy a table for four, and the redundant seat is wasted. Obviously, the restaurant wants to maximise the number of guests, so it'll favour reserving two-person tables for one and two people, four-person tables for three and four people, and so on. </p> <p> In order to illustrate the desired behaviour, here's some extra test cases to add to the ones already in place: <table> <thead> <tr> <td>Tables</td> <td>Existing reservations</td> <td>Candidate reservation</td> <td>Expected outcome</td> </tr> </thead> <tbody> <tr> <td> Two tables for two<br> Two tables for four </td> <td><em>none</em></td> <td>Quantity: 4, Date: 2024-06-07</td> <td>Accepted</td> </tr> <tr> <td> Two tables for two<br> Two tables for four </td> <td><em>none</em></td> <td>Quantity: 5, Date: 2024-06-07</td> <td>Rejected</td> </tr> <tr> <td> Two tables for two<br> One table for four </td> <td>Quantity: 2, Date: 2024-06-07</td> <td>Quantity: 4, Date: 2024-06-07</td> <td>Accepted</td> </tr> <tr> <td> Two tables for two<br> One table for four </td> <td>Quantity: 3, Date: 2024-06-07</td> <td>Quantity: 4, Date: 2024-06-07</td> <td>Rejected</td> </tr> </tbody> </table> </p> <p> Again, you should consider adding more test cases if you're unit-testing the kata. </p> <h3 id="e008d27660b54882816e2e496ee89709"> Second seatings <a href="#e008d27660b54882816e2e496ee89709" title="permalink">#</a> </h3> <p> Some restaurants (even some of those on the <em>World's 50 best</em> list) have a second seating. As a diner, you have a limited time (e.g. 2&frac12; hours) to complete your meal. After that, other guests get your table. </p> <p> This implies that you must now consider the time of day of reservations. You should also be able to use an arbitrary (positive) seating duration. All previous rules should still apply. New test cases include: <table> <thead> <tr> <td>Seating duration</td> <td>Tables</td> <td>Existing reservations</td> <td>Candidate reservation</td> <td>Expected outcome</td> </tr> </thead> <tbody> <tr> <td>2 hours</td> <td> Two tables for two<br> One table for four </td> <td>Quantity: 4, Date: 2023-10-22, Time: 18:00</td> <td>Quantity: 3, Date: 2023-10-22, Time: 20:00</td> <td>Accepted</td> </tr> <tr> <td>2&frac12; hours</td> <td> One table for two<br> Two tables for four </td> <td> Quantity: 2, Date: 2023-10-22, Time: 18:00<br> Quantity: 1, Date: 2023-10-22, Time: 18:15<br> Quantity: 2, Date: 2023-10-22, Time: 17:45 </td> <td>Quantity: 3, Date: 2023-10-22, Time: 20:00</td> <td>Rejected</td> </tr> <tr> <td>2&frac12; hours</td> <td> One table for two<br> Two tables for four </td> <td> Quantity: 2, Date: 2023-10-22, Time: 18:00<br> Quantity: 2, Date: 2023-10-22, Time: 17:45 </td> <td>Quantity: 3, Date: 2023-10-22, Time: 20:00</td> <td>Accepted</td> </tr> <tr> <td>2&frac12; hours</td> <td> One table for two<br> Two tables for four </td> <td> Quantity: 2, Date: 2023-10-22, Time: 18:00<br> Quantity: 1, Date: 2023-10-22, Time: 18:15<br> Quantity: 2, Date: 2023-10-22, Time: 17:45 </td> <td>Quantity: 3, Date: 2023-10-22, Time: 20:15</td> <td>Accepted</td> </tr> </tbody> </table> </p> <p> If you make the seating duration short enough, you may even make room for a third seating, and so on. </p> <h3 id="cec332ae8ea444de929c2f5ca5603e90"> Alternative table configurations <a href="#cec332ae8ea444de929c2f5ca5603e90" title="permalink">#</a> </h3> <p> If tables are rectangular, the restaurant has the option to combine several smaller tables into one larger. Consider a typical restaurant layout like this: </p> <p> <img src="/content/binary/restaurant-configuration-with-three-individual-two-person-tables.png" alt="A map of a restaurant including three adjacent two-person tables."> </p> <p> There's a round four-person table, as well as a few small tables that can't easily be pushed together. There's also three (orange) two-person tables where one guest sits against the wall, and the other diner faces him or her. These can be used as shown above, but the restaurant can also push two of these tables together to accommodate four people: </p> <p> <img src="/content/binary/restaurant-configuration-with-two-two-person-tables-combined.png" alt="A map of a restaurant where two of the three adjacent two-person tables have been pushed together."> </p> <p> This still leaves one of the adjacent two-person tables as an individual table, but the restaurant can also push all three tables together to accommodate six people: </p> <p> <img src="/content/binary/restaurant-configuration-with-all-two-person-tables-combined.png" alt="A map of a restaurant where all three adjacent two-person tables have been pushed together."> </p> <p> Implement decision logic that allows for alternative table configurations. Remember to take seating durations into account. Consider both the configuration illustrated, as well as other configurations. Note that in the above configuration, not all two-person tables can be combined. </p> <h3 id="fa8d74d3a39f462ca23818f79eefb7a8"> More domain logic <a href="#fa8d74d3a39f462ca23818f79eefb7a8" title="permalink">#</a> </h3> <p> You can, if you will, invent extra rules. For example, restaurants have opening hours. A restaurant that opens at 18:00 and closes at 0:00 will not accept reservations for 13:30, regardless of table configuration, existing reservations, seating duration, and so on. </p> <p> Building on that idea, some restaurants have different opening hours on various weekdays. Some are closed Mondays, serve dinner only Tuesday to Friday, but are then open for both lunch and dinner in the weekend. </p> <p> Going in that direction, however, opens a can of worms. Perhaps the restaurant is closed on public holidays. Or perhaps it's explicitly open on public holidays, to cater for an audience that may not otherwise dine out. <a href="/2017/04/24/simple-holidays">But implementing a holiday calender is far from as simple as it sounds</a>. That's the reason I left such rules out of the above specifications of the kata. </p> <p> Another idea that you may consider is to combine communal bar seating with more traditional tables. <a href="https://thecloveclub.com">The Clove Club</a> is an example of restaurant that does it that way. </p> <h3 id="66b7a3d1b3e5453ca343494ccd0bc51a"> Summary <a href="#66b7a3d1b3e5453ca343494ccd0bc51a" title="permalink">#</a> </h3> <p> This is a programming kata description. Implement the decision logic of a ma&icirc;tre d': <em>Can the restaurant accept a given reservation?</em> </p> <p> After some time has gone by, I'll post at least one of my own attempts. You're welcome to <a href="https://github.com/ploeh/ploeh.github.com#comments">leave a comment</a> if you do the kata and wish to share your results. </p> </div><hr> This blog is totally free, but if you like it, please consider <a href="https://blog.ploeh.dk/support">supporting it</a>. Mark Seemann https://blog.ploeh.dk/2020/01/27/the-maitre-d-kata