Zetetic

When we started integrating simple social networking features into PingMe we wanted to easily represent a bi-directional relationship between users in the system. When a user signs up for PingMe they can invite another user to join them. Once an invite is accepted, the users become mutual friends, or contacts in PingMe parlance, and can send Pings to each other.

Most importantly, we wanted the relationship to be bidirectional - when Jack is a friend of Jane then Jane should also be a friend of Jack.

Unfortunately we quickly realized that this model was not going to be so easy. The usual way of representing this type of network relationship using ActiveRecord is with an intermediate HABTM join, or with a self-referential has_many :through association. For example one might define a simple person model and then a join table to store the friendship relation:

  create_table :people, :force => true do |t|
    t.column :name, :string
  end

  create_table :friends, {:id => false} do |t|
    t.column :person_id, :integer, :null => false
    t.column :person_id_friend, :integer, :null => false      # target of the relationship
  end

The problem is that this model requires two rows in the intermediate table to make a relationship bi-directional.

  jane = Person.create(:name => 'Jane')
  jack = Person.create(:name => 'Jack')
  
  jane.friends << jack              
  jane.friends.include?(jack)    =>  true   # Jack is Janes friend
  jack.friends.include?(jane)    =>  false  # Jane is NOT Jack's friend

In short, you must explicitly define the reverse relation in order for this to work.

  jack.friends << jane
  jack.friends.include?(jane)    =>  true  # now they're buds

This can be implemented in a fairly DRY way using association callbacks as documented in Rails Recipes, but things start to get ugly when you want to express the relationship through a "proper" join model (like for an Invite) using has_many :through.

  create_table :invites do |t|
    t.column :person_id, :integer, :null => false           # source of the relationship
    t.column :person_id_friend, :integer, :null => false    # target of the relationship
    t.column :code, :string                                 # random invitation code
    t.column :message, :text                                # invitation message
    t.column :is_accepted, :boolean
    t.column :accepted_at, :timestamp                       # when did they accept?
  end

Enter acts_as_network

acts_as_network is a plugin that we developed for PingMe to resolve some of these issues. It drives the social networking features of the site. It's intended to simplify the definition and storage of reciprocal relationships between entities using ActiveRecord by exposing a "network" of 2-way connections.

What makes it special is that it does this in a DRY way using only a single record in an intermediate has_and_belongs_to_many join table or has_many :through join model. There is no redundancy, and you need only one instance of an association or join model to represent both directions of the relationship. Consider this more desirable implementation:

  class Invite < ActiveRecord::Base
    belongs_to :person                    # the source of the invite
    belongs_to :person_target,            # the target of the invite
        :class_name => 'Person', 
        :foreign_key => 'person_id_target'       
  end

  class Person < ActiveRecord::Base
    acts_as_network :friends, :through => :invites, :conditions => ["is_accepted = ?", true]
  end

In this case acts_as_network implicitly defines five new properties on the Person model

  person.invites_out        # has_many invites originating from me to others
  person.invites_in         # has_many invites originating from others to me
  person.friends_out        # has_many friends :through outbound accepted invites from me to others
  person.friends_in         # has_many friends :through inbound accepted invites from others to me
  person.friends            # the union of the two friend sets - all people who I have
                            # invited all the people who have invited me and 

Now...

  # Jane invites Jack to be friends
  invite = Invite.create(:person => jane, :person_target => jack, :message => "let's be friends!")    
  
  jane.friends.include?(jack)    =>  false   # Jack is not yet Jane's friend
  jack.friends.include?(jane)    =>  false   # Jane is not yet Jack's friend either

  invite.is_accepted = true  # Now Jack accepts the invite
  invite.save and jane.reload and jack.reload

  jane.friends.include?(jack)    =>  true   # Jack is Janes friend now
  jack.friends.include?(jane)    =>  true   # Jane is also Jacks friend

So much cleaner!

Most of this magic is actually accomplished with a UnionCollection class that provides useful application-space functionality for emulating set unions across ActiveRecord collections. Once initialized, the UnionCollection itself will act as an array containing all of the records from each of its member sets, but its more interesting feature is that it will intelligently forward ActiveRecord method calls like find, find_all_by_*, etc. to its member sets.

Check it out

Further documentation is available online, and you can easily install acts_as_network as a plugin to try it out:

% script/plugin source http://actsasnetwork.rubyforge.org/svn/plugins
% script/plugin install acts_as_network  
% rake doc:plugins

Please check it out and let us know what you think.