Refactoring to use-cases

A case study

Przemysław::Kowalczyk
a.k.a. szeryf

about me

the traditional way

MVC
considered harmful?

Rails made me do it

Jamis Buck, 2006

obese model,
not so skinny controller

there's more than Model, View & Controller

MVC makes use-cases difficult to read

use-case spread over many files

shotgun surgery

lack of cohesion

Single Responsibility Principle

class has exactly one reason to change

Robert C. Martin, Agile Software Development, Principles, Patterns, and Practices

`AR::Base` already has a responsibility

OOP makes use-cases difficult to read

Classes dictate methods of objects

A new hope

Data
Context
Interaction

Data

What the system is
Tends to be stable
Boring stuff, dumb data-structures
No use-case specific methods
Used in different contexts!

...which may lead to obesity (in traditional way)

Context

Performs use-cases
a.k.a. scenarios, algorithms, habits
Makes objects play roles
Provides environment

Interaction

What the system does
Tends to change rapidly
Interesting stuff!
Roles interacting with each other
Usually not an actual object

DCI in example

class Account
  attr_accessor :balance
end

class TransferMoneyContext
  def perform src_id, dst_id, amount
    src_act = AccountRepo.fetch(src_id)
    src_act.extend(TransferMoneySourceAccount)
    dst_act = AccountRepo.fetch(src_id)
    dst_act.extend(TransferMoneyDestinationAccount)
    
    src_act.transfer(amount, dst_act)
  end
end

class TransferMoneySourceAccount
  def transfer amount, dst_act
    if self.balance < amount
      raise InsufficientFunds.new
    else
      transaction do
        self.balance -= amount
        self.log("transfer out", Time.now, amount)
        dst_act.transfer_in(amount)
      end
    end
  end
end

Architecture
The Lost Years

by Uncle Bob Martin

http://www.youtube.com/watch?v=WpkDN78P884

use-cases are your application,
Rails isn't

Architecture according to Uncle Bob

Entity

Dumb data, application-independent business rules
Interactor

Application-specific business rules == use-cases
Delivery mechanism

Should be an implementation detail == a plugin
Persistence

Should be an implementation detail == a plugin

Architecture according to Uncle Bob

Isolated layers
Communicating through simple data structures
Views so simple there's no point in testing them
The database is a detail!

Good architecture allows to defer decisions

...maximizes number of decisions not made

It's Business Time by Jim Gay

Data model != Domain model

i.e. ActiveRecord::Base != models
separate what is stable and what changes

Presented at wroc_love.rb: http://www.youtube.com/watch?v=lhFSc0dWsto

Objects on Rails

Single Responsibility Principle
Dependency Injection in Ruby!
de-couple as much as possible
"lone wolf" anti-pattern
Post.find(id) vs. current_user.blog.posts.find(id)
Coolest anti-pattern name since "shotgun surgery"!
too much hassle with Exhibits

a must-read! => objectsonrails.com

A new hope

This will be mainstream in 5 years

(except Java)

examples

caveat emptor:
work in progress

before

role.rb

