Ruby on Rails Engines is one of the most powerful and underestimated features. It distinguishes Rails from other web frameworks.

What engines?

Engines are embeddable applications that can be integrated into your Ruby on Rails application. They are distributed as regular Ruby gems with models, controllers, and views.

The UI that comes with engines is incredibly useful, and most engines can be set up within 10 minutes, saving months of integration of microservices and external SaaS tools.

Here are the top eight Ruby on Rails engines:

1. Sidekiq - background jobs
2. Blazer - business intelligence
3. Lookbook - UI components previews
4. Flipper - Feature toggles
5. Split - A/B testing
6. PGHero - PostgreSQL monitoring
7. FastEntry - cache previewer
8. GraphiQL - GraphQL IDE

1) Sidekiq

Sidekiq is the de facto standard for background jobs in Ruby land. The engine provides a UI to monitor what is happening with your background jobs.

2) Blazer

Blazer allows you to write SQL queries and build charts and dashboards from them, making it an excellent tool for business intelligence.

But even if you don't use it as a business intelligence tool. It is a great developer tool. It can help you see what is in your database in local or staging environments.

3) Lookbook

I found this recently.

If you use ViewComponents to build UI elements instead of Action View Helpers, you should use it. It builds on top of previews and wraps them in Storybook like interface.

However, if you have ever tried to set up Storybook and React components, you have spent A LOT of time on it.

This gem takes about 10 minutes to set up, and the rest is just writing simple previews Ruby classes.

4) Flipper

Flipper provides infrastructure and UI for Feature toggle.

I have written before how to integrate with React - here.

Flipper has a paid version with features like permissions and audit history.

5) Split

Split provides infrastructure for A/B testing.

There are a lot of SaaS tools to do so; however, they are slowing your pages, cost a lot and take time integrate.

6) PGHero

It provides a performance dashboard PostgreSQL. It tells you things like - slow queries, unused indexes, table/index sizes, and more.

It comes from ? Instacard, which makes also Blazer and other wonderful open source projects.

7) FastEntry

Do you know what is in your cache? FastEntry shows you this. Simple and useful.

I have found a secondary use for it in development. I use the same Redis instance for cache, Sidekiq, and application data storage. It shows you everything in this Redis instance.

8) GraphiQL

Last but not least. GraphiQL is IDE for GraphQL. This engine provides quick setup and integration.

How to setup and secure engines?

I mentioned that engines are easy to set up. But talk is cheap. Let me show you the code. ?

Let's install Blazer, as it is one of the more complex ones to set up.

Step 1: Add to Gemfile

gem "blazer"

Step 2: Bundle install & database setup

bundle install

rails generate blazer:install
rails db:migrate

Step 3: Mount to the Rails application

# config/routes.rb
namespace :dev, constraints: Routes::AdminConstraint do
  mount Blazer::Engine, at: '/blazer'
  # ... other engines
end

Note: Routes::AdminConstraint ensures that this namespace is only available for certain users.

A simplified version can look something like:

module Routes::AdminConstraint
  extend self

  def matches?(request)
    return false if request.session[:user_id].blank?

    User.find(request.session[:user_id]).admin?
  end
end

In Production: Have database as ENV variable

ENV["BLAZER_DATABASE_URL"] = "postgres://user:password@hostname:5432/database"

That's it, you have a business intelligence tool ?

Conclusion

Engines have saved me a lot of time (and use of external services) over the years. I'm constantly on the lookup for new useful ones ?

If you have any questions or comments, you can ping me on Twitter or Mastodon.

Our applications rarely work in isolation. Gone are the days where your app is just talking to a single database and storing files to local disc. Nowadays, apps talk to many external services like Sentry, Stripe, Twitter, etc.

External services are often added one by one in various places in a system, and it is easy to lose track of them. Because of this, at Product Hunt we have strict rules for dealing with external services. This blogs post shows and explains those rules.

Our main goals are to isolate those external services and to make it easy for team members to know why and how services are used.

1. Keep all services in a single place

All external services live in the app/services/external folder and are namespaced under the External module. All network-related code goes there. This includes calls to microservices we wrote ourselves.

In this way, we can see most of the outcoming network calls from our application just by opening this folder.

2. Wrap the external services in a facade module

All external services are accessed via External::[Service]Api facade module.

The following is our template for such a module.

# frozen_string_literal: true

# Documentation
#
# - service: [url to service]
# - manage: [url to manage tokens]
# - api: [url to api documentation]
# - gem: [gem we are using (optional)]
# [- ... other links]

module External::[Service]Api
  extend self

  # documentation: [documentation]
  def perform_action(args)
    # use HTTParty or gem for this external service
  end
end

Usually, the API facades are just a bag of module methods.

