So long, and thanks for all the bits

The Ultimate MacBook+PC Monitor Showdown

2021-01-01T00:00:00+00:00

Like many folks finding their way through the COVID-19 pandemic, I’ve recently accepted a job working permanently remote. So for the foreseeable future my workstation will be pulling double-duty for macOS-based software development with a MacBook Pro and Windows-based gaming on a PC.

Modern monitors come with a lot of interesting features. Did you know you can connect a MacBook to a monitor using a single USB-C cable and transmit USB, power, audio and video?

Unfortunately, it’s not as simple as knowing whether a monitor supports USB-C. Many monitors support USB-C but don’t have any sort of way to pipe the audio out from the monitor (for example, to a sound bar). And some monitors have USB-C and audio out, but only provide 15W of power.

With enough features, the monitor effectively acts as a KVM+audio, like so:

So I set out to identify a monitor that meets all of my criteria. Specifically:

Has a built-in KVM switch that lets me easily switch between my PC and MacBook.
Provides at least 60W power over USB-C (the bare minimum to power a 16-inch MacBook Pro).
Some sort of audio output (almost always analog).
Upstream USB-B Port so that I can plug my keyboard and mouse into the monitor and pipe PC audio through the monitor to the sound bar.
VESA mountable.
IPS panel. The viewing angles on my TN panel are so bad it interferes with my work so IPS is a must.
27” or 34” ultrawide @ 1440p. Good for gaming and happens to be the ideal non-retina DPI for macOS. Full retina @ 5k instead of 1440p would be nice, but unfortunately I couldn’t find such a monitor that meets all the minimum criteria. Awkward DPIs are a deal-breaker due to scaling and “shimmering” effects mentioned in the linked post.

Nice-to-haves:

Adaptive sync (AS).
144hz refresh rate. At 60hz I lose track of my mouse cursor in League of Legends and we can’t have that!
90W power delivery over USB-C.
Reasonable price.

Here’s what I found after about 15 hours of research:

Model	Size	Pros	Cons
ViewSonic VP2771	27” 1440p	$200-$450	60hz, 60W USB-C
LG 34WK95C-W	34” 1440p UW	Adaptive Sync	75hz, 60W USB-C, ~$1,000
Dell U3421WE	34” 1440p UW	90W USB-C	60hz, ~$1,000
LG 34WK95U	34” 4k UW	85W USB-C	60hz, ~$1,300, awkward DPI
Dell U3219Q	32” 4k	90W USB-C	60hz, ~$800, awkward DPI
BenQ PD3220U	32” 4k	85W USB-C	60hz, ~$1,200, awkward DPI
Razer Raptor 27	27” 1440p	AS, 144hz, HDR	15W USB-C, No VESA mount, $700
Philips 346B1C	34” 1440p UW	90W, AS, $450	100hz, VA panel
Acer Predator X34 S	34” 1440p UW	200hz, AS, 85W	Not available (yet)

I can’t guarantee this is an exhaustive list, but it might be. I left off monitors that are no longer for sale or lack crucial features like an audio output or upstream USB-B port.

As you can see, there’s no ideal monitor except for the Acer Predator X34 S, which isn’t available in the US yet and currently costs ¥9999 (roughly $1,500 USD). There’s a similar model with a lower refresh rate, the X34 GS, however I can only find it for sale in Australia for approximately $1,342 USD. In terms of what’s available today, you ultimately need to choose whether you want to sacrifice refresh rate, VESA mounting, USB-C charging, or panel type.

As luck would have it, I ended up snagging a ViewSonic VP2771 on eBay for $200 shipped. After all, I still have a 144hz TN panel that I can keep plugged into the gaming PC. It’s not ideal but it’ll work until I get my hands on that Acer.

Let me know in the comments if you find a monitor that should be in this list. If you want to play League of Legends together you can find me under the summoner name JamesJonesJrJr.

Stay safe out there, friends.

HTTP PUT is dead, long live HTTP PUT

2020-02-27T00:00:00+00:00

Absent some sort of alien quantum technology, engineering client-server applications will always mean entertaining the possibility that clients will lag the server by at least one version.