class Role < ActiveRecord::Base

  belongs_to :user
  belongs_to :project
  ROLES = %w{creator member supervisor applicant follower}

  validates :role_type, :inclusion => ROLES

  after_create :notify_applicable_user, :unless => :accepted?

  state_machine :initial => :pending do
    state :pending, :accepted, :applied

    after_transition any => :accepted, :do => :create_activity_item
    after_transition :applied => :accepted, :do => :accept_applicant

    event :accept do
      transition :pending => :accepted
      #create_notification
    end

    event :accept_application do
      transition :applied => :accepted
    end
  end

  def self.create_roles(users, project)
    users.each do |user|
      Role.create!(:user => user, :project => project, :role_type => 'member')
    end
  end

  def self.create_member(user, project)
    Role.create!(:user => user, :project => project, :role_type => 'member', :state => 'accepted')
  end

  def self.create_owner(user, project)
    Role.create!(:user => user, :project => project, :role_type => 'creator', :state => 'accepted')
    project.create_activity_item
  end

  def self.create_follower(project, user)
    Role.create!(:user => user, :project => project, :role_type => 'follower', :state => 'accepted')
  end

  def self.create_user_follower(following_user, user)
    following_user.own_projects.each do |project|
      create_follower(project, user)
    end
  end

  def change!(value)
    update_attribute(:role_type, value)
  end

  def accept_applicant
    self.role_type = "member"
    self.save
  end

  private

    def notify_applicable_user
      if state == "pending" # user has been invited to join
        notify_user
      elsif state == "applied" # user has applied to join
        notify_project_owner
      end

    end

    def notify_user
      path    = Rails.application.routes.url_helpers.accept_project_role_path(project, self)
      subject = "You have been invited to project called #{project.name}"
      body    = "<a href=\"#{path}\">Accept invitation here</a>"
      Message.create_notification!(subject, body, user)
    end

    def notify_project_owner
      path    = Rails.application.routes.url_helpers.accept_application_project_role_path(project, self)
      subject = "#{user.name} would like to join your project called #{project.name}"
      body    = "To Accept <a href=\"/users/#{user.id}\">#{(user.name)}'s</a> application, <a href=\"#{path}\">click here</a>"
      Message.create_notification!(subject, body, self.project.owner)
    end

    def create_activity_item
      aid = ActivityItem.gen_aid

      # User has joined Project
      ActivityItem.create_item(subject: self.user, item: self, second_subject: self.project, description: "NEW", activity_identifier: aid)

      # Project owner has welcomed new user
      ActivityItem.create_item(subject: self.project.owner, item: self, second_subject: self.user, description: "WELCOME", activity_identifier: aid)
    end
end

Single Responsibility Principle?

§1 Role is sending notifications!

after_create :notify_applicable_user, :unless => :accepted?

private
  def notify_applicable_user
    if state == "pending" # user has been invited to join
      notify_user
    elsif state == "applied" # user has applied to join
      notify_project_owner
    end
  end

§2 Role is producing HTML!

def notify_user
  path    = Rails.application.routes.url_helpers
              .accept_project_role_path(project, self)
  subject = "You have been invited to project called #{project.name}"
  body    = "<a href=\"#{path}\">Accept invitation here</a>"
  Message.create_notification!(subject, body, user)
end

def notify_project_owner
  path    = Rails.application.routes.url_helpers
              .accept_application_project_role_path(project, self)
  subject = "#{user.name} would like to join your project called #{project.name}"
  body    = "To Accept <a href=\"/users/#{user.id}\">#{(user.name)}'s</a>
                application, <a href=\"#{path}\">click here</a>"
  Message.create_notification!(subject, body, self.project.owner)
end

§3 Role has a state machine

state_machine :initial => :pending do
  state :pending, :accepted, :applied

  after_transition any => :accepted, :do => :create_activity_item
  after_transition :applied => :accepted, :do => :accept_applicant

  event :accept do
    transition :pending => :accepted
    #create_notification
  end

  event :accept_application do
    transition :applied => :accepted
  end
end

def accept_applicant
  self.role_type = "member"
  self.save
end

§4 Role creates activity items

def create_activity_item
  aid = ActivityItem.gen_aid

  # User has joined Project
  ActivityItem.create_item(subject: self.user, item: self, second_subject:
               self.project, description: "NEW", activity_identifier: aid)

  # Project owner has welcomed new user
  ActivityItem.create_item(subject: self.project.owner, item: self, second_subject:
               self.user, description: "WELCOME", activity_identifier: aid)
end

§5 Role creates roles

def self.create_roles(users, project)
  users.each do |user|
    Role.create!(:user => user, :project => project, :role_type => 'member')
  end
end

def self.create_member(user, project)
  Role.create!(:user => user, :project => project, :role_type => 'member',
               :state => 'accepted')
end

def self.create_owner(user, project)
  Role.create!(:user => user, :project => project, :role_type => 'creator',
               :state => 'accepted')
  project.create_activity_item
end

§6 Role has security holes

def self.create_follower(project, user)
  Role.create!(:user => user, :project => project, :role_type => 'follower',
               :state => 'accepted')
end

def self.create_user_follower(following_user, user)
  following_user.own_projects.each do |project|
    create_follower(project, user)
  end
