Stop coupling logic with your HTTP layer!
Tags: webdev, architecture, ruby
Published: 2018-10-30 19:11:41

---
title: Stop coupling logic with your HTTP layer!
published: true
description: Coupling logic with a specific communication layer is not desirable. Here's why.
tags: webdev, architecture, ruby
---

As a developer, there is one issue that I tend to notice in many codebases: **logic coupled with a specific communication layer**.

This issue is especially common in the **controllers** of most web backends, where application logic is usually intertwined with access to the HTTP layer. It is not surprising. Many documentation examples of some of the most well-known frameworks ([Rails][rails], [Django][django], [Flask][flask], [Phoenix][phoenix], etc.) have this issue.

[rails]: https://guides.rubyonrails.org/action_controller_overview.html#parameters
[django]: https://docs.djangoproject.com/en/2.1/intro/tutorial03/
[flask]: http://flask.pocoo.org/docs/1.0/quickstart/#a-minimal-application
[phoenix]: https://hexdocs.pm/phoenix/overview.html

But, what do I mean when I say "logic intertwined with access to the HTTP layer"? Let's take a look at how a simple login endpoint could be implemented in Ruby on Rails:

```ruby
class UsersController < ApplicationController
  def login
    user = User.find_by(email: params[:email])

    unless user.password_match?(params[:password])
      return error_response(:invalid_credentials)
    end

    json_response(auth_token: Tokens.auth(user))
  end
end
```

Simple, right? But... How do we use this `UsersController` class? How do we test our `login` logic? Who populates `params`? What data does it need? **The public contract of this code is not clear at all!** We have a class with a method that takes no arguments and uses internal (hidden) state to do its job.

**When code cannot be easily used in isolation, it becomes harder to understand, test and debug.** We should try to avoid it as much as possible.

The code above is tying the logic of the function to some specific communication layer (HTTP, in this case). Using `params` and `json_response` forces us to be aware of this layer every time that we want to use this `login` method.

We can isolate the logic of our endpoint:

```ruby
ApiLogin = ->(email:, password:) do
  user = User.find_by(email: email)
  return { data: nil, errors: [:invalid_credentials] } unless user.password_match?(password)

  { data: { auth_token: Tokens.auth(user) }, errors: [] }
end
```

This is now a communication-agnostic function. Its input  (`email` and `password`) and its output (a simple hash with `data` and `errors`) are explicit. Therefore, we can test it very easily:

```ruby
ApiLogin.call(email: "some@email.com", password: "12345678")
# => { data: { auth_token: "..." }, errors: [] }
```

Now, we just need to connect this function to our communication layer. We can use an `ApplicationController`, like before:

```ruby
class UsersController < ApplicationController
  def login
    response = ApiLogin.call(email: params[:email], params[:password])
    
    if response.fetch(:errors).empty?
      json_response(response.fetch(:data))
    else
      error_response(response.fetch(:errors))
    end
  end
end
```

The key point here is that this wiring does not contain any relevant logic that needs specific testing because it can be easily abstracted! Most of the time, connecting a function to an HTTP layer consists of the same steps:

  1. Obtain the input data from the request.
  2. Call a function with the obtained data.
  3. Transform the output of the function into an HTTP response.

With this in mind, we could write a Ruby DSL to produce custom controllers, like this:

```ruby
UsersController = Http.controller do
  action :login, ApiLogin, email: param(:email), password: param(:password)
end
```

And extend it as needed. For instance, we could implement `header` and `json` methods, analogous to `param`.

There are many ways to expose a function over HTTP. I personally like to build a pipeline of transformations where the input is the HTTP request and the output is the HTTP response, especially in functional languages with powerful type systems. This pipeline is defined safely and accurately step by step with a flexible API. I will write about how I did this in Haskell soon!

In conclusion, once we split logic from communication, we obtain some interesting benefits:

  * Our application logic becomes easier to use, understand and test.
  * The communication details can be centralized, changed and tested using a single-responsibility abstraction.
  * We can implement a new communication layer (a CLI, a different HTTP layer) to expose the same logic.

---

Let me know about your thoughts in the comments! Why do you think it's such a common issue? Are you already doing something similar?