Here is an example from our External::UnsplashApi:

# frozen_string_literal: true

# Documentation
#
# - service: https://unsplash.com/
# - api: https://unsplash.com/documentation
# - gem: https://github.com/unsplash/unsplash_rb
# - portal: https://unsplash.com/oauth/applications

module External::UnsplashApi
  extend self

  def search(query)
    Unsplash::Photo.search(query, 1, 12, 'landscape')
  end

  def track_download(id)
    photo = Unsplash::Photo.find(id)
    photo.track_download
  rescue Unsplash::NotFoundError
    nil
  end
end

Even when the external service has a gem to access it, the gem is never used outside this module.

If the gem returns an instance of a response object, we try to wrap it with a class defined by us. We started wrapping those response objects quite late.

We expose only what we use from the services.

3. Storing credentials

Rails added support for encrypted credentials. Our newest applications use this mechanism for storing external services secrets.

We use the following commands to work with credentials.

EDITOR=vim rails credentials:edit --environment development
EDITOR=vim rails credentials:edit --environment production

Credentials are stored in YAML. We always include a link to where a certain credential was taken because it is very irritating to search where token and secret was taken from—especially when dealing with Google APIs.

# Taken from: [url to where those credentials are taken]
[sevice_name]_token: [...]
[sevice_name]_secret: [...]

Conclusion

We are structuring our external services for the following reasons:

• Know precisely which services are external to the system
• Make it evident that we are interacting with an external system where network calls are involved
• Have an obvious surface area of external service, where we know what exact features we are using from them
• Having a facade makes it easier to add proper logging, caching, and error handling
• Simpler upgrade paths of APIs -- if an external gem has a breaking change, it only affects the facade object

Mutations in GraphQL ... mutate data. ?

At the time of this writing, Product Hunt codebase and related projects have 222 mutations. All of our mutations have the same structure. This enables us not only to have a consistent system but to build a lot of tooling around it to make our developer's life easier.

Here the Product Hunt guide on structuring GraphQL mutations:

Naming

There are only two hard things in Computer Science: cache invalidation and naming things
-- Phil Karlton

We have decided to name our mutations in the following pattern:

[module][object][action]

Here are some examples:

CommentCreate
CollectionPostAdd
PostVoteCreate
PostVoteDestroy
PostSubmissionCreate
ShipContactCreate
ShipContactDestroy

The reason to follow this approach is consistency and easier grouping. Autocompleting mutations names is even easier because you filter from module to object to the action.

Mutation shape

This is how a typical mutation looks like:

mutation CollectionPostAdd($input: CollectionPostAddInput!) {  
  response: collectionPostAdd(input: $input) {      
    node {
       id
       ...SomeFragment
    }    
    errors {    
      name  
      messages
    }
  }
}

It has the following elements:

• it is Relay compatible
• the result object is always named node
• it always has error array for user input validations
• in frontend we alias the mutation to “response.”

Let look at each one of those elementals:

Relay compatibility

We are using Apollo in our frontend. However, we try to have Relay comparable scheme, just in case this situation changes.

In order for a mutation to be Relay compatible, it is required to have a field named clientMutationId and accepted all of its arguments as inputs variable. inputs contains all arguments.

We tend to use clientMutationId when we don’t care about the mutation result. For example - TrackEventCreate .

inputs is more interesting. It is an input type, containing all values needed for the mutation.

It makes it very easy to work with Forms. Because we have a single argument object to hold the form state, we can just pass this object to the mutation. When we add/remove arguments from a given mutation, we don't have to change the mutation call at all.

I really like this concept.

Node field

We noticed that most mutations operate on a single object. Because Relay uses the term node a lot (example - connections). We decide to name the object returned from the mutation - node. This makes it easier for the frontend to handle it since it knows what to expect and where to look for it. Plus backend mutation can just return an object, making defining mutations in the backend easier.

In some rare occasions, we might need a second object to be returned from mutation. We support this.

Errors field

There are a lot of debates on how to handle mutation errors. Should the GraphQL error system be used, or should we return an array of error objects?

I prefer returning error objects. I split the errors into two buckets based on their cause:

1. those caused by system error
2. those caused by a user input error

In Product Hunt, we handle system errors with GraphQL system error, and we handle user input errors with error objects. Because of this, all our mutations have error fields, which return an array of Error objects:

type Error {
  name: String!
  messages: [String!]!
}

Our BaseMutation knows how to return it and our Form.Mutation knows how to map the errors to its input fields.

We use the name base for errors which can’t be attached to a particular field. Example: "you posted too many posts for today".

I have written about this before ? here.

Response alias

We alias the mutation field name to response, so we can simplify our frontend code:

const response = await mutation({ variables: $input });


responseNode(response)
responseErrors(resoonse)