end

§7 Role has backdoors

def change!(value)
  update_attribute(:role_type, value)
end

after

Project Membership Request

require 'dependency_injection.rb'
require 'uses_transaction.rb'

class ProjectMembershipRequest
  include UsesTransaction
  extend DependencyInjection

  inject_dependency :notification_source, %q{ Message.public_method(:create_request_notification!) }
  inject_dependency :rails_url_helper, %q{ Rails.application.routes.url_helpers }
  inject_dependency :colleagueships_source, %q{ Colleagueship.public_method(:make_pair) }

  def request project, user
    unless project.users.include?(user)
      in_transaction.call do
        colleagueships_source.call(user, project.owner)
        role = project.roles.create(user: user, state: Role::APPLIED, role_type: Role::APPLICANT)

        path = rails_url_helper.accept_application_project_role_path(project, role)
        subject = "#{user.name} would like to join your project called #{project.name}"
        body = "To Accept <a href=\"/users/#{user.id}\">#{(user.name)}'s</a> application, <a href=\"#{path}\">click here</a>"
        notification_source.call(subject, body, project.owner, role)
      end
    end
  end
end

Project Membership Acceptance

class ProjectMembershipAcceptance
  include UsesTransaction
  include CreatesActivityItems

  def accept role
    return :already_accepted unless role.state == Role::APPLIED || role.state == Role::PENDING
    return :colleagueship_not_accepted unless role.project.owner.colleagues.include?(role.user)
    return :project_archived if role.project.archived?
    in_transaction.call do
      role.project.chapters.create(name: "#{role.project.name.titleize}'s Lab Book", lab_book: role.user.lab_book)
      role.role_type = Role::MEMBER
      role.state = Role::ACCEPTED
      create_activity_item(role)
      role.save!
    end
  end

private
  def create_activity_item role
    # User has joined Project
    ai1 = activity_item_source.call(subject: role.user, item: role, second_subject: role.project, description: "NEW")
    # Project owner has welcomed new user
    activity_item_source.call(subject: role.project.owner, item: role, second_subject: role.user, description: "WELCOME", activity_identifier: ai1.activity_identifier)
  end
end

Plan Change

class PlanChange
  extend DependencyInjection
  include UsesTransaction

  inject_dependency :payments_proxy, %q{ PaymentsProxy.new }

  def change user, plan_type, token
    plan = user.plan
    return :same_plan if token.nil? && plan.plan_type == plan_type
    check_plan_limits(user, plan, plan_type)
    in_transaction.call do
      change_plan_for(user, plan, plan_type, token)
    end
  end

private
  def check_plan_limits user, plan, plan_type
    if user.own_projects.only_private.count > plan_type.closed_project_limit
      error "You own too many private projects for this plan."
    elsif user.max_collaborators_in_any_closed_project > plan_type.colaborators_limit
      error "The number of collaborators in at least one of your project exceeds this plan's limit."
    end
  end

  def change_plan_for user, plan, plan_type, token
    result = if plan.stripe_customer_token
      handle_existing_customer(plan, plan_type, token)
    else # no stripe_customer_token yet
      handle_new_customer(user, plan, plan_type, token)
    end
    plan.plan_type = plan_type
    plan.save!
    return result
  end

how to use?

Roles Controller

class RolesController < ApplicationController
  def create
    users_from_textboxlist = User.search_by_ids(params[:users_ids].split(/i*,i*/))
    ProjectMembershipInvitation.new.invite(project, users_from_textboxlist)
    redirect_to project, notice: 'Invitations have been sent.'
  end

  def accept
    case ProjectMembershipAcceptance.new.accept(role)
    when :already_accepted
      redirect_to project, alert: "You have already accepted this invitation"
    when :colleagueship_not_accepted
      redirect_to project, notice: "You have to accept colleague invitation first."
    when :project_archived
      redirect_to project, notice: "You cannot join to archived project."
    else
      redirect_to project, notice: "You have been added to project called #{project.name}"
    end
  end

Role

