Pitfalls of Ruby interactors

Rico Sta. Cruz@rstacruz

The Ruby and Rails communities often use a gem (package) called interactor which aims to make logic encapsulated into self-contained pieces. After writing a few interactors myself, I came across a few problems that I thought I’d share.

Problem: No separation of inputs and outputs

Interactors are often used to wrap code that will receive an input, and return an output. It starts off like this:

Background image — For instance, registering a user involves taking in `email`, `name` and returning a `user`.

Working with contexts

The way interactors handle this is by using a context object that holds both inputs and outputs.

# <-- input:  context.email
# <-- input:  context.name
# <-- input:  context.is_admin (optional)
# --> output: context.user
# --> output: context.profile
module RegisterUser
  include Interactor

  def call
    create_user
    create_profile
    track_analytics
  end

  def create_user
    context.user = User.create(
      email: context.email,
      is_admin: context.is_admin || false
    )
  end

  def create_profile
    context.profile = Profile.create(
      user_id: context.user.id,
      name: context.name
    )
  end

  def track_analytics
    Analytics.track('NEW_USER', uid: context.user.id)
  end
end

RegisterUser.call(email: 'hi@example.com', name: 'John')
result.success? # => true
result.name     # => string
result.email    # => string
result.user     # => <User>

Note how result seems to hold both input and outputs.

Problem: organisers reuses the same context

Interactors provide an Organizer class which allows breaking apart interactors into smaller, reuseble interactors. However, doing so often means the concept of “inputs” and “outputs” are a bit blurred.

module RegisterUser
  include Interactor::Organizer
  organize(
    CreateUserRecord,
    CreateProfile,
    TrackAnalytics
  )
end

# <-- input:  context.email
# <-- input:  context.is_admin (optional)
# --> output: context.user
module CreateUserRecord
  include Interactor
  def call; ... end
end

# <-- input:  context.user
# <-- input:  context.email
# --> output: context.profile
module CreateProfile
  include Interactor
  def call; ... end
end

# <-- input:  context.user
module TrackAnalytics
  include Interactor
  def call; ... end
end

In this example, the RegisterUser class can be refactored into 3 sub-interactors. At this point, the inputs and outputs start to get difficult to make sense of.

Making sense of it

I’ve found that the more organisers are used, the more context becomes harder to manage. One way to keep track of this is making some graph that keeps track of these things.

|                     | email | is_admin | user | profile |
| ------------------- | ----- | -------- | ---- | ------- |
| RegisterUser        | in    | in (opt) | out  | out     |
| .. CreateUserRecord | in    |          | out  |         |
| .. CreateProfile    |       |          | in   | out     |
| .. TrackAnalytics   |       |          | out  |         |

These tables can get very difficult to manage very quickly.

Problem: interactors aren’t reuseable

Interactors are often touted for being useful for managing reuseable pieces of logic. Here’s one example of business logic that might be useful in many places.

module ValidateEmail
  include Interactor
  def call
    email = context.email

    unless EMAIL_REGEXP.match(email)
      context.fail! error: :invalid_format
    end

    if User.where(email: email).count != 0
      context.fail! error: :email_is_already_taken
    end
  end
end

This interactor takes in a context.email input, and throws an error if it's not valid.

Not easily reuseable

While this logic is nicely self-contained, it’s not easily reuseable in an organizer that might take in a different input shape.

module SendPageToFriend
  include Interactor::Organizer
  organize(
    ValidateEmail, # <-- ! not working as intended!
    DoSendPageToFriend
  )
end

SendPageToFriend(
  params: {
    email: 'hello@example.com',
    message: 'Have a look!'
  }
)

This interactor takes in context.params.email, not the context.email expected by ValidateEmail. In this case, ValidateEmail can't be re-used as-is.

Problem: nested interactors break error handling

Because Interactor Organisers enforce the use of the same context fields, it’s often better to call interactors directly from other interactors.

module NestedInteractor
  def call
    ValidateEmail.call!(email: context.params.email)

    # Question: will an error in the line above
    # prevent this next line from working?
    do_work_after_validation
  end
end

The intention here is to have call! stop the execution when an error is encountered. However, it doesn't work that way...

Errors are swallowed by default

Unfortunately, the code above wouldn’t work, because errors are swallowed by default even when using call!. The fix here is to intentionally rescue Interactor errors and re-raise them using context.fail!.

module NestedInteractor
  def call
    ValidateEmail.call!(email: context.params.email)

    do_work_after_validation

  rescue Interactor::Failure => e
    context.fail!(error: e.context.error)
  end
end

# Now errors can be propagated instead of being
# silently swallowed:
handle_errors do
  MyOtherInteractor.call!
end

The rescue block will be needed when using call! inside interactors. See the discussion on GitHub.

Problem: Interactor hasn’t been maintained

The last release of the interactor and interactor-rails gems are in 2019. There has been plans for a v4 release but those have been put on hold as of Dec 2021. There are still some open issues, such as with the use of nested interactors mentioned above.

Problem: type checking is difficult

Ruby 3.0 comes with static type checking. However, with context being shared as both input and output, type definitions can become ambiguous. Interactors don’t support static typing yet, but consider this hypothetical example below that shows how difficult it would be to add types.

# register_user.rbs (type definitions)

module RegisterUser
  def self.call(context: RegisterUserContext) -> void
end

class RegisterUserContext extends Interactor::Context
  email: string
  is_admin: boolean | nil
  user: User | nil
  profile: Profile | nil
end

In this example, the RegisterUserContext will be shared across all sub-interactors. Some devs might confuse why user is optional: is it because its an output, or because its an optional input?

Suggested solutions

Here are a few ideas I had on how to work around these limitations with interactors.

Avoid organisers

Organisers impose strict restrictions on how code is supposed to be structured, and I feel that the restrictions don’t necessarily make for better code. It’s not worth the extra effort in my opinion, and nested interactors are a more reasonable alternative.

Consider validating inputs

Gems like dry.rb allows writing runtime validation for types. Static compile-time type checking is most ideal in my opinion (eg, Ruby type signatures or Sorbet), but runtime validation is the closest alternative.

Catch nested interator errors, or avoid `fail!`

Many devs I talked to who uses interactors have written some code to fix the shortcomings of fail! errors being swallowed. This snippet might be good to extract into somewhere easy to reuse:

module MyInteractor
  include Interactor

  def handle_errors(&block)
    yield
  rescue Interactor::Failure => e
    context.fail!(error: e.context.error)
  end
end

This is a workaround to allow for fail! errors to propagate taken from this comment on GitHub.

Document inputs and outputs

Since it’s easy to get lost in what parts of a context is input or output, I found that it helps to document what each interactor’s inputs and outputs are.

# == Inputs
# [user_id] (string) The user ID
# [use_defaults] (boolean, optional)
#
# == Outputs
# [categories] (Category[])
module CreateUseCategories
  include Interactor

  def call; ... end
end

Use plain Ruby instead of interactors

Many scenarios involving interactors can be done using plain Ruby modules. Consider if the addition of a gem like interactor is worth it over writing service objects in a different way.