hyper-mesh 0.4.0

data/docs/client_side_scoping.md

@@ -0,0 +1,103 @@
+## ActiveRecord Scope Enhancement
+
+When the client receives notification that a record has changed HyperMesh finds the set of currently rendered scopes that might be effected, and requests them to be updated from the server.  
+
+On the server scopes are a useful way to structure code.  **On the client** scopes are vital as they limit the amount of data loaded, viewed, and updated on the client.  Consider a factory floor management system that shows *job* state as work flows through the factory.  There may be millions of jobs that a production floor browser is authorized to view, but at any time there are probably only 50 being shown.  Using ActiveRecord scopes is the way synchromesh keeps the data requested by the browser limited to a reasonable amount.  
+
+To make scopes work efficiently on the client HyperMesh adds some features to the ActiveRecord `scope` and `default_scope` macros.  Note you must use the `scope` macro (and not class methods) for things to work with HyperMesh.
+
+The additional features are accessed via the `:joins`, `:client`, and `:select` options.
+
+The `:joins` option tells the synchromesh client which models are joined with the scope.  *You must add a `:joins` option if the scope has any data base join operations in it, otherwise if a joined model changes, synchromesh will not know to update the scope.*
+
+The `:client` option provides the client a way to update scopes without having to contact the server.  Unlike the `:joins` option this is an optimization and is not required for scopes to work.
+
+```ruby
+class Todo < ActiveRecord::Base
+
+  # Standard ActiveRecord form:
+  # the proc will be evaluated as normal on the server, and as needed updates
+  # will be requested from the clients
+
+  scope :active, -> () { where(completed: true) }
+
+  # In the simple form the scope will be reevaluated if the model that is
+  # being scoped changes, and if the scope is currently being used to render data.
+
+  # If the scope joins with other data you will need to specify this by
+  # passing a relationship or array of relationships to the `joins` option.
+
+  scope :with_recent_comments,
+        -> { joins(:comments).where('comment.created_at >= ?', Time.now-1.week) },
+        joins: ['comments'] # or joins: 'comments'
+
+  # Now with_recent_comments will be re-evaluated whenever a Todo record, or a Comment
+  # joined with a Todo change.
+
+  # Normally whenever synchromesh detects that a scope may be effected by a changed
+  # model, it will request the scope be re-evaluated on the server.  To offload this
+  # computation to the client provide a client side scope method:
+
+  scope :with_recent_comments,
+        -> { joins(:comments).where('comment.created_at >= ?', Time.now-1.week) },
+        joins: ['comments']
+        client: -> { comments.detect { |comment| comment.created_at >= Time.now-1.week }
+
+  # The client proc is executed on each candidate record, and if it returns true the record
+  # will be added to the scope.
+
+  # Instead of a client proc you can provide a select proc, which will receive the entire,
+  # collection which can then be filtered and sorted.
+
+  scope :sort_by_created_at,
+        -> { order('created_at DESC') }
+        select: -> { sort { |a, b| b.created_at <=> a.created_at }}
+
+  # To keep things tidy you can specify the server scope proc with the :server option
+
+  scope :completed,
+        server: -> { where(complete: true) }
+        client: -> { complete }
+
+  # The expressions in the joins array can be arbitrary sequences of relationships and
+  # scopes such as 'comments.author'.  
+
+  scope :with_managers_comments,
+        server: -> { ... }
+        joins: ['comments.author', 'owner']
+        client: -> { comments.detect { |comment| comment.author == owner.manager }}}
+
+  # You can also use the client, select, server, and joins option with the default_scope macro
+
+  default_scope server: -> { where(deleted: false).order('updated_at DESC') }
+                select: -> { select { |r| !r.deleted }.sort { |a, b| b <=> a } }
+
+  # NOTE: it is highly recommend to provide a client proc with default_scopes.  Otherwise
+  # every change is going to require a server interaction regardless of what other client procs
+  # you provide.
+
+end
+```
+
+#### How it works
+
+Consider this scope on the Todo model
+
+```ruby
+scope :with_managers_comments,
+      server: -> { joins(owner: :manager, comments: :author).where('managers_users.id = authors_comments.id').distinct },
+      client: -> { comments.detect { |comment| comment.author == owner.manager }}
+      joins: ['comments.author', 'owner']
+```
+
+The joins 'comments.author' relationship is inverted so that we have User 'has_many' Comments which 'belongs_to' Todos.
+
+Thus we now know that whenever a User or a Comment changes this may effect our with_managers_comments scope
+
+Likewise 'owner' becomes User 'has_many' Todos.
+
+Lets say that a user changes teams and now has a new manager.  This means according to the relationships that the
+User model will change (i.e. there will be a new manager_id in the User model) and thus all Todos belonging to that
+User are subject to evaluation.
+
+While the server side proc efficiently delivers all the objects in the scope, the client side proc just needs to incrementally update the scope.