class Role < ActiveRecord::Base
  belongs_to :user
  belongs_to :project

  CREATOR    = 'creator'
  MEMBER     = 'member'
  SUPERVISOR = 'supervisor'
  APPLICANT  = 'applicant'
  validates :role_type, inclusion: [CREATOR, MEMBER, SUPERVISOR, APPLICANT]

  PENDING  = 'pending'
  APPLIED  = 'applied'
  ACCEPTED = 'accepted'
  validates :state, inclusion: [PENDING, APPLIED, ACCEPTED]

  scope :of_type,  ->(type)  { where(role_type: type) }
  scope :in_state, ->(state) { where(state: state) }
  scope :for,      ->(user)  { where(user_id: user) }

  def initialize *args
    super
    self.state ||= PENDING
  end

  def pending?
    state == PENDING
  end
end

helpers

Creates Activity Items

module CreatesActivityItems
  attr_writer :activity_item_source

private
  def activity_item_source
    @activity_item_source ||= ActivityItem.public_method(:create_item)
  end
end

Uses Transaction

module UsesTransaction
  attr_writer :in_transaction

private
  def in_transaction
    @in_transaction ||= Project.public_method(:transaction)
  end
end

Dependency Injection

module DependencyInjection
  def inject_dependency name, default
    class_eval %Q{
      attr_writer :#{name}
      def #{name}
        @#{name} ||= #{default}
      end
      private :#{name}
    }
  end
end

how to test?

Project Membership Acceptance Test

require_relative 'test_helper'
require_relative '../../app/use-cases/project_membership_acceptance.rb'

class ProjectMembershipAcceptanceTest < Test::Unit::TestCase

  def setup
    @lab_book = stub('lab_book')
    @user     = stub('user', lab_book: @lab_book)
    @owner    = stub('owner', colleagues: [@user])
    @project  = stub('project', owner: @owner, name: stub(titleize: "Test"), chapters: stub())
    @role     = stub('role', state: Role::PENDING, project: @project, user: @user, save!: true, accept!: true)

    @activity_item = stub('activity_item', activity_identifier: '123456')
    @activity_item_source = stub('activity_item_source', call: @activity_item)

    @pma = ProjectMembershipAcceptance.new
    @pma.in_transaction = ->(&blk){ @done_in_transaction = true; blk.call }
    @pma.activity_item_source = @activity_item_source
  end

  def test_should_accept
    @role.expects(:state=).with(Role::ACCEPTED)
    @role.expects(:save!).returns(true)
    assert_equal true, @pma.accept(@role)
    assert @done_in_transaction, "should be done in transaction"
  end

  def test_should_not_accept_unless_pending
    @role.expects(:state).returns(Role::ACCEPTED).twice
    @role.expects(:save!).never
    assert_equal :already_accepted, @pma.accept(@role)
  end

  def test_should_require_collegueship_to_be_accepted_first
    @role.project.owner.colleagues.expects(:include?).with(@user).returns false
    @role.expects(:save!).never
    assert_equal :colleagueship_not_accepted, @pma.accept(@role)
  end

  def test_should_create_lab_book_chapter
    @project.chapters.expects(:create).with(name: "Test's Lab Book", lab_book: @lab_book)
    assert_equal true, @pma.accept(@role)
  end

  def test_should_create_activity_items
    @activity_item_source.expects(:call).with(subject: @user, item: @role, second_subject: @project, description: "NEW").returns(@activity_item)
    @activity_item_source.expects(:call).with(subject: @owner, item: @role, second_subject: @user, description: 'WELCOME', activity_identifier: '123456')
    assert_equal true, @pma.accept(@role)
  end

end

Test Helper

require 'test/unit'
require 'mocha'

unless defined? Role
  class Role
    APPLICANT = 'applicant'
    MEMBER = 'member'
    CREATOR = 'creator'
    PENDING = 'pending'
    APPLIED = 'applied'
    ACCEPTED = 'accepted'
  end
end

class NilClass
  def blank?
    true
  end
end

Y U NO `rake test`?

`lib/tasks/tests.rake`

namespace :test do
  Rake::TestTask.new(:usecases) do |t|
    t.libs << 'test'
    t.verbose = true
    t.pattern = 'test/use-cases/**/*_test.rb'
  end
end
Rake::Task['test:usecases'].comment = "Runs use cases tests"

