Josh W Lewis

Error Handling in Elixir with Plug.Exception

2016-05-29T19:00:00-05:00

I found a hidden gem last week: Plug’s exception protocol. It gives you a concise pattern for rendering errors to users in an informative way.

For example, consider some team dashboard that you want to limit access to in your Phoenix application. You want to block non-admins and non-team-members from seeing it, but you also want to provide context that they were blocked and also why.

The most straightforward way to do this would just be a simple conditional in your controller. Like this:

defmodule MyApp.WidgetController do
  alias MyApp.{Repo, Team, Widget}

  def index(conn, %{"id" => team_id}) do
    user = get_current_user(conn)
    team = Repo.get(Team, team_id)
    if user.role == "admin" && team.id == user.team_id do
      # user is authorized; now we can load up the data
      widgets = Repo.all(Widget)
      render(conn, "show.json", %{widgets: widgets})
    else
      # user is not allowed access; tell them with a message and http status
      put_status(conn, 403)
      |> render(ErrorView, "403.json", %{message: "You need to be a team admin"})
    end
  end
end

For this to work, you’ll need to define a function to handle rendering the 403:

defmodule MyApp.ErrorView
  def render("403.json", %{message: message}) do
    %{
      status: 403,
      message: message
    }
  end
end

Now this works, and is clear and explicit. But it feels a bit verbose to me. We’re mixing authorization and retrieving data into the same function, and half the code is devoted to detecting and rendering the error. I was doing something like this, and after adding this to several controllers, the logic started to feel like a filibuster.

One important thing about Elixir that we should note here, is that there is no return keyword. There is no way to exit a function early. So we can’t just render and abort – the only way to end the function is to finish execution. With that in mind, here’s a way you could extract this logic.

defmodule MyApp.WidgetController do
  def index(conn, %{"id" => team_id}) do
    user = get_current_user(conn)
    team = Repo.get(Team, team_id)
    authorize(conn, user, team, fn ->
      widgets = Repo.all(Widget)
      render(conn, "show.json", %{widgets: widgets})
    end)
  end

  defp authorize(conn, user, team, callback) do
    if user.role =="admin" && team.id == user.team_id do
      callback.()
    else
      put_status(conn, 403)
      |> render(ErrorView, "403.json", %{message: "You need to be a team admin"})
    end
  end
end

Here, the index function is a little easier to read, and the authorize function encapsulates most of that logic. But this still feels long-winded for my taste.

Luckily plug provides a handy protocol for rendering exceptions, which Phoenix supports.

This is actually what Phoenix uses to render a 404 when Ecto.Repo.get!/2 fails. Phoenix has implemented the Plug.Exception protocol for some of the common Ecto errors.

defimpl Plug.Exception, for: Ecto.NoResultsError do
  def status(_), do: 404
end

To use it ourselves, we’ll start by defining your own Exceptions. For the above example, a new Forbidden exception makes sense. But you may want to add more. I have Unauthorized (401) and UnprocessibleEntity (422) in my app.

defmodule MyApp.Forbidden do
  defexception [message: "You do not have access to this resource.",
                plug_status: 403]
end

Now we have an exception that Plug knows how to handle. Whenever we raise this error, Plug knows to return an HTTP status of 403. We also defined a default message, which Phoenix will automatically pass to our ErrorView above.

Now, we can clean up our controller a bit.

defmodule MyApp.WidgetController do
  def index(conn, %{"id" => team_id}) do
    user = get_current_user(conn)
    team = Repo.get(Team, team_id)
    authorize!(user, team)
    widgets = Repo.all(Widget)
    render(conn, "show.json", %{widgets: widgets})
  end

  defp authorize!(user, team) do
    if user.role !="admin" || team.id != user.team_id do
      raise MyApp.Forbidden, message: "You need to be a team admin"
    end
  end
end

This is certainly more concise, and both functions are directly to the point.