Most people I know prefer to use the oldest version of software they can get away with. Updating software without a specific feature in mind means spending precious time learning a new interface and dealing with new bugs.

As a system engineer, you can respond a couple different ways:

If you’re ok with your users hating you, you can force client updates.
Plan for the possibility that some clients will lag the server by at least one version.

A problematic verb

When it comes to RESTful API’s, the first HTTP verb that comes to mind when you’re editing a entity is almost always PUT. The problem with using PUT is that it lacks forward compatibility. Here’s why:

Step 1: Client v1.1 POSTs a new entity to the server:

{ "name": "Dave", "age": 47 } 

Step 2: An older client (v1.0) GETs the entity client v1.1 created, transforms it to a model compatible with its UI, lets the user modify it, and then attempts to send it back to the server via HTTP PUT. The thing is, the ‘age’ property was just added in v1.1 and client v1.0 has no notion of it, so the payload it sends looks like this:

{ "name": "Whitmer" } 

Because we’re using PUT, the server must replace the entire document in the database with this new document, so “age” is dropped and this data is lost. If an older client is unknowingly deleting data created by newer clients, you’re gonna have a bad time.

We can avoid having a bad time.

Enter JSON Merge Patch

No, not that other patch. JSON Merge Patch is perfect because it’s almost exactly like PUT except it doesn’t delete fields it doesn’t know about.

In other words, when you omit a property in a Merge PATCH, the database will simply let that property remain whatever value it presently is. This provides forward compatibility and thus fixes the main issue we have with PUT.

In closing, stop using HTTP PUT

It’s just bad, mkay? Okay fine it’s actually not that bad. PUT can actually be pretty great for other things, just consider PATCH instead when you’re trying to edit entities.

Temporal repository implementation using MongoDB and ASP.NET Core

2019-11-14T00:00:00+00:00

In my last post we covered why CRUD patterns can be inherently difficult to scale. If you’ve reached that point, congratulations, it’s time to upgrade your design. In this post we’ll cover a different kind of data access pattern that’s a little more complicated than CRUD, but offers some benefits that just might make it worthwhile.

The key to scalable systems is asyncronous processing. And the key to asyncronous processing is adopting data structures that facilitate asyncronous processing. One such data structure is the ‘temporal’ repository.

temporal (ˈtemp(ə)rəl)

adjective

relating to time.

The temporal repository is capable of knowing not just the current state of the entities within it but also their prior states. This repo has the memory of an elephant and knows not just facts about the world, but also when it came to know about them. Here’s what such an interface looks like:

public interface ITemporalRepository<T> { /// <summary> /// Saves the entity to the database. /// </summary> Task SaveAsync(T entity); /// <summary> /// Gets the latest version of the entity from the database. /// </summary> Task<T> GetAsync(string identifier); /// <summary> /// Gets a version of the entity as of a given point in time. /// </summary> Task<T> GetAsync(string identifier, DateTime asOf); /// <summary> /// Gets the complete history of an entity. /// </summary> IAsyncEnumerable<T> GetHistoryAsync(string identifier); /// <summary> /// Gets the latest versions of all the entities in the /// database. /// </summary> IAsyncEnumerable<T> GetAllAsync(); /// <summary> /// Gets all the entities from the database as of a given /// point in time. /// </summary> IAsyncEnumerable<T> GetAllAsync(DateTime asOf); /// <summary> /// Purges historical versions of an entity beyond a given /// point in time. Keeps however many versions specified. /// </summary> Task PurgeHistoricalVersionsAsync(DateTime howFarBackToPurge, int minVersionsToKeep); } 

As you can see, by enabling our data model to travel backwards in time, we end up with more than just the standard four CRUD routines. This interface enables us to do some pretty cool stuff, namely:

Coordinate multiple batch processes to asynchronously process the system as of an exact point in time. In other words, we have an immutable data set. We don’t have to worry about anyone pulling the rug out from under us and retries can be idempotent.
Perform diffs on the data, for example to understand what has changed since the last time a batch process was ran.
Provide an audit log, which is immensely useful for debugging and is oftentimes required to meet regulatory requirements.
Retroactively process data as of a specific point in time in the past (i.e. quarterly reporting).

You get all of this and more without ever needing to create a transaction.

See it in action

I’ve created a demo of this pattern using ASP.NET Core 3.0, MongoDB and Docker. One thing I love about Docker is that you don’t need to install MongoDB just to see this demo work. Simply run the Docker Compose file and you’re off to the races. I should also mention this can run on both macOS and Windows. I know because I developed this demo on both a MacBook and a Windows PC. 🤠

To run the demo I’d recommend installing the following software:

Visual Studio 2019
Docker (along with Kitematic for managing containers)

Next, clone or download the source from my GitHub. You should be able to simply open the solution in Visual Studio and run the docker-compose project. In Kitematic, use Ctrl + R (or ⌘ + R) to refresh the container list. You should see the list of Docker containers that were created and you should observe that the MongoDB cluster has formed:

Next, use the Test Explorer in Visual Studio to run the integration tests and observe that they all pass:

I think I’ve said enough for one blog post. Go ahead, set some breakpoints and tinker around. If you’d like to connect to the local MongoDB cluster you can connect to it on the default port 27017. If you have MongoDB Compass you should be able to simply open it up and hit ‘Connect’.

It’s called ‘CRUD’ for a reason

2019-10-30T00:00:00+00:00

“To err is human, but to really foul things up you need a computer.”

-Paul R. Ehrlich

Many business processes that exist today were born out of old fashioned paper/form-driven processes. This is because paper was invented before computers were invented. Had computers been invented first, you might imagine a completely different world in which you place an order online to buy something and your browser spins until the package arrives on your doorstep.

I’m kidding, sort of.

Many enterprise software systems are less exaggerated versions of this. In some cases I’ve seen ‘submit’ buttons routinely keep the user waiting as long as several minutes for the underlying transaction to complete.

Why has the bar fallen this low? And how can we fix it? In this post we’ll dive into exactly that.

History doesn’t repeat itself, but it often rhymes

Most modern ways of doing things can be traced back to a historical problem that was solved using the path of least resistance. From the icons on your phone to the arrangement of the keys on your keyboard, these enduring vestiges of the past surround us.

Back when the world was run on paper, modifying a piece of information might have meant moving a giant, heavy filing cabinet. It made much more sense to grab a fresh form and fill it out, with the intent of replacing the original form later on. This is a very intuitive practice because the cabinet is heavy and slow, and there aren’t significant consequences for updating original form at your convenience. And if finance wants to do a quarter-end process that takes a few days and depends on these forms, you can let them do their thing unbothered by everyone wanting to update their information. Many processes like this exist because they feel natural.

Fast forward to the digital age, our first (and correct) assumption is that computers are fast. To assume otherwise would be a missed opportunity to design a simpler system that performs adequately. In the industry this dilemma is known as “premature optimization.” In the typical lifecycle of a software system, the first step is to build a rudimentary proof-of-concept that’s gradually modified to accommodate the increased demands placed upon it.

The simplest kind of computer information system is a CRUD-like design. CRUD stands for Create/Read/Update/Delete, which refers to the way data is stored on the system. In this kind of system, every entity in the system reflects its most recent write. If the need arises to keep multiple entities in a consistent state or capture the state of the system at a single point in time, a dark magic known as ACID transactions are employed. A CRUD design is effectively the same as the paper-driven process except your data entry person is The Flash and is capable of immediately updating information upon arrival and can also generate any kind of report you need, when you need it.

The unfortunate reality is that even The Flash has his limits. CPU speeds haven’t budged in decades and data requirements continue to grow exponentially. And as it turns out, ACID transactions aren’t magic. They typically rely on a mix of locks (which reduce system availability) or optimistic concurrency (which reduces reliability and consistency). These effects are ever more pronounced as the system scales. Mutable state, scalability and consistency are sworn enemies.

Like a thin layer of filth (crud?) that slowly accumulates on your lenses, it can be difficult to notice that you’ve gradually moved the goalposts on the responsiveness of the system. It’s tempting to blame the CAP theorem for your woes and settle for investing weeks of developer time into regaining marginal amounts of lost ground. Any progress can seem impressive when you’re desperate enough. But fear not, there’s solution to all of this, you just haven’t seen it in a very, very long time.

Meet the new process, same as the old process

It would be easy for me to throw software developers under the bus for not championing a solution to this problem. The reality is that business process owners are equally culpable. After all, early business process owners were able to conquer these issues using the slowest and most error-prone computers of all – human beings.

The major difference between the slow, paper-driven processes of yore and the “fast,” computer-driven processes of today is something called “temporality.” It’s this idea that you can have multiple versions of a piece of information, each valid as of their respective points in time. By incorporating the dimension of time, the system can recall what its exact state was at any given point in time.

Early information systems possessed elements of temporal systems by virtue of the fact that the easiest thing to do was to version the data stored within them. By intentionally utilizing this concept in digital information systems, we can achieve a whole new level of scalability, responsiveness, reliability, testability and simplicity. I can’t wait to show you how easy it can be to design this sort of system. Stay tuned.

See the follow-up blog post: Temporal repository implementation using MongoDB and ASP.NET

Put your ASP.NET Core controller on a diet with middleware

2019-03-02T00:00:00+00:00

One of the most important responsibilities of RESTful web services is that they translate business logic outcomes (and unexpected errors) to the correct HTTP response code. When it comes to accomplishing this in ASP.NET Core, this logic usually ends up in the controller and looks something like this:

public ActionResult Put(int id, [FromForm] string value) { if (string.IsNullOrEmpty(value)) { // don't do this! var responseObject = new { message = "value is a required parameter" }; string responseBody = JsonConvert .SerializeObject(responseObject); return BadRequest(responseBody); } _repo.Update(id, value); return Ok(); } 

Or even worse:

public ActionResult Put(int id, [FromForm] string value) { try { _repo.Update(id, value); } catch (ArgumentNullException ex) // ew { var responseObject = new { message = ex.Message; }; string responseBody = JsonConvert .SerializeObject(responseObject); return BadRequest(responseBody); } catch (Exception ex) // gross { return new StatusCodeResult(500); } return Ok(); } 

The problem is that these controller methods are exceedingly thick. Every controller method requires input validation and emitting an HTTP response in the event of a validation failure. There are ways to push this validation to other places in the service layer, but the crux of the issue is that validation is in fact business logic which should really be in a domain layer.

Ideally, we could reduce the controller methods down to something much simpler, like this:

public ActionResult Put(int id, [FromForm] string value) { if (string.IsNullOrEmpty(value)) { throw new BadRequestException("value is required"); } _repo.Update(id, value); return Ok(); } 

Or even better:

public ActionResult Put(int id, [FromForm] string value) { _repo.Update(id, value); //internally throw BadRequestException return Ok(); } 

Where BadRequestException is an exception that lives in our domain layer:

public class BadRequestException : Exception { } 

Getting throw BadRequestException("...") out of the controller and pushing it down into the domain layer is desirable, because as mentioned before, much of the business logic is captured in validation. And almost everyone can agree business logic shouldn’t be in the HTTP layer. The HTTP layer is complicated enough without having to worry about business logic!

In case you’re balking at the idea of using exceptions this way, allow me the opportunity to allay your concern:

You may want this exception to be called ValidationException or something less HTTP-oriented, and by all means feel free to do that. I personally think it’s fine for the domain layer to have some notion of an HTTP response since requirements are so usually so coupled with HTTP responses. To each their own. However you name it, the key is that we’re using exceptions for the validation failure workflow.

You also might be wondering if it’s okay to use exceptions for business logic. I personally think this is fine for one big reason: Exceptions are an immensely powerful construct for implementing validation logic because they let you write functions as if a validation failure will never happen. They enable you write clean, happy-path function signatures that are blissfully unaware of the possibility that a validation failure may occur. And this is infinitely better than passing validation lists via reference into every function or stuffing your controller with validation logic.

Anyway, back to the point of this post. Since the controller and domain layer won’t catch exceptions, then who will? You guessed it – the answer is ASP.NET Core middleware. I’m telling you, it’s SO comforting knowing middleware will always be there to catch you. Seriously, once you start using this pattern you’ll never go back. So let’s get to it.

First, we need to create a marker-like interface which will let our middleware discern between exceptions thrown by our business logic and the other, more nefarious exceptions like NullReferenceException, etc:

public interface IHttpException { int HttpStatusCode { get; } } 

And then we’ll fix up our BadRequestException to use that interface:

public class BadRequestException : Exception, IHttpException { public int HttpStatusCode => StatusCodes.Status400BadRequest; } 

And, without further adieu, here’s the middleware that will handle all uncaught exceptions:

public static IApplicationBuilder UseExceptionHandlingMiddleware (this IApplicationBuilder app) { return app.UseExceptionHandler(options => { options.Run(async context => { var ex = context.Features.Get<IExceptionHandlerFeature>(); context.Response.ContentType = "application/json"; string responseMessage; if (ex.Error is IHttpException) { context.Response.StatusCode = (ex.Error as IHttpException).HttpStatusCode; responseMessage = ex.Error.Message; } else { context.Response.StatusCode = StatusCodes.Status500InternalServerError; responseMessage = "internal server error :("; } var responseObject = new { message = responseMessage }; string responseBody = JsonConvert .SerializeObject(responseObject); await context.Response.WriteAsync(responseBody.ToString()); }); }); } 

Note

Notice how exceptions which don’t match the IHttpException marker will emit an internal server error. Internal server errors are certainly inconvenient, but we owe it to our service consumers to be transparent when something very bad has happened! This way, we can quickly respond to critical errors in a consistent way (for example, by logging the stack trace, sending a notification to support, reaching out to the user, etc). And it’s pretty nice not having try/catches all over the place.

If anything, I hope this post demonstrates the power of ASP.NET Core middleware to handle cross-cutting concerns such as exception handling. As a rule of thumb, pretty much any time you have code repeating in many controller methods there’s usually a way to move that code into middleware.

Feel free to clone the source from GitHub and see the pattern in action. The unit tests use Microsoft.AspNetCore.Mvc.Testing to test the entire HTTP pipeline, including the middleware. Enjoy.

Bug fix - HTTP Error 502.5 - Process Failure

2019-02-22T00:00:00+00:00

I encountered a weird error today attempting to run a .NET Core application hosted in IIS. The error was:

An error occurred while starting the application.

Well that’s a little vague. It worked fine in IIS Express. So I decided to restart my computer because that’s what I do when I need some time to think, and every once in a while it helps. In this case it actually did help by giving a different error message the first time I visit the page after a fresh restart:

HTTP Error 502.5 - Process Failure

Common causes of this issue:

The application process failed to start

The application process started but then stopped

The application process started but failed to listen on the configured port

It occurred to me that since this is an ASP.NET Core application that the ASP.NET Core module for IIS is attempting to launch an executable, which I can also execute at will. Running the executable directly gives me a clear indication of the problem on the console output – there’s an uncaught exception being thrown in Startup.cs:

There’s the problem! A missing config variable. I love when I don’t need to scour the internet with cryptic error codes. ASP.NET Core told me exactly what the issue was.

Real-time by accident

2019-01-22T00:00:00+00:00

Wednesday, 8:55 AM.

You get settled into your chair and log in. Time to get some work done.

…

9:35 AM.

You hear someone tapping on your doorway.

“The 8:00 AM daily batch job failed run. Can you look into it?”

9:51 AM.

You discover what happened. The 4:00 AM nightly batch job took longer than usual to run. Your excellent logging indicates it was processing an usually large set of data. In fact, it’s still running right now and it’s almost complete. You fire off an email to let the concerned know what’s going on and that you’ll restart the 8:00 AM job once the 4:00 AM job is done.

Crap! You’re late for the 10:00 AM standup.

…

11:05 AM.

You finally arrive back at your desk, quickly verify the 4:00 AM job finally finished, manually kick off the job that was supposed to run at 8:00 AM, and send another email letting the user know when the job finishes. It usually only takes 30 minutes or so. Try to get some work done in the meantime.

11:35 AM.

Crap, the job’s still running.

11:40 AM.

Still running…

11:45 AM.

The job’s done! Fire off a third email letting them know the issue’s resolved.

What do you know, it’s lunch time! Where’d the morning go?

Here’s where it went

You spent it babysitting a faux-real-time system.

It’s real-time in the sense that processing deadlines are imposed on the system. In our example, the 4:00 AM job has a worst-case execution time of 4 hours. It’s a hard deadline in the sense that the system fails if the jobs don’t complete on-time. It’s ‘faux’ in the sense that these constraints are unnecessary and engender a lot of serious drawbacks.

Scheduling batch jobs this way lends itself to tedious management of issues arrising from the inherent race conditions involved. Additionally, it’s difficult to determine the dependencies between the jobs since they appear more coincidental than explicit. This sort of knowledge is usually known by everyone but never defined anywhere. “Everyone knows the 4:00 AM job needs to be done before the 8:00 AM job starts!” And worst of all, these patterns tend to fail you just when you need them to work the most.

This pattern is usually borne out of a few reasons:

An attempt to sequence the jobs in a decoupled way,
The availability of ‘cron’-like job scheduling tools, and
The apparent lack of equivalently-available and simple alternatives.

So how can we get ourselves out of this mess? Are there any alternatives?

Potential solutions

Mutex locks (don’t do this)

One solution I’ve seen at a major international company was to keep the existing scheduling system and augment it with mutex locks. Specifically:

Create a dependency graph for every job.
When each job starts, attempt to obtain a lock on all dependencies that job depends on (including the job itself).
- In case of failure to obtain all the locks, release the locks and try again in several minutes.
- If all locks were successfuly obtained, start the job.
When the job finishes, release the locks that were obtained in order to start the job.

Although this approach worked in the short-term, it was fraught with issues. If a job goes longer than usual and causes other jobs to enter a retry state, you never know which of the retrying jobs will go next. Oftentimes you want them to go in chronological order, but retry logic doesn’t naturally enable this sort of behavior. You’d need to tack on some additional logic which looks at the other jobs and this quickly gets very convoluted.

There are other issues such as deadlocks and lost locks. Just stay away from this pattern.

Event sourcing/CQRS/Job queueing

Much smarter people than me have written about these patterns in vast detail, so I won’t waste time rehashing their work. In essence, we want to remove the timing-based scheduling and replace it with chaining or queueing. The end of one job should indirectly trigger the next job, ideally without the jobs knowing about each other.

This is roughly how it would look:

At 4:00 AM, a command is submitted to the command queue to start Job 1.
An agent picks up Job 1 and starts working on it. Once it ends the agent creates a “Job 1 completed” event.
The “Job 1 completed” event is translated into a command to start Job 2 and the command is subsequently submitted to the command queue.
An agent picks up the Job 2 command and starts working on it.

At its heart we’re literally linking the jobs together. In other words, when one job ends another quickly starts after it. The dependency is explicitly defined in code (a “Job 1 completed” event causes a Job 2 command to be submitted).

Sure, it’s possible that one job severely delays the other jobs, but in enterprise system that’s generally okay.

As the adage goes, better late than never.

New blog, who dis?

2018-11-24T00:00:00+00:00

So I got my new blog up and running in a matter of 10 minutes. Of course that doesn’t count all the hours spent deliberating between all the potential alternatives (Medium, WordPress, MkDocs, Blogger, etc). Nor does it count all the prerequisite knowledge it takes to understand how to do, well, anything. Nonetheless, I’m sticking with 10 minutes.

I ended up going with Jekyll on GitHub Pages for a few reasons:

I can edit my posts directly on GitHub and GitHub automatically recompiles the whole Jekyll site for me. This is immensely convenient.
Creating it was simply a matter of forking a repo and adjusting a couple variables.
The website is static once compiled, so I never need to worry about it going down.
My blog is portable, so if GitHub Pages goes away I can host it pretty much anywhere else.
I trust GitHub more than anyone to keep my code replicated and safe in case of a disaster scenario. Plus, I’ll always have a copy on my local machine by virtue of Git.
It’s 100% free.

OK sure that was more than just a few reasons. Gotta keep you on your toes. Hopefully the convenience factor will reduce the friction to a point that I’ll be willing to write more often. We shall see…