Entangled
This project is not actively maintained at the moment.
Real time is important. Users have come to expect real time behavior from every website, because they want to see the latest data without having to reload the page. Real time increases their engagement, provides better context for the data they're seeing, and makes collaboration easier.
Entangled stores and syncs data from ActiveRecord instantly across every device. It is a layer behind your models and controllers that pushes updates to all connected clients in real time. It is cross-browser compatible and offers real time validations.
Currently, Entangled runs on Rails >= 4.0 and Ruby >= 2.0.0. In the front end, libraries are available in plain JavaScript and for Angular.
Installation
Add this line to your application's Gemfile:
gem 'entangled'
Note that Redis and Puma are required as well. Redis is needed to build the channels clients subscribe to, Puma is needed to handle websockets concurrently.
You need to install Redis if you haven't yet. Entangled comes with a Ruby client for Redis that will connect to your Redis instance once it's installed.
You also need to add Puma to your Gemfile:
gem 'puma'
And then execute:
$ bundle
Usage
Entangled is needed in three parts of your app: Routes, models, and controllers. Given the example of a MessagesController
and a Message
model for a chat app, you will need:
Routes
Add the following to your routes file:
sockets_for :messages
Under the hood, this creates the following routes:
Prefix Verb URI Pattern Controller#Action
messages GET /messages(.:format) messages#index
message GET /messages/:id(.:format) messages#show
create_messages GET /messages/create(.:format) messages#create
update_message GET /messages/:id/update(.:format) messages#update
destroy_message GET /messages/:id/destroy(.:format) messages#destroy
Note that websockets don't speak HTTP, so only GET requests are available. That's why these routes deviate slightly from restful routes. Also note that there are no edit
and new
actions, since an Entangled controller is only concerned with rendering data, not views.
You can use sockets_for
just like resources
, including the following features:
# Inclusion/exclusion
sockets_for :messages, only: :index
sockets_for :messages, only: [:index, :show]
sockets_for :messages, except: :index
sockets_for :messages, except: [:index, :show]
# Nesting
sockets_for :parents do
sockets_for :children
end
# Multiple routes at once
sockets_for :foos, :bars
# ...etc
Models
Add the following to the top of your model (e.g., a Message
model):
class Message < ActiveRecord::Base
include Entangled::Model
entangle
end
This will create the callbacks needed to push changes to data to all clients who are subscribed. This is essentially where the data binding is set up.
By default, the following callbacks will be added:
after_create
after_update
after_destroy
You can limit this behavior by specifying :only
or :except
options. For example, if you don't want to propagate the destruction or update of an object to all connected clients, you can do the following:
entangle only: :create
entangle only: [:create, :update]
Calling entangle
creates the following channels (sticking with the example of a Message
model):
# For the collection
"/messages"
# For a member, e.g. /messages/1
"/messages/:id"
:id
being the record's id, just as with routes.
Controllers
Your controllers will be a little more lightweight than in a standard restful Rails app. A restful-style controller is expected and should look like this:
class MessagesController < ApplicationController
include Entangled::Controller
def index
broadcast do
@messages = Message.all
end
end
def show
broadcast do
@message = Message.find(params[:id])
end
end
def create
broadcast do
@message = Message.create(message_params)
end
end
def update
broadcast do
@message = Message.find(params[:id])
@message.update(message_params)
end
end
def destroy
broadcast do
@message = Message.find(params[:id]).destroy
end
end
# def custom_action
# broadcast do
# # do whatever
# end
# end
private
def message_params
# params logic here
end
end
Note the following:
- All methods are wrapped in a new
broadcast
block needed to receive and send data to connected clients - The
index
action will expect an instance variable with the same name as your controller in the plural form (e.g.@messages
in aMessagesController
) - The
show
,create
,update
, anddestroy
actions will expect an instance variable with the singular name of your controller (e.g.@message
in aMessagesController
) - The instance variables are sent to clients as stringified JSON
- Strong parameters are expected
- The path to your controllers' index action has to match the model's channel for the collection, and the path to your controller's show action has to match the model's channel for a single member (which it will automatically if you stay RESTful)
- You can add custom actions on top of the five RESTful ones; JSON sent through sockets is available in the params hash
Server
Remember to run Redis whenever you run your server:
$ redis-server
Redis is needed to subscribe and publish to the channels that are created by Entangled internally to communicate over websockets.
If you store your Redis instance in $redis
or REDIS
(e.g. in an initializer), Entangled will use that assigned instance so that you can configure Redis just like you're used to. Otherwise, Entangled will instantiate Redis itself and use its default settings.
Associations
What if you want to only fetch and subscribe to children that belong to a specific parent? Or maybe you want to create a child in your front end and assign it to a specific parent?
Imagine the following Parent > Children relationship in your models:
class Parent < ActiveRecord::Base
include Entangled::Model
entangle
has_many :children
end
class Child < ActiveRecord::Base
include Entangled::Model
entangle
belongs_to :parent
end
Entangled takes note of every belongs_to
association and creates two additional channels for each belongs_to
association in the child model:
"/parents/:parent_id/children"
"/parents/:parent_id/children/:id"
So in total, the Child
model will have all of the following channels:
"/children"
"/children/:id"
"/parents/:parent_id/children"
"/parents/:parent_id/children/:id"
Channels are deeply nested for child/parent/grandparent etc associations. There is no limit. To get a list of all available channels on a record, you can call the method channels
on any entangled instance.
To reflect associations in your front end, you just need to add three things to your app:
- Nest your routes so that they resemble the parent/child relationship:
sockets_for :parents do
sockets_for :children
end
- Adjust the
index
andcreate
actions in yourChildrenController
so that they look like this:
class ChildrenController < ApplicationController
include Entangled::Controller
# Fetch children of specific parent
def index
broadcast do
@children = Child.where(parent_id: params[:parent_id])
end
end
# Create child of specific parent
def create
broadcast do
@child = Child.new(child_params)
@child.parent_id = params[:parent_id]
@child.save
end
end
# show, update and destroy don't need to be nested
end
Check out the JavaScript guides to implement associations on the client.
The Client
Pick if you want to use Entangled with plain JavaScript or with Angular:
The following versions are compatible:
entangled.gem | entangled-js.js | entangled-angular.js |
---|---|---|
1.5.0 | 1.4.0 | 1.4.0 |
1.4.1 | 1.3.1 | 1.3.1 |
1.4.1 | 1.3.0 | 1.3.0 |
A Note On Cases
The case conventions differ in Ruby and JavaScript. snake_case
is the standard in Ruby, whereas camelCase
is the standard in JavaScript.
To comply with both standards, Entangled automatically converts attribute names to camel case before sending them from the server to the client to comply with JS conventions, and back to snake case before sending them from the client back to the server to comply with Ruby conventions.
All this means for you is that this enables you to use the conventional case for both environments. For example, a sender_name
attribute on your model in Rails will turn into a senderName
attribute in the browser, and vice versa. It would be weird to write camel case in Ruby.
Planning Your Infrastructure
This gem is best used for Rails apps that serve as APIs only and are not concerned with rendering views, since Entangled controllers cannot render views. A front end separate from your Rails app is recommended, either in your Rails app's public directory, or a separate front end app altogether.
Limitations
The gem relies heavily on convention over configuration and currently only works with restful style controllers as shown above. More features will be available soon. See the list of development priorities below.
Debugging Websockets
To debug websockets from your terminal, you can use curl. For example, to do a handshake with a socket at /messages
(a route you need to have set up), you can do the following:
curl -i -N -H "Connection: Upgrade" -H "Upgrade: websocket" -H "Host: echo.websocket.org" -H "Origin: http://localhost:3000" http://localhost:3000/messages
More information here.
Development Priorities
The following features are to be implemented next:
- Support multiple
hasMany
andbelongsTo
associations in front end - Make prefix of create path
create_message
instead ofcreate_messages
- Support
has_one
associations in back end and front end and route helper for single resource - Support scoping in back end (see dchacke/entangled-angular#4)
- Add support for scopes and where clauses in front end once back end can do scopes à la Spyke
- Add ability to configure options, such as to specify which Redis instance to use, in initializer through a config block; see need and example here
- Display results of interactions to client immediately without going through the server; add server interactions to queue and constantly dequeue; if result from server conflicts with client state, update client accordingly
- Add offline capabilities, i.e. only dequeue server interactions once internet connection established
- Add authentication - with JWT?
- On Heroku, tasks are always in different order depending on which ones are checked off and not
- Add
$onChange
method to objects - Test controllers (see ngauthier/tubesock#41)
- Add
.destroyAll()
method - Support custom actions in front end (see dchacke/entangled-angular#1)
- Use only one socket for everything
Contributing
- Fork it - you will notice that the repo comes with a back end and a front end part to test both parts of the gem
- Run
$ bundle install
in the root of the repo - Run
$ bower install
and$ npm install
in spec/dummy/public - The back end example app resides in spec/dummy. You can run
rails
andrake
commands in there if you prefix them withbin/
, e.g.$ bin/rails s
or$ bin/rake db:schema:load
. Run your Rails tests in the root of the repo by running$ rspec
- The front end example app resides in spec/dummy/public. To look at it in your browser, cd into spec/dummy/public and run
$ bin/rails s
. Tests for this part of the app can be located under spec/dummy/public/test and are written with Jasmine. To run the tests, first run$ bin/rails -e test
to start up the server in test mode, and then run$ grunt test
in a new terminal tab. It's important to remember that changes you make to the server will not take effect until you restart the server since you're running it in the test environment. Also remember to prepare the test database by running$ bin/rake db:test:prepare
- The Entangled Angular service resides in spec/dummy/public/app/entangled/entangled.js. This is where you can make changes to the service. A copy of it, living in /entangled.js at the root of the repo, should be kept in sync for it to be available with Bower. Once you're done editing spec/dummy/public/app/entangled/entangled.js, copy it over to /entangled.js
- Write your tests. Test coverage is required
- Write your feature to make the tests pass
- Stage and commit your changes
- Push to a new feature branch in your repo
- Send me a pull request!
Credits
Thanks to Ilias Tsangaris for inspiring the name "Entanglement" based on Quantum Entanglement where pairs or groups of particles always react to changes as a whole, i.e. changes to one particle will result in immediate change of all particles in the group.