data/docs/simple_poller_quickstart.md

@@ -0,0 +1,121 @@
+### Simple Poller Quickstart
+
+The easiest way to get started is to use the built-in simple polling transport.
+
+#### 1 Get yourself a rails app
+
+Either take an existing rails app, or create a new one the usual way.
+
+#### 2 Add ReactRb
+
+If you have not already installed the `hyper-react` and `reactive-record` gems, then do so now using the [reactrb-rails-generator](https://github.com/hyper-react/reactrb-rails-generator) gem.
+
+- add `gem 'reactrb-rails-generator'` to your gem file (in the development section)
+- run `bundle install`
+- run `bundle exec rails g hyper-react:install --all` (make sure to use the --all option)
+- run `bundle update`
+
+#### 3 Add the synchromesh gem
+
+- add `gem 'synchromesh', git: 'https://github.com/hyper-react/synchromesh', branch: 'authorization-policies'`
+- then `bundle install`  
+- and in `app/views/components.rb` add `require 'hyper-mesh'`  
+ immediately below`require 'reactive-record'`
+
+#### 4 Set the transport
+
+Once you have hyper-react installed then add this initializer:
+```ruby
+#config/initializers/synchromesh.rb
+HyperMesh.configuration do |config|
+  config.transport = :simple_poller
+end
+```
+
+#### 5 Make sure caching is enabled
+
+HyperMesh uses the rails cache to keep track of what connections are alive in a transport independent fashion.  Rails 5 by default will have caching off in development mode.
+
+Check in `config/development.rb` and make sure that `cache_store` is never being set to `:null_store`.  
+
+If you would like to be able to interact via
+the `rails console` you should set the store to be something like this:
+
+```ruby
+# config/development.rb
+Rails.application.configure do
+  config.cache_store = :file_store, './rails_cache_dir'
+end
+```
+
+#### 6 Define Your Policies
+
+To start just open everything up by adding a policies directory and defining a policy file like this:
+
+```ruby
+# app/policies/application_policy.rb
+class ApplicationPolicy
+  always_allow_connection
+  regulate_all_broadcasts { |policy| policy.send_all }
+  allow_change(to: :all, on: [:create, :update, :destroy]) { true }
+end
+```
+
+#### 8 Try It Out  
+
+If you don't already have a model to play with,  add one now:
+
+`bundle exec rails generate model Word text:string`
+
+`bundle exec rake db:migrate`
+
+Whatever model(s) you will plan to access on the client need to moved to the `app/models/public` directory.  This allows reactive-record to build a client side proxy for the models.  Models not moved will be completely invisible on the client side.
+
+If you don't already have a simple component to play with,  here is a simple one (make sure you add the Word model):
+
+```ruby
+# app/views/components/app.rb
+class App < React::Component::Base
+
+  def add_new_word
+    # for fun we will use setgetgo.com to get random words!
+    HTTP.get("http://randomword.setgetgo.com/get.php", dataType: :jsonp) do |response|
+      Word.new(text: response.json[:Word]).save
+    end
+  end
+
+  render(DIV) do
+    SPAN { "Count of Words: #{Word.count}" }
+    BUTTON { "add another" }.on(:click) { add_new_word }
+    UL do
+      Word.each { |word| LI { word.text } }
+    end
+  end
+end
+```
+
+Add a controller:
+
+```ruby
+#app/controllers/test_controller.rb
+class TestController < ApplicationController
+  def app
+    render_component
+  end
+end
+```
+
+Add the `test` route to your routes file:
+
+```ruby
+#app/config/routes.rb
+
+  get 'test', to: 'test#app'
+
+```
+
+Fire up rails with `bundle exec rails s` and open your app in a couple of browsers.  As data changes you should see them all updating together.
+
+You can also fire up a rails console, and then for example do a `Word.new(text: "Hello").save` and again see any browsers updating.
+
+If you want to go into more details with example check out [words-example](/docs/words-example.md)

data/docs/todo-example.md

@@ -0,0 +1,116 @@
+Lets look at part of a very simple Todo application with one model:
+
+```ruby
+# app/models/public/todo.rb  <- public models are accessible on the client
+class Todo < ActiveRecord::Base
+  scope :active ->() { where(completed: true) }
+  scope :complete ->() { where(completed: false) }
+end
+```
+
+To show our Todo's we might have a very simple app like this:
+
+```ruby
+# app/views/components/app.rb
+class App < React::Component::Base
+
+  define_state scope: :active        
+  define_state new_todo: Todo.new
+
+  def todos  # display our list of todos
+    ul do
+      Todo.send(state.scope).each do |todo|
+        li do
+          status(todo); todo.title.span; delete_button(todo)
+        end
+      end
+    end
+  end
+
+  def status(todo) # display / change the status
+    checkbox(type: :checkbox, checked: todo.completed)
+    .on(:click) do
+      todo.completed = !todo.completed
+      todo.save
+    end
+  end
+
+  def delete_button(todo) # delete a todo
+    button { "delete!" }.on(:click) { todo.destroy }
+  end
+
+  def save_new_todo  # save a new todo
+    state.new_todo.save
+    state.new_todo! Todo.new
+  end
+
+  def link(to) # display a link to a scope
+    button { to }.on(:click) { state.scope! to }
+  end
+
+  render do # render everything
+    div do
+      todos
+      input(value: state.new_todo.title)
+      .on(:change) { |e| state.new_todo.title = e.target.value }
+      .on(:key_down) { |e| save_new_todo if e.key_code == 13 }
+      div { link(:all); link(:active); link(:complete) }
+    end
+  end
+end
+```
+
+Finally we will need a controller:
+
+```ruby
+class HomeController < ApplicationController
+  def app
+    render_component
+  end
+end
+```
+
+Except for configuration that is our complete App.  When the page loads it will show all the todos currently in the database.  As the user changes the state of the Todos (or adds more) the changes will be persisted via the Todo model.
+
+In order to have the changes on one browser be synchronized across all browsers we have to set up some *policies* to define the desired behavior.  Here is a very simple policy without any protection:
+
+```ruby
+#app/policies/application_policy.rb
+class ApplicationPolicy
+  always_allow_connection  # any browser may connect
+  regulate_all_broadcasts &:send_all # send all changes from all models
+  allow_change(to: :all, on: [:create, :update, :destroy])
+end
+```
+
+That is it!
+
+Lets walk through what happens users interact with the system.
+
+When the page first renders (on the server) our `App` component executes (on the server) and renders the initial view.  This is no different from the normal rendering cycle of any rails view, the only difference is we are using `Ruby` as our templating language.
+
+Compare the lines:
+```ruby
+ul do
+  Todo.send(state.scope).each do |todo|
+    li do
+      status(todo); todo.title.span; delete_button(todo)
+    end
+  end
+end
+```
+to the equivilent html.erb file:
+```html
+<ul>
+  <% Todo.send(@scope).each do |todo| %>
+    <li>
+      ...
+    </li>
+  <% end %>
+</ul>
+```
+The only difference is your brain doesn't hurt from all the syntactic context switching.
+
+So the server builds a pile of html and dumps it the browser as normal, but once on the browser we have the exact same ruby code running their as well.  It will automatically add all of event handlers (`on(:click), on(:change)`, etc), and as the events occur the underlying react.js system will cause portions of our code to rerender.
+
+Also during the client load any connections allowed to the browser will be established so that changes in the server database made by other sources will get broadcast to us.

data/docs/words-example.md

@@ -0,0 +1,65 @@
+## Random Words example
+
+This is the example app used by the quick start guides, and if you want to dive deeper this is the place to be.
+
+If you have not already done so, follow any one of the quick start guides to set up the basic system.  Make sure to follow the steps in the last section and add a `Word` model, a `App` component, and a controller and route.
+
+### The initial component:
+
+Your initial component should look like this:
+
+```ruby
+# app/views/components/app.rb
+class App < React::Component::Base
+
+  def add_new_word
+    # for fun we will use setgetgo.com to get random words!
+    HTTP.get("http://randomword.setgetgo.com/get.php", dataType: :jsonp) do |response|
+      Word.new(text: response.json[:Word]).save
+    end
+  end
+
+  render(DIV) do
+    SPAN { "Count of Words: #{Word.count}" }
+    BUTTON { "add another" }.on(:click) { add_new_word }
+    UL do
+      Word.each { |word| LI { word.text } }
+    end
+  end
+end
+```
+
+Before going further lets understand exactly what is going on here.
+
+1) Our controller has a method named `app`, so by convention Reactrb will look for a
+component class named `App`, which it finds and *mounts* where ever the the *layout* yields to the view.  
+
+Take a second to look at your `application.html.erb` and find the `<%= yield %>`.  That is the normal rails way of
+indicating where the view requested by the controller (in the case our component) should be rendered.
+
+2) The component is rendered on the server like any other view.  The `render` callback defines exactly what to render.  
+
+
+```ruby
+# app/views/components/app.rb
+class App < React::Component::Base
+
+  def add_new_word
+    # for fun we will use setgetgo.com to get random words!
+    word = Word.new(text: '')
+    Word << word # force our local list to update before the save
+    HTTP.get("http://randomword.setgetgo.com/get.php", dataType: :jsonp) do |response|
+      word.text = response.json[:Word]
+      word.save
+    end
+  end
+
+  render(DIV) do
+    SPAN { "Count of Words: #{Word.count}" }
+    BUTTON { "add another" }.on(:click) { add_new_word }
+    UL do
+      Word.sort.each { |word| LI { word.text.empty? ? 'loading...' : word.text } }
+    end
+  end
+end
+```