Notice that this code applies to every mutation we have.

Backend tooling

BaseMutation

If you are working by schema first, enforcing those rules will be quite painful.

In Product Hunt, we use the revolver first approach to GraphQL development. We have a lot of built-in tools on top of GraphQL ruby gem.

One of those tools is BaseMutation. Every mutation in our system uses it.

Here is an example:

module Graph::Mutations
  class CollectionPostAdd < BaseMutation
    argument_record :collection, Collection, authorize: :edit
    argument_record :post, Post
    argument :description, String, required: false

    returns Graph::Types::CollectionPostType

    def perform(collection:, post:, description: nil)
      Collections.collect(
        current_user: current_user,
        collection: collection, 
        post: post, 
        description: description
      )
    end
  end
end

• it generates consistent mutations.
• it can fetch records
• it handles authorization
• it knows how to map returns to node field
• it knows how to handle raised errors from Ruby on Rails, validation, authorization and similar

The developer just has to think about:

• what is your input
• what are you returning
• what are the authorization rules
• implement

All the mechanics are handled by this class.

This is how we define mutations:

module Graph::Types
  class MutationType < Types::BaseObject
    # we have this small helper to reduce the noise when defining mutations
    def self.mutation_field(mutation)
      field mutation.name.demodulize.underscore, mutation: mutation
    end

    mutation_field Graph::Mutations::CommentCreate
    mutation_field Graph::Mutations::CollectionPostAdd
    mutation_field Graph::Mutations::PostVoteCreate
    mutation_field Graph::Mutations::PostVoteDestroy
    mutation_field Graph::Mutations::PostSubmissionCreate
    mutation_field Graph::Mutations::ShipContactCreate
    mutation_field Graph::Mutations::ShipContactDestroy

    # ...
  end
end

Frontend tooling

Having all wiring in the backend makes it very easy to build tooling for frontend. I already mentioned responseNode and responseErrors. We have them, but in reality, we use Form.Mutation and MuttationButton more.

Form.Mutation

I have written and spoken about this before. Here is a link to a post about it, and here is a link to a presentation about forms in general (here is a recording)

<Form.Mutation onSubmit={onComplete}>
  <Form.Field name="title" />
  <Form.Field name="email" control="email" />
  <Form.Field name="description" control="textarea" />
  <Form.Field name="length" control="select" options={LENGTH_OPTIONS} />
  <Form.Field name="level" control="radioGroup" options={LEVEL_OPTIONS} />
  <Form.Field name="speakers" control={SpeakersInput} />
  <Form.Submit />
</Form.Mutation>

This form handles:

• provides consistent UI for forms
• map fields and arguments
• knows how to pass inputs to mutation and interpret results
• protects against double submit
• handles validation errors and map them to fields
• handles the successful submission and passes node to onSubmit handler

MutationButton

The second main way mutations are triggered by buttons. We have a React component name MutationButton:

function LikeButton({ post, onLike }) {
  const mutation = post.isLiked ? DESTROY_MUTATION : CREATE_MUTATION;
  const optimistic = post.isLiked ? optimisticDestroy : optimisticCreate;

  return (
    <MutationButton
      requireLogin={true}
      mutation={mutation}
      input={{ postId: post.id }}
      optimisticResponse={optimistic(post)}
      onMutate={onLike}
      active={post.isLiked}
      icon={<Like Icon />
      label={post.likesCount}
    />
  );
}

This button handles:

• triggering the mutation with right arguments
• protects against double click
• handle optimistic updates
• handles clicks from not logged in users
• knows how to interpret the result of the mutations

Conclusion

Having all those structure and tooling around mutations helps the developers to focus on business logic and not worry about mechanics. This is a big win in my book.

Polymorphic associations in ActiveRecord are very useful. Especially for attachable models like Comments, Attachments, Likes. However, sometimes we define them too loosely.

Here is an example of a Comment model. Its subject is polymorphic, allowing us to add comments to any ActiveRecord model.

class Comment < ApplicationRecord
  belongs_to :subject, polymorphic: true, inverse_of: :comments
end

Two things are bothering me with this code:

1. What are all possible subject types?
2. Any model can have comments. What if I don't want that?

To address my worries, I explicitly list and validate all allowed classes.

class Comment < ApplicationRecord
   SUBJECT_TYPES = [Post, Message, Category, Discussion::Thread]
   
   belongs_to :subject, polymorphic: true, inverse_of: :comments

   validates :subject_type, inclusion: { in: SUBJECT_TYPES.map(&:name) } 

This solves my issues.

I need this functionality basically everywhere where I have a polymorphic association. So, I moved it to "ApplicationRecord".

class ApplicationRecord < ActiveRecord::Base
  self.abstract_class = true

  class << self
    def belongs_to_polymorphic(name, allowed_classes:, **options)
      belongs_to name, polymorphic: true, **options
      validates "#{name}_type", inclusion: { in: allowed_classes.map(&:name) }
      define_singleton_method("#{name}_types") { allowed_classes }
    end
  end
end

All ActiveRecord models inherit from "ApplicationRecord":

class Comment < ApplicationRecord
  belongs_to_polymorphic :subject, allowed_classes: [Post, Message, Category, Discussion::Thread]
end

When I extracted this. I noticed another pattern, I almost always do with polymorphic associations. Adding named scopes for each of the corresponding models.

class Comment < ApplicationRecord
  belongs_to_polymorphic :subject, allowed_classes: [Post, Message, Category, Discussion::Thread]

  scope :with_subject, ->(subject_class) { where(subject_type: subject_class.name) }
  scope :with_subject_post, -> { with_subject(Post) }
  scope :with_subject_message, -> { with_subject(Message) }
  scope :with_subject_category, -> { with_subject(Category) }
end

Since we already have ApplicationRecord.belongs_to_polymorphic we can add this functionality there.

class ApplicationRecord < ActiveRecord::Base
  self.abstract_class = true

  class << self
    def belongs_to_polymorphic(name, allowed_classes:, **options)
      belongs_to name, polymorphic: true, **options
      validates "#{name}_type", inclusion: { in: allowed_classes.map(&:name) }
      define_singleton_method("#{name}_types") { allowed_classes }
      
      # generates a generic finder method
      define_singleton_method("with_#{name}") do |type|
        type = case type
               when Class then type.name
               when String then type
               else type.class.name
               end
        where("#{name}_type" => type)
      end

      # generates scope for each allowed class
      allowed_classes.each do |model|
        scope "with_#{name}_#{model.name.underscore.tr('/', '_')}", -> { where("#{name}_type" => model.name) }
      end
    end
  end
end

Conclusion

Having belongs_to_polymorphic cleaned up a lot of my models.

• I can clearly see what models are used as a subject for the relationship
• I have validations to ensure the proper models are being used
• I have a standardly named scope and finder methods

In Part 1, I was showing how at Product Hunt we use GraphQL::Batch to solve N+1 when loading associations.

Those are the obvious first candidates for optimization in the GraphQL world.
But the N+1 queries is hidden in a lot of places.

For example, let's say we have the following query:

query {
  posts(date: 'today') {
    id
    name
    isVoted
  }
}

This isVoted returns whether the current user (viewer) have voted for this post.

The naive implementation would be something like:

class Graph::Types::PostType < GraphQL::Schema::Object
  field :id, ID, null: false
  # ..
  field :is_voted, function: Graph::Resolvers::IsVotedResolver.new
end

class Graph::Resolvers::IsVotedResolver < GraphQL::Function
  type !types.Boolean

  def call(post, _args, ctx)
    # handle not-logged in users
    return false unless ctx.current_user?

    # check if user have voted for a post
    ctx.current_user.votes.where(post_id: post.id).exists?
  end
end

This generates the following queries:

SELECT * FROM posts WHERE DATE(featured_at) = {date}
SELECT * FROM votes WHERE post_id={post.id} and user_id={user_id}
SELECT * FROM votes WHERE post_id={post.id} and user_id={user_id}
SELECT * FROM votes WHERE post_id={post.id} and user_id={user_id}
SELECT * FROM votes WHERE post_id={post.id} and user_id={user_id}
SELECT * FROM votes WHERE post_id={post.id} and user_id={user_id}
SELECT * FROM votes WHERE post_id={post.id} and user_id={user_id}
SELECT * FROM votes WHERE post_id={post.id} and user_id={user_id}
-- ...

Those are N+1. But there isn't a build in solution in Rails for those. Because of this, they are often unaddressed.

The solution we have in Product Hunt for this problem as of most of N+1 is to uses GraphQL::Batch:

class Graph::Resolvers::IsVotedResolver < GraphQL::Function
  type !types.Boolean

  def call(post, _args, ctx)
    # handle not-logged in users
    return false unless ctx.current_user?

    # `.for` ensures we get the same loader instance
    loader = VotesLoader.for(ctx.current_user)
    # `.load` adds the post id to the list of things to load
    loader.load(post.id)
    # return a future promise for this particular post load
    loader
  end

  class VotesLoader < GraphQL::Batch::Loader
    def initialize(user)
      @user = user
    end
    
    # this gets called after all `isVoted` were collected
    def perform(post_ids)
      # THE TRICK: load with one query only the voted post id from votes, not all posts
      voted_post_ids = @user.votes.where(post_id: post_ids).pluck(:post_id)

      # fulfill the future promises
      post_ids.each do |post_id|
        fulfill post_id, voted_post_ids.include?(post_id)
      end
    end
  end
end

This now generates only two queries.

SELECT * FROM posts WHERE DATE(featured_at) = {date}
SELECT post_id FROM votes WHERE post_id IN ({post_ids})

This problem exists with normal Rails applications. It isn't GraphQL specific. But I have rarely seen this being addressed. With GraphQL::Batch we can elegantly solve this problem.

When people see GraphQL their first question - what about N+1 problems.

This is a legit question. In Product Hunt as in every GraphQL powered project, we have the same issues.

For example, let's say we have the following query:

query {
  posts(date: 'today') {
    id
    name
    slug
    topics {
      id
      name
      slug
    }
  }
}

And the following type definition for a post:

class Graph::Types::PostType < GraphQL::Schema::Object
  field :id, ID, null: false
  field :name, String, null: false
  field :slug, String, null: false
  field :topics, [Graph::Types::TopicType], null: false
end

This would result the following queries:

SELECT * FROM posts WHERE DATE(featured_at) = {date}
SELECT * FROM topics JOIN post_topics WHERE post_id = {post_id}
SELECT * FROM topics JOIN post_topics WHERE post_id = {post_id}
SELECT * FROM topics JOIN post_topics WHERE post_id = {post_id}
SELECT * FROM topics JOIN post_topics WHERE post_id = {post_id}
SELECT * FROM topics JOIN post_topics WHERE post_id = {post_id}
SELECT * FROM topics JOIN post_topics WHERE post_id = {post_id}
-- ...

All those N+1s SQL queries ?

We don't only have additional queries but when a couple of posts have the same topics we load those multiple times.

The best solution, I have found to this problem so far was to use GraphQL::Batch gem from Shopify.

Adding the gem to your project is simple.

class Graph::Schema << GraphQL::Schema
  # ...

  use GraphQL::Batch

  # ...
end

The way batching works: Instead of executing the query immediately, it returns an instance of GraphQL::Batch::Loader. The same instance of a loader object is returned for a given field leaf. After all fields for a given GraphQL query leaf are collected, then the perform method of the loader is called with all requested records. preform then must load and return for each record the requested data.

Here is how are going to solve the N+1 for topics with GraphQL::Batch.

First, we change the post type to use a new resolver.

class Graph::Types::PostType < GraphQL::Schema::Object
  # ...

  field :topics, [Graph::Types::TopicType], null: false, function: Graph::Resolvers::Posts::TopicsResolver.new
end

Define the resolver itself:

class Graph::Resolvers::Posts::TopicsResolver < GraphQL::Function
  def call(post, _args, _ctx)
    # `.for` makes sure we return the same loader instance
    # so all leaves, so we can group data
    loader = TopicsLoader.for
    # adds a post to the list of posts to be loaded
    loader.load(post)
    # returns the loader, not the actual topics
    # this gets transformed into topics afterward
    loader
  end

  # Loaders represent promises and mechanism to 
  # postpone loading until we have all posts in the list
  class TopicsLoader < GraphQL::Batch::Loader
    # perform called with all the posts
    def perform(posts)
      # this is the built-in active record mechanism to 
      # preload associations into a group of records
      # association are loaded with the minimum amount of queries
      # if a couple of posts have same topics they would be loaded once
      ::ActiveRecord::Associations::Preloader.new.preload(posts, :topics)
      
      posts.each do |post|
        # returns topics for every post in the list
        fulfill post, post.topics
      end
    end
  end
end

Now we have a lot less queries ?

SELECT * FROM posts WHERE DATE(featured_at) = {date}
SELECT * FROM topics JOIN post_topics WHERE post_id IN ({post_ids})

Also, each topic is loaded only once ?

Since loading associations is a very typical problem, I have created a generic AssociationLoader. It can be found in this gist.

class Graph::Types::PostType < GraphQL::Schema::Object
  # ...

  field :topics, [Graph::Types::TopicType], null: false, function: Graph::Resolvers::AssociationResolver.new(:topics)
end

During the Christmas break me and Mike were discussing a new feature at Product Hunt. The feature required scheduling an ActiveJobs when a user signs up, votes or submits a comment.

There is SignUp object which handles user registration. So scheduling a new background job there is quite simple:

module SignUp
  # ... handle user sign up

  def after_sign_up(user)
    WelcomeEmailWorker.perform_later(user)
    WelcomeTweetWorker.perform_later(user)
    SyncProfileImageWorker.perform_later(user)
    NewFancyFeatureWorker.perform_later(user) # <- new worker
  end
end

Unfortunately after_sign_up method was becoming quite large ☹️
Now imagine having to add NewFancyFeatureWorker to 10 other places ?

Those issues pushed us to create a simple wrapper around ActiveJobs, which we call KittyEvents.

Now in SignUp there is just one trigger for an "event":

module SignUp
  # ... handle user sign up

  def after_sign_up(user)
    ApplicationEvents.trigger(:user_signup, user)
  end
end

And there is a central place, where events are mapped to ActiveJobs Workers:

# config/initializers/application_events.rb
module ApplicationEvents
  extend KittyEvents

  event :user_signup, [
    WelcomeEmailWorker,
    WelcomeTweetWorker,
    SyncProfileImageWorker,
    NewFancyFeatureWorker, # <- new worker
  ]

  # ... other events
end

When an event is triggered, all ActiveJobs Workers for this events are scheduled and executed.

Another bonus, is when using KittyEvents, you only make a single Redis call to trigger any number of events. This shaves off precious milliseconds when using KittyEvents in request.

Ruby on Rails 5 has arrived. Though, I don't care much about the big features. I'm more excited about the smaller features, which would not change my life, but will make it a bit easier.

API mode improvements

Most of my work in Rails projects, these days is just using Rails as an api endpoint. There are lots of improvements.

I'm really glad we finally got ActionController::API.

Easier conversion of errors to JSON

Returning consistent and usable error messages is vital when designing and API.

Previously getting usable validation errors from rails was quite painful. Since you can only have:

user.errors.messages # => {:email=>["can't be blank"]}

This error message is it quite hard for clients. In several projects, I have defined a json locale where things like "can't be blank" is just "blank" and used that for the api.

But this is no more! Since errors.details exists now:

user.errors.details # => {:email=>[{:error=>:blank}]}

Better exceptions in development

Speaking about errors. There is a new option debug_exception_response_format:

# config/environments/development.rb
config.debug_exception_response_format = :api

You will get exception information in JSON format during development, instead of HTML.

ActiveJob improvements

In a previous post - Retrying ActiveJob, there was a glue code depending on a Rails 5 feature - ActiveJob::Base#deserialize. Now that can be removed.

Also having the ApplicationJob makes including the ActiveJobRetriesCount from the post easier:

class ApplicationJob < ActiveJob::Base
  include ActiveJobRetriesCount
end

ActiveRecord improvements

• better and more stable migrations,
• where.or
• ApplicationRecord.
• New Attributes API

And even more

There is, even more, stuff like redirect_back or ActiveModel::AttributeAssignment. But for more information I encourage you to check:

• BigBinary Rails 5 coverage
• The official Ruby on Rails release notes

Overall I think this is a solid release.

I have heard on The Bike Shed that there are discussions about changing the release process and to smaller and more frequent release cycle. I think this would be great. Especially since the features, I'm mostly excited usually are smaller and don't require a major version change.

I like ActiveJob. One missing feature is the ability to retry when a job fails. Fortunately, this is quite easy to add:

module ActiveJobRetriesCount
  extend ActiveSupport::Concern

  included do
    attr_accessor :retries_count
  end

  def initialize(*arguments)
    super
    @retries_count ||= 0
  end

  def deserialize(job_data)
    super
    @retries_count = job_data['retries_count'] || 0
  end

  def serialize
    super.merge('retries_count' => retries_count || 0)
  end

  def retry_job(options)
    @retries_count = (retries_count || 0) + 1
    super(options)
  end
end

class ImageDownloader::Worker < ActiveJob::Base
  include ActiveJobRetriesCount

  rescue_from ImageDownloader::TimeoutError do |exception|
    if exception.code == 0
      # just retry the download in 5 minutes
      # tolarate up to 5 failures
      retry_job wait: 5.minutes if retries_count > 5
    else
      fail exception
    end
  end

  def perform(url)
    ImageDownloader.download(url)
  end
end

Here is a simple test for the ActiveJobRetriesCount.

require 'spec_helper'

describe ActiveJobRetriesCount do
  class RetriesTestClass
  end

  class RetriesTestError < StandardError
  end

  class RetriesTestWorker < ActiveJob::Base
    include ActiveJobRetriesCount

    rescue_from RetriesTestError do
      retry_job wait: 5.minutes if retries_count < 5
    end

    def perform
      RetriesTestClass.do_something(retries_count)
    end
  end

  it 'handles retries counts', active_job: :inline do
    allow(RetriesTestClass).to receive(:do_something).and_raise RetriesTestError

    expect { RetriesTestWorker.perform_later }.not_to raise_error

    expect(RetriesTestClass).to have_received(:do_something).with(5)
    expect(RetriesTestClass).not_to have_received(:do_something).with(6)
  end
end

If you are not on Rails 5, you would need the following code:

if ActiveJob::Base.method_defined?(:deserialize)
  fail 'This no longer needed.'
else
  module ActiveJob
    class Base
      def self.deserialize(job_data)
        job = job_data['job_class'].constantize.new
        job.deserialize(job_data)
        job
      end

      def deserialize(job_data)
        self.job_id               = job_data['job_id']
        self.queue_name           = job_data['queue_name']
        self.serialized_arguments = job_data['arguments']
      end
    end
  end
end

For more advanced features – check out ActiveJob::Retry.

In the life of almost all Rails applications, comes the moment where custom routes are needed. Usually, the custom routes are just convenience methods like these:

def post_path(post)
  date_post_path post.date_slug, post.slug
end

def product_url
  date_post_url post.date_slug, post.slug
end

In this way, you decouple the route generation from your objects. Also, if you are doing some system route update and you want to keep the old routes around - this is the way.

Usually, I create a module CustomPaths and put those methods there. But in recent years, Rails.application.routes.url_helpers is showing up in more and more places like - background jobs, presenters, serializers and so. This complicates things.

At Product Hunt we needed some custom paths. So, me and Mike Coutermarsh created the following object:

# => routes.rb
module Routes
  # Simple `extend self` won't work here,
  # due to the way Rails implement `url_helpers`
  class << self
    include Rails.application.routes.url_helpers
    include Routes::CustomPaths
  end

  include Rails.application.routes.url_helpers
  include Routes::CustomPaths

  def default_url_options
    Rails.application.routes.default_url_options
  end
end

# => routes/custom_paths.rb
module Routes
  module CustomPaths
    # ... all your custom route methods
  end
end

It behaves the same way as Rails.application.routes.url_helpers plus the custom routes.

# in can be called directly
Routes.root_path
Routes.product_path(product)

# or included in another object
class ObjectWhoNeedsRoutes
  include Routes
end

ObjectWhoNeedsRoutes.new.root_path
ObjectWhoNeedsRoutes.new.product_path

I added Routes to my toolbox with install instructions and tests.

I see a lot of the following pattern in Rails projects:

class ProductsController < ApplicationController
  before_action :assign_post, only: %i(show edit)
  
  def index
    @posts = Post.paginate(params[:page])
  end
  
  def show
  end
  
  def edit
  end
  
  private
  
  def assign_post
    @post = Post.find(params[:id])
  end
end

Most people do this, because for them @post = Post.find(params[:id]) is duplication. Having assign_post is more DRY.

I don't buy the duplication argument. The definition for DRY is:

“Every piece of knowledge must have a single, unambiguous, authoritative representation within a system."

Unfortunately, most people confused it with - "I don't want to have the same sequence of characters more than once". David Chelimsky have an excellent talk on that subject.

But, my biggest issue with the approach is that it "hides" all variables passed to the view. Especially if there are only or except passed to before_action. Then you have to become an interpreter to figure out what gets into the view. I can recall several situations when during a code review I found code passing unwanted variables to a view.

I prefer to think the following, when I read a controller:

ok, show sends @post and @comments to the view

Instead of:

So, if show is called then assign_posts is called before it, which sets @posts, then show is not included in this other action filter, but is not excluded for this third one...

Also, it is easier for a developer to spot, that too many variables are passed to the view if all of them are listed together.

Because of that, I prefer to use the following pattern:

class ProductsController < ApplicationController
  def show
    @post = find_post
  end
  
  def edit
    @post = find_post
  end
  
  private
  
  def find_post
    Post.find(params[:id])
  end
end

In this way, the duplication is moved into finder methods. So if I have to add a scope like visible to Post.find, I just need to apply it in find_post.

My last blog post - Dealing with form objects, got me thinking about form objects. I also had a 12 hours flight to San Francisco, where I was meeting my teammates at Product Hunt.

During that flight, I went back and checked all of my custom form implementations. I gathered them together in a folder and started combining and extracting the common parts. By the end of the flight I almost had what now is MiniForm. (I had to change its name several times since I'm not very good with names and most of the decent names are not available).

MiniForm allows the following code:

 class RegistrationForm  
  include ActiveModel::Model

  attr_reader :user, :account

  attr_accessor :first_name, :last_name, :email, :name, :plan, :terms_of_service

  # user validation
  validates :first_name, presence: true
  validates :last_name, presence: true
  validates :email, presence: true, email: true

  # account validation
  validates :account_name, presence: true

  # form custom validation
  validates :plan, inclusion: {in AccountPlan::VALUES}
  validates :terms_of_service, acceptance: true

  # ensure uniqueness
  validate :ensure_unique_user_email
  validate :ensure_unique_account_name

  def initialize
    @user    = User.new
    @account = Account.new owner: @user
  end

  def update(attributes)
    attributes.each do |name, value|
      public_send "#{name}=", value
    end

    if valid? & user.update(user_attributes) && account.update(account_attributes)
      account.users << user
      AccountWasCreated.perform_later(account)
    else
      false
    end
  end

  private

  def ensure_unique_user_email
    errors.add :email, 'already taken' if User.where(email: email).any?
  end

  def ensure_unique_account_name
    errors.add :name, 'already taken' if Account.where(name: name).any?
  end

  def user_attributes
    {first_name: first_name, last_name: last_name, email: email}
  end

  def account_attributes
    {plan: plan, name: name}
  end
end 

To become:

class RegistrationForm  
  include MiniForm::Model

  # `model` delegates attributes to models 
  # and copies the validations from them
  model :user, attributes: %i(first_name last_name email), save: true
  model :account, attributes: %i(name plan), save: true

  attributes :terms_of_service

  validates :plan, inclusion: {in AccountPlan::VALUES}
  validates :terms_of_service, acceptance: true

  def initialize
    @user    = User.new
    @account = Account.new owner: @user
  end

  # `update` calls `perform` if model is valid
  # and models are saved
  def perform
    account.users << user
    AccountWasCreated.perform_later(account)
  end
end

Let's say - we have the following nice clean model for our new application:

class Label < ActiveRecord::Base
  belogns_to :user, required: true
  
  validates :name, presence: true, uniquness: true
end

Several months later, we have the requirement to add quote and description to Label and those attributes should be mandatory. So we update Label:

class Label < ActiveRecord::Base
  belogns_to :user, required: true

  validates :name, presence: true, uniquness: true

  validates :quote, :description, presence: true
 end

Now we have a big problem. All of our previous Label records are invalid. Because those new attributes didn't exist an hour ago. Also quote and description are not the kind of fields we add good default values.

So we revert this change and start thinking about a better way to handle the situation.

When a little more thought is put into this - we find that we need this validation to be applied in two places - my/labels/create and my/labels/update pages.

One pattern I have seen used for dealing with this is the following:

class Label < ActiveRecord::Base
  belogns_to :user, required: true

  validates :name, presence: true, uniquness: true

  validates :quote, presence: true, if: :validating_as_designer?
  validates :description, presence: true, if: :validating_as_designer?

  def update_as_designer(attributes = {})
    @validating_as_designer = true

    update_attributes(attributes).tap do
      @validating_as_designer = false
    end
  end

  private

  def validating_as_designer?
    @validating_as_designer
  end
end

In a newish model, this approach doesn't look so bad.

But this becomes unmaintainable easy. The main issue here is that we are adding form specific logic into a domain model. Now this model knows about certain pages. In my experience, such things tend to happen for the core modals of the application, which are bigger by nature.

Also, I have seen situations where a new developer enters the project, see that update_as_designer is used and decided that "this is the way they do stuff here" and adds update_as_admin.

So what is a better way to deal with the issue? I tend to favor the extraction of form objects:

class DesignerForm
  include ActiveModel::Model

  attr_accessor :label, :user, :name, :quote, :description

  validates :user, presence: true
  validates :name, presence: true
  validates :quote, presence: true
  validates :description, presence: true

  def initialize(label = Label.new)
    @label = label
  end

  def persisted?
    @label.persisted?
  end

  def update(attributes)
    attributes.each do |name, value|
      public_send "#{name}=", value
    end

    if valid?
      @label.update attributes
    else
      false
    end
  end
end

That sure looks too complicated! I can understand why people decide to use the "nice short method" instead of this big bulky object. But this is just our starting point.

Let's apply some minor modules; I use in almost every project I'm working on.

• ActiveModel::Attributes
• ActiveModel::Validations::ValidValidator

class DesignerForm
  include ActiveModel::Model
  include ActiveModel::Attributes

  attr_reader :label

  delegate :persisted?, to: label
  
  # ActiveModel::Attributes method:
  # share attributes between form object and label
  attributes :user, :name, :quote, :description, delegate: :label
  
  # ValidValidator:
  # runs label validations and copies the errors to the form
  validates :label, valid: true

  # this is form specific validations we need
  validates :quote, presence: true
  validates :description, presence: true

  def initialize(label = Label.new)
    @label = label
  end

  def update(attributes)
    # ActiveModel::Attributes method
    self.attributes = attributes

    if valid?
      @label.save!
      true
    else
      false
    end
  end
end

That is a lot better. Still not perfect. In my experience after having 2-3 form objects in the application - more and more common functionally is extracted. In the end, most of the form objects become something like following:

class DesignerForm
  include BaseForm
  
  model :label, attributes: %i(user name quote description) 

  validates :quote, presence: true
  validates :description, presence: true
end

I don't start with BaseForm because every project has slightly different requirements for handling forms.

p.s. As expected - there a several gems which provide nice apis for form objects. I don't use any of them.