There’s another advantage here that’s worth highlighting. This error can be raised anywhere within the life-cycle of a Plug request, and Plug will handle it. In the first examples, a function needed access to the conn struct to operate on it. Now it’s easy to raise an appropriate exception in any of your functions deeper in the stack (hopefully not in your models, though!).

Documentation on this feature is a bit sparse, but one thing I like about the Elixir ecosystem is that the code is accessible and easy to grok. I pieced this functionality together by from data scattered in these resources:

I feel like this was a pretty good improvement, and hopefully it helped you. I’d be eager to hear if you have any improvements.

Rails Unit Measurement Persistence

2014-03-08T18:00:00-06:00

I’ve worked on a few apps in the past that had some cumbersome constraints in regards to the units of measurement. Models needed to store heat transfer or fluid dynamics properties in either english or SI units. This is can be a bit of a pain, so I thought I’d share my methods and save someone else the trouble.

My problem scenario was in an engineering realm, but there are plenty of other mainstream domains that exhibit the problem. Consider foot races – they are commonly defined in either mileage (like 26.1 miles for a marathon) or kilometers (like a 5K). Or consider a mechanic’s wrenches – they have a metric set with sizes like 10 mm, but also have an english set with sizes like 5/8 inch.

To demonstrate the problem and solution, say you are creating an app for cooks. Maybe it would let cooks share recipes, perhaps it might be used to help them decide what to offer on tonight’s menu, or perhaps it just tracks ingredient inventory. In any of those cases, you probably need a model for a recipe and its ingredients.

# create_table :recipes do |t|
#   t.string  :name, null: false
# end
class Recipe < ActiveRecord::Base
  has_many :ingredients
end

# create_table :ingredients do |t|
#   t.string  :substance,     null: false
#   t.decimal :quantity,      null: false,  default: 0
#   t.integer :recipe_id
# end
class Ingredient < ActiveRecord::Base
  belongs_to :recipe
end

So, these are some pretty typical models. Sure, they are overly simplified. In any case, we can setup a new ingredient pretty easily.

Ingredient.create(substance: 'Olive Oil', quantity: 1)

Now we can see the problem. The obvious question here is how much olive oil is ‘1’? Is that one teaspoon, tablespoon, ounce, or maybe even pint or gallon?

In a lot of apps, you might just have some tribal knowledge where everyone understands that we store quantities in tablespoons. That might be fine in a lot of cases. But, say we need to know how much olive oil to buy for next week. Can we buy olive oil by the tablespoon? My olive oil usually comes in 750 ml bottles. How many tablespoons is that?

It just so happens that I’ve built a tool for that. Unitwise is a Ruby library for converting and performing math on all kinds of units, volumes included.

Say our grand total of estimated olive oil usage for the week was 1000 tablespoons. With Unitwise, we could calculate how many bottles of olive oil is required.

(1000.tablespoon / 750.ml).to_f # => 19.715686375000004

Helpful, but there is a little more we can do here. Instead of relying on tribal knowledge about storing the quantity in tablespoons, we could make it explicit.

class Ingredient < ActiveRecord::Base
  def quantity
    read_attribute(:quantity).to_tablespoon
  end
end

With this modification, each time we retrieve the quantity, we’ll get a measurement back with a value and a unit.

Ingredient.last.quantity # => #<Unitwise::Measurement value=1 unit=tablespoon>

Unitwise comes with a handy to_s method that should get invoked by your views, which means you can display this value to your users as '1 tablespoon'.

Cool, but we can make this a little better yet.

class Ingredient < ActiveRecord::Base
  def quantity
    # unchanged from above
  end

  def quantity=(value)
    write_attribute(:quantity, value.to_tablespoon)
  end
end

Now we have the advantage of setting the quantity with any unit compatible with tablespoons – that is, any volumetric unit.

tomatoes = Ingredient.create(name: 'Crushed tomatoes', quantity: 8.fluid_ounce)
tomatoes.quantity # => #<Unitwise::Measurement value=16 unit=tablespoon>

With this change, we can now set the quantity with any compatible unit. When we retrieve the value, it comes back in tablespoons.

We are definitely making progress here. All the values stored and retrieved are based on tablespoons, no matter what unit you set it with. But, who buys tomatoes by the tablespoon? When the amount of tomatoes is displayed to the user, they probably just want to know how many cans (8 fluid ounces) or cups to use.

Lets make one more enhancement. This time, we are going to add a string column to the ingredients table so we can display an appropriate unit for any ingredient.

# create_table :ingredients do |t|
#   t.string  :substance,     null: false
#   t.decimal :quantity,      null: false,  default: 0
#   t.string  :quantity_unit, null: false,  default: 'tablespoon'
#   t.integer :recipe_id,     null: false
# end

class Ingredient < ActiveRecord::Base

  def quantity
    read_attribute(:quantity).convert_to(self.quantity_unit)
  end

  def quantity=(value)
    write_attribute :quantity, value.to_tablespoon
    if value.respond_to?(:unit)
      self.quantity_unit = value.unit.to_s
    end
  end

end

Now we’ve got something solid. Now all database entries are stored in the same unit (tablespoon), which is nice, in case some other program or query wants to do something with that data. And now whatever unit we set the quantity with is what gets read into the model. For example:

water = Ingredient.create(substance: 'Water', quantity: 1.cup)
water.quantity # => #<Unitwise::Measurement value=1 unit=cup>

beer = Ingredient.create(wine: 'Beer', quantity: 1.pint)
beer.quantity # => #<Unitwise::Measurmeent value=1 unit=pint>

This example is fairly simple, but it should give you an idea of how to do something similar in your own domain. Unitwise supports a ton of units, and has some other really nice features – Check it out.

Unitwise: Ruby Unit Measurement Math and Conversion

2013-08-12T19:00:00-05:00

So, way back in Mechanical Engineering school, I learned that a very effective way to check my answers was to make sure the units worked out. For an example, consider a basic physics problem:

The average mass of an adult American male is 86 kilograms. Determine weight of an average man on the moon where the gravitational field is one-sixth that of the Earth (9.8 m/s²).

If you paid attention in physics, you would work it out like this:

  mass = 86 # 86 kg
  acceleration = 9.8 / 6 # 1.633334 m/s2
  force = mass * acceleration 
  # => 140.4666666666667

Ok, so 140 – but 140 what? Since we effectively performed ‘kg * m/s²’ it’s plain to see that our unit is 'kg⋅m/s²’. Ok, great, so our unit result is in the form of a mass times an acceleration, just as we would expect to see when calculating a force. When you are using a pen and paper, this is a great way to make sure your result is what you expect (your force is a measurement force, your energy is a unit of energy).

But using straight up Numerics for calculation through Ruby means that we lose track of units. As the calculation gets more complicated, manual unit checking becomes monotonous and error-prone. On emergentcoils.com I’ve had to do a fair amount of these types of calculations (namely heat transfer capacities), and I was getting tired of trying to remember what unit a Numeric value was in.

So, like any good Rubyist, I searched for a RubyGem that could track units as I performed math on them. There are a couple already out there (most notably ruby-units), and they certainly work for many (or probably most) situations. However, they either didn’t have a few of the units I needed or they only did conversion (not Math).

During my search, I ended up stumbling across The Unified Code for Units of Measurement (UCUM) – which had all the units I needed ready to go in XML format. From that Unitwise was born.

Now, it’s really easy to track units for our example problem:

mass = 86.kg
# => <Unitwise::Measurement 86 kg>
acceleration = 9.8.convert_to('m/s2') / 6
# => <Unitwise::Measurement 1.6333333333333335 m/s2>
force = mass * acceleration
# => <Unitwise::Measurement 140.4666666666667 kg.m/s2>

And of course it does conversion:

mass.to_pound
=> <Unitwise::Measurement 189.5975454789947 pound>

force.to_newton
=> <Unitwise::Measurement 140.4666666666667 newton>

Obviously, this is a very simple example, but the possibilities are certainly endless. UCUM (and by extension Unitwise) features 95 metric units, 199 non-metric units, and 24 unit prefixes. That’s approximately 2,500 basic units to start you with, but these can be combined with multiplication and division for infinite combinations.

You can find Unitwise at github.com/joshwlewis/unitwise. Check out the README there for installation and additional usage instructions.

Rails' ActiveSupport try

2013-04-25T19:00:00-05:00

ActiveSupport has a few great Ruby extensions that I just love. One of my favorites is try.

.try()

Try is a sneaky method for handling NoMethodErrors on NilClass. If you ever get stuck writing code like this:

name = user.name unless user.nil?

Consider using try instead:

name = user.try :name

It’s basically like using send, but it will return nil if the receiver is nil.

Here it works like send:

user = User.new name: "Josh"    #=> #<User>
user.send :name                 #=> "Josh"
user.try :name                  #=> "Josh"

And here it doesn’t blow up with a NoMethodError:

user = nil                      #=> nil
user.send :name                 #=> NoMethodError
user.try :name                  #=> nil

EDIT: I still find try helpful in some cases, but I think it’s best to exercise caution with it. Many times delegation or the null object pattern can solve your problem a little more eloquently. If you find yourself chaining try you should probably look at another way to factor your code.

Rails Flash Messages with Twitter Bootstrap

2013-03-01T18:00:00-06:00

When building new Rails projects, I often use Bootstrap because it lets me focus more on the business logic, rather than design. Almost everytime I start one of these projects, I forget how I did flash messages the last time, and have to look at a past project or refer to Bootstrap’s documentation.

So, for my reference, and maybe your gain, this is the method that works for me.

- flash.each do |k,v|
  - bootstrap_class = {alert: 'alert-error', notice: 'alert-success', info: 'alert-info'}[k]
  %div{class: [:alert, bootstrap_class]}
    %button.close{data:{dismiss: :alert}} ×
    = v

This partial renders all flash messages (In the rare case that you have more than one), and matches the flash type to the bootstrap class. It also uses lets users close the messages (via bootstrap-transitions.js or bootstrap.js)

Static Site Creation with Middleman

2013-02-09T18:00:00-06:00

I’ve put off building my personal website for a while. I’m a Rails developer, so it would be fairly straight forward to build a blogging application and host it somewhere. But, that seemed like a lot of overhead – content management system, database, and a VPS to host it on. It just didn’t seem worth the expense and effort for a hobby site. Sure, I could hand build a simple html site, but I’m used to the conveniences of helpers and templating languages that make building html easy.

Enter Static Site Generators

Turns out there are tools out there to bridge the gap. They let you use all the great tools for making development easier, but compile to static HTML files. Some examples of these:

Jekyll
Octopress
Middleman
Nanoc

I won’t go into the virtues of each of these, but my eventual choice was Middleman.

Middleman

It’s built on Ruby, and it’s got a bunch of Rails already baked in. For example…

I can use link_to, just like Rails:

link_to "Home", "/"

Or render a partial, just like Rails:

partial :article_preview, :locals => {:article => article}

I can use Haml for layouts, just like Rails:

#page
  .container
    %section.content= yield
    - if blog.articles.present?
      %footer.explore.center

And I can even write some Ruby to keep things DRY:

def sentence_tag_list(article)
  if tags = article.tags
    "This article was filed under " +
    content_tag(:div, class: :tags) do
      article.tags.map{|t| link_to t, "/essays/categories/#{t}"}.to_sentence
    end
  end
end

Best of Both Worlds

So in development, I can use Ruby, Sass, Coffeescript, Markdown, and Haml. So it’s a pleasure to build sites, and I’m a happy developer.

When it’s all ready to go, I build the static files and push to any static file web server. The advantage here is that I can deploy it basically anywhere, and because it’s just static files, the web server can be highly optimized for caching…

So its BLAZING FAST.

VY8FZ2Z9FUU2