task "test" => ["test:usecases"]

Y U NO `autotest`?

`~/.autotest`

Autotest.add_hook :initialize do |at|
  at.add_mapping %r[^app/use-cases/(.*)\.rb$] do |_, m|
    at.files_matching %r%^test/use-cases/#{File.basename(m[1])}_test\.rb$%
  end
  at.add_mapping %r[^test/use-cases/.*.rb$] do |f, _|
    f
  end
end

pros

use-cases easy to follow

easier to modify

easier to reason about

dependencies under control

crazy fast tests

units

$ time rake test:units
# Running tests:

..................................................................................................................................................................

Finished tests in 33.363820s, 4.8855 tests/s, 8.5422 assertions/s.

163 tests, 285 assertions, 0 failures, 0 errors

real  0m51.735s
user  0m43.616s
sys   0m2.795s

units

$ time rake test:units
# Running tests:

..................................................................................................................................................................

Finished tests in 33.363820s, 4.8855 tests/s, 8.5422 assertions/s.

163 tests, 285 assertions, 0 failures, 0 errors

real  0m51.735s
user  0m43.616s
sys   0m2.795s

use cases

$ time rake test:usecases
# Running tests:

................................................

Finished tests in 0.081814s, 586.6967 tests/s, 1821.2042 assertions/s.

48 tests, 149 assertions, 0 failures, 0 errors, 0 skips

real  0m6.375s
user  0m5.115s
sys   0m1.175s

use cases

$ time rake test:usecases
# Running tests:

................................................

Finished tests in 0.081814s, 586.6967 tests/s, 1821.2042 assertions/s.

48 tests, 149 assertions, 0 failures, 0 errors, 0 skips

real  0m6.375s
user  0m5.115s
sys   0m1.175s

Refactoring to use-cases

A case study

Przemysław::Kowalczyk a.k.a. szeryf

about me

Table of contents

The traditional way

The new way

Case-study

the traditional way

MVC considered harmful?

Rails made me do it

obese model, not so skinny controller

there's more than Model, View & Controller

MVC makes use-cases difficult to read

use-case spread over many files

shotgun surgery

lack of cohesion

Single Responsibility Principle

class has exactly one reason to change

AR::Base already has a responsibility

OOP makes use-cases difficult to read

Classes dictate methods of objects

A new hope

DataContextInteraction

Data

What the system is

Tends to be stable

Boring stuff, dumb data-structures

No use-case specific methods

Used in different contexts!

Context

Performs use-cases

Makes objects play roles

Provides environment

Interaction

What the system does

Tends to change rapidly

Interesting stuff!

Roles interacting with each other

Usually not an actual object

DCI in example

ArchitectureThe Lost Years

by Uncle Bob Martin

use-cases are your application,Rails isn't

Architecture according to Uncle Bob

Entity

Interactor

Delivery mechanism

Persistence

Architecture according to Uncle Bob

Isolated layers

Communicating through simple data structures

Views so simple there's no point in testing them

The database is a detail!

Good architecture allows to defer decisions

...maximizes number of decisions not made

It's Business Time by Jim Gay

Data model != Domain model

i.e. ActiveRecord::Base != models

separate what is stable and what changes

Objects on Rails

Single Responsibility Principle

Dependency Injection in Ruby!

de-couple as much as possible

"lone wolf" anti-pattern

Coolest anti-pattern name since "shotgun surgery"!

too much hassle with Exhibits

A new hope

This will be mainstream in 5 years

(except Java)

examples

caveat emptor: work in progress

before

role.rb

Single Responsibility Principle?

§1 Role is sending notifications!

§2 Role is producing HTML!

§3 Role has a state machine

§4 Role creates activity items

§5 Role creates roles

Przemysław::Kowalczyk
a.k.a. szeryf

MVC
considered harmful?

obese model,
not so skinny controller

`AR::Base` already has a responsibility

Data
Context
Interaction

Architecture
The Lost Years

use-cases are your application,
Rails isn't

caveat emptor:
work in progress

Y U NO `rake test`?

`lib/tasks/tests.rake`

Y U NO `autotest`?

`~/.autotest`