data/examples/action-cable/.gitignore

@@ -0,0 +1,21 @@
+# See https://help.github.com/articles/ignoring-files for more about ignoring files.
+#
+# If you find yourself ignoring temporary files generated by your text editor
+# or operating system, you probably want to add a global ignore instead:
+#   git config --global core.excludesfile '~/.gitignore_global'
+
+# Ignore bundler config.
+/.bundle
+
+# Ignore the default SQLite database.
+/db/*.sqlite3
+/db/*.sqlite3-journal
+
+# Ignore all logfiles and tempfiles.
+/log/*
+/tmp/*
+!/log/.keep
+!/tmp/.keep
+
+# Ignore Byebug command history file.
+.byebug_history

data/examples/action-cable/Gemfile

@@ -0,0 +1,58 @@
+source 'https://rubygems.org'
+
+
+# Bundle edge Rails instead: gem 'rails', github: 'rails/rails'
+gem 'rails', '~> 5.0.0', '>= 5.0.0.1'
+# Use sqlite3 as the database for Active Record
+gem 'sqlite3'
+# Use Puma as the app server
+gem 'puma', '~> 3.0'
+# Use SCSS for stylesheets
+gem 'sass-rails', '~> 5.0'
+# Use Uglifier as compressor for JavaScript assets
+gem 'uglifier', '>= 1.3.0'
+# Use CoffeeScript for .coffee assets and views
+gem 'coffee-rails', '~> 4.2'
+# See https://github.com/rails/execjs#readme for more supported runtimes
+# gem 'therubyracer', platforms: :ruby
+
+# Use jquery as the JavaScript library
+gem 'jquery-rails'
+# Turbolinks makes navigating your web application faster. Read more: https://github.com/turbolinks/turbolinks
+gem 'turbolinks', '~> 5'
+# Build JSON APIs with ease. Read more: https://github.com/rails/jbuilder
+gem 'jbuilder', '~> 2.5'
+# Use Redis adapter to run Action Cable in production
+# gem 'redis', '~> 3.0'
+# Use ActiveModel has_secure_password
+# gem 'bcrypt', '~> 3.1.7'
+
+# Use Capistrano for deployment
+# gem 'capistrano-rails', group: :development
+
+group :development, :test do
+  # Call 'byebug' anywhere in the code to stop execution and get a debugger console
+  gem 'byebug', platform: :mri
+  gem 'reactrb-rails-generator'
+end
+
+group :development do
+  # Access an IRB console on exception pages or by using <%= console %> anywhere in the code.
+  gem 'web-console'
+  gem 'listen', '~> 3.0.5'
+  # Spring speeds up development by keeping your application running in the background. Read more: https://github.com/rails/spring
+  gem 'spring'
+  gem 'spring-watcher-listen', '~> 2.0.0'
+end
+
+# Windows does not include zoneinfo files, so bundle the tzinfo-data gem
+gem 'tzinfo-data', platforms: [:mingw, :mswin, :x64_mingw, :jruby]
+
+gem 'hyper-react'
+gem 'react-rails', '>= 1.3.0'
+gem 'opal-rails', '>= 0.8.1'
+gem 'therubyracer', platforms: :ruby
+gem 'react-router-rails', '~> 0.13.3'
+gem 'reactrb-router'
+gem 'reactive-record', '>= 0.8.0'
+gem 'synchromesh', path: '../..'