sync_bumper 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: eeb67b4ccf61e6b2c827757823f6c3409b204a0f
+  data.tar.gz: 1c00aeefec000c068ed4198c161fd84b9d1827a1
+SHA512:
+  metadata.gz: 4a38eb4c7caa2151750ef0f6de38f2dbe0afb392a5e3f97fea70d1d691ab8eb3f4a8029238818773b719f0997275a2964e881d6ab104e624942c174d8d76796d
+  data.tar.gz: 6bf29354269289a5ee3836aeeeddfde38eb11bd3296df2128a74fcd3f8b2231878302438dbd58f53633190cc7582e9da342940cf2880f6422128d9cacff271c5

data/CHANGELOG.md

@@ -0,0 +1,50 @@
+# Version 0.2.3 - June 30, 2013
+
+- Fixed Turbolinks issue where `page:restore` events no longer evaluate script tags in the body. The workaround re-evaluates all sync sript tags on page restore.
+
+# Version 0.2.1 - May 27, 2013
+
+ - Add ability to narrow scope to custom channel for sync_new publishes
+
+Example Usage:
+
+View:
+```erb
+<%= sync_new partial: 'todo_list_row', resource: Todo.new, scope: [@project, :staff] %>
+```
+
+Controller/Model:
+```ruby
+sync_new @todo, scope: [@project, :staff]
+```
+
+
+# Version 0.2.0 - May 26, 2013
+
+ - Add ability to refetch partial from server to render within session context, ref: https://github.com/chrismccord/sync/issues/44
+
+This solves the issues of syncing partials across different users when the partial requires the session's context (ie. current_user). 
+
+Ex:
+    View: Add `refetch: true` to sync calls, and place partial file in a 'refetch'
+    subdirectory in the model's sync view folder:
+
+The partial file would be located in `app/views/sync/todos/refetch/_list_row.html.erb`
+```erb
+<% @project.todos.ordered.each do |todo| %>
+  <%= sync partial: 'list_row', resource: todo, refetch: true %>
+<% end %>
+<%= sync_new partial: 'list_row', resource: Todo.new, scope: @project, refetch: true %>
+```
+
+*Notes*
+While this approach works very well for the cases it's needed, syncing without refetching should be used unless refetching is absolutely necessary for performance reasons. For example, 
+
+A sync update request is triggered on the server for a 'regular' sync'd partial with 100 listening clients:
+- number of http requests 1
+- number of renders 1, pushed out to all 100 clients via pubsub server.
+
+
+A sync update request is triggered on the server for a 'refetch' sync'd partial with 100 listening clients:
+- number of http requests 100
+- number of renders 100, rendering each request in clients session context.

data/Gemfile

@@ -0,0 +1,3 @@
+source "http://rubygems.org"
+
+gemspec

data/LICENSE

@@ -0,0 +1,22 @@
+Copyright (c) 2013 Chris McCord
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+The Software shall be used for Good, not Evil.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.md

@@ -0,0 +1,408 @@
+# Sync
+> This started as a thought experiment that is growing into a viable option for realtime Rails apps without ditching
+  the standard rails stack that we love and are so productive with for a heavy client side MVC framework.
+
+
+Real-time partials with Rails. Sync lets you render partials for models that, with minimal code,
+update in realtime in the browser when changes occur on the server.
+
+#### Watch a screencast to see it in action
+[![See it in action](http://chrismccord.com/images/sync/video_thumb.png)](http://chrismccord.com/blog/2013/04/21/sync-realtime-rails-partials/)
+
+In practice, one simply only needs to replace:
+
+```erb
+<%= render partial: 'user_row', locals: {user: @user} %>
+```
+
+with:
+
+```erb
+<%= sync partial: 'user_row', resource: @user %>
+```
+
+Then update views realtime automatically with the `sync` DSL or with a with a simple `sync_update(@user)` in the controller without any extra javascript or
+configuration.
+
+In addition to real-time updates, Sync also provides:
+
+  - Realtime removal of partials from the DOM when the sync'd model is destroyed in the controller via `sync_destroy(@user)`
+  - Realtime appending of newly created model's on scoped channels
+  - JavaScript/CoffeeScript hooks to override and extend element updates/appends/removes for partials
+  - Support for [Faye](http://faye.jcoglan.com/) and [Pusher](http://pusher.com)
+
+## Requirements
+
+  - Ruby >= 1.9.2
+  - Rails 3 >= 3.1 or Rails 4
+  - jQuery >= 1.9
+
+
+## Installation
+
+#### 1) Add the gem to your `Gemfile`
+
+#### Using Faye
+
+```ruby
+gem 'faye'
+gem 'thin', require: false
+gem 'sync'
+```
+
+#### Using Pusher
+
+```ruby
+gem 'pusher'
+gem 'sync'
+```
+
+#### Install
+
+```bash
+$ bundle
+$ rails g sync:install
+```
+
+#### 2) Require sync in your asset javascript manifest `app/assets/javascripts/application.js`:
+
+```javascript
+//= require sync
+```
+
+#### 3) Add the pubsub adapter's javascript to your application layout `app/views/layouts/application.html.erb`
+
+```erb
+<%= javascript_include_tag Sync.adapter_javascript_url %>
+```
+
+#### 4) Configure your pubsub server (Faye or Pusher)
+
+
+#### Using [Faye](http://faye.jcoglan.com/) (self hosted)
+
+Set your configuration in the generated `config/sync.yml` file, using the Faye adapter. Then run Faye alongside your app.
+
+```bash
+rackup sync.ru -E production
+```
+
+#### Using [Pusher](http://pusher.com) (SaaS)
+
+Set your configuration in the generated `config/sync.yml` file, using the Pusher adapter. No extra process/setup.
+
+## Current Caveats
+The current implementation uses a DOM range query (jQuery's `nextUntil`) to match your partial's "element" in 
+the DOM. The way this selector works requires your sync'd partial to be wrapped in a root level html tag for that partial file. 
+For example, this parent view/sync partial approach would *not* work:
+
+Given the sync partial `_todo_row.html.erb`:
+
+```erb
+Title:
+<%= link_to todo.title, todo %>
+```
+
+And the parent view:
+
+```erb
+<table>
+  <tbody>
+    <tr>
+      <%= sync partial: 'todo_row', resource: @todo %>
+    </tr>
+  </tbody>
+</table>
+```
+
+##### The markup *would need to change to*:
+
+
+sync partial `_todo_row.html.erb`:
+
+```erb
+<tr> <!-- root level container for the partial required here -->
+  Title:
+  <%= link_to todo.title, todo %>
+</tr>
+```
+
+And the parent view changed to:
+
+```erb
+<table>
+  <tbody>
+    <%= sync partial: 'todo_row', resource: @todo %>
+  </tbody>
+</table>
+```
+
+I'm currently investigating true DOM ranges via the [Range](https://developer.mozilla.org/en-US/docs/DOM/range) object.
+
+
+## 'Automatic' syncing through the sync DSL
+
+In addition to calling explicit sync actions within controller methods, a
+`sync` and `enable_sync` DSL has been added to ActionController::Base and ActiveRecord::Base to automate the syncing 
+approach in a controlled, threadsafe way.
+
+### Example Controller/Model
+```ruby
+  class TodosController < ApplicationController
+
+    enable_sync only: [:create, :update, :destroy]
+    ...
+  end
+
+  class Todo < ActiveRecord::Base
+
+    belongs_to :project, counter_cache: true
+    has_many :comments, dependent: :destroy
+
+    sync :all, scope: :project
+
+  end
+```
+
+### Syncing outside of the controller
+
+`Sync::Actions` can be included into any object wishing to perform sync
+publishes for a given resource. Instead of using the the controller as
+context for rendering, a Sync::Renderer instance is used. Since the Renderer
+is not part of the request/response/session, it has no knowledge of the
+current session (ie. current_user), so syncing from outside the controller
+context will require some care that the partial can be rendered within a
+sessionless context.
+
+### Example Syncing from a background worker or rails console
+```ruby
+ # Inside some script/worker
+  Sync::Model.enable do
+    Todo.first.update title: "This todo will be sync'd on save"
+  end
+  Todo.first.update title: "This todo will NOT be sync'd on save"
+
+  Sync::Model.enable!
+  Todo.first.update title: "This todo will be sync'd on save"
+  Todo.first.update title: "This todo will be sync'd on save"
+  Todo.first.update title: "This todo will be sync'd on save"
+  Sync::Model.disable!
+  Todo.first.update title: "This todo will NOT be sync'd on save"
+```
+  
+## Custom Sync Views and javascript hooks
+
+Sync allows you to hook into and override or extend all of the actions it performs when updating partials on the client side. When a sync partial is rendered, sync will instantiate a javascript View class based on the following order of lookup:
+
+ 1. The camelized version of the concatenated snake case resource
+    and partial names.
+ 2. The camelized version of the snake cased partial name.
+
+#### Examples
+
+partial name 'list_row', resource name 'todo', order of lookup:
+
+ 1. Sync.TodoListRow
+ 2. Sync.ListRow
+ 3. Sync.View (Default fallback)
+
+
+For example, if you wanted to fade in/out a row in a sync'd todo list instead of the Sync.View default of instant insert/remove:
+
+```coffeescript
+class Sync.TodoListRow extends Sync.View
+
+  beforeInsert: ($el) ->
+    $el.hide()
+    @insert($el)
+
+  afterInsert: -> @$el.fadeIn 'slow'
+
+  beforeRemove: -> @$el.fadeOut 'slow', => @remove()
+
+```
+
+## Narrowing sync_new scope
+
+Sometimes, you do not want your page to update with every new record. With the `scope` option, you can limit what is being updated on a given page.
+
+One way of using `scope` is by supplying a String or a Symbol. This is useful for example when you want to only show new records for a given locale:
+
+View:
+```erb
+<%= sync_new partial: 'todo_list_row', resource: Todo.new, scope: I18n.locale %>
+```
+
+Controller/Model:
+```ruby
+sync_new @todo, scope: @todo.locale
+```
+
+Another use of `scope` is with a parent resource. This way you can for example update a project page with new todos for this single project:
+
+View:
+```erb
+<%= sync_new partial: 'todo_list_row', resource: Todo.new, scope: @project %>
+```
+
+Controller/Model:
+```ruby
+sync_new @todo, scope: @project
+```
+
+Both approaches can be combined. Just supply an Array of Strings/Symbols and/or parent resources to the `scope` option. Note that the order of elements matters. Be sure to use the same order in your view and in your controller/model.
+
+## Refetching Partials
+
+Refetching allows syncing partials across different users when the partial requires the session's context (ie. current_user). 
+
+Ex:
+    View: Add `refetch: true` to sync calls, and place partial file in a 'refetch'
+    subdirectory in the model's sync view folder:
+
+The partial file would be located in `app/views/sync/todos/refetch/_list_row.html.erb`
+```erb
+<% @project.todos.ordered.each do |todo| %>
+  <%= sync partial: 'list_row', resource: todo, refetch: true %>
+<% end %>
+<%= sync_new partial: 'list_row', resource: Todo.new, scope: @project, refetch: true %>
+```
+
+*Notes*
+
+While this approach works very well for the cases it's needed, syncing without refetching should be used unless refetching is absolutely necessary for performance reasons. For example, 
+
+A sync update request is triggered on the server for a 'regular' sync'd partial with 100 listening clients:
+- number of http requests 1
+- number of renders 1, pushed out to all 100 clients via pubsub server.
+
+
+A sync update request is triggered on the server for a 'refetch' sync'd partial with 100 listening clients:
+- number of http requests 100
+- number of renders 100, rendering each request in clients session context.
+
+## Using with cache_digests (Russian doll caching)
+
+Sync has a custom `DependencyTracker::ERBTracker` that can handle `sync` render calls.
+Because the full partial name is not included, it has to guess the location of
+your partial based on the name of the `resource` or `collection` passed to it.
+See the tests to see how it works. If it doesn't work for you, you can always
+use the [explicit "Template Dependency"
+markers](https://github.com/rails/cache_digests).
+
+To enable, add to `config/initializers/cache_digests.rb`:
+
+#### Rails 4
+
+```ruby
+require 'action_view/dependency_tracker'
+
+ActionView::DependencyTracker.register_tracker :haml, Sync::ERBTracker
+ActionView::DependencyTracker.register_tracker :erb, Sync::ERBTracker
+```
+
+#### Rails 3 with [cache_digests](https://github.com/rails/cache_digests) gem
+
+```ruby
+require 'cache_digests/dependency_tracker'
+
+CacheDigests::DependencyTracker.register_tracker :haml, Sync::ERBTracker
+CacheDigests::DependencyTracker.register_tracker :erb, Sync::ERBTracker
+```
+
+**Note:** haml support is limited, but it seems to work in most cases.
+
+
+## Serving Faye over HTTPS (with Thin)
+
+Create a thin configuration file `config/sync_thin.yml` similar to the following:
+
+```yaml
+---
+port: 4443
+ssl: true
+ssl_key_file: /path/to/server.pem
+ssl_cert_file: /path/to/certificate_chain.pem
+environment: production
+rackup: sync.ru
+```
+
+The `certificate_chain.pem` file should contain your signed certificate, followed by intermediate certificates (if any) and the root certificate of the CA that signed the key.
+
+Next reconfigure the `server` and `adapter_javascript_url` in `config/sync.yml` to look like `https://your.hostname.com:4443/faye` and `https://your.hostname.com:4443/faye/faye.js` respectively.
+
+Finally start up Thin from the project root.
+
+```
+thin -C config/sync_thin.yml start
+```
+
+
+## Brief Example or [checkout an example application](https://github.com/chrismccord/sync_example)
+
+View `sync/users/_user_list_row.html.erb`
+
+```erb
+<tr>
+  <td><%= link_to user.name, user %></td>
+  <td><%= link_to 'Edit', edit_user_path(user) %></td>
+  <td><%= link_to 'Destroy', user, method: :delete, remote: true, data: { confirm: 'Are you sure?' } %></td>
+</tr>
+```
+
+View `users/index.html.erb`
+
+```erb
+<h1>Some Users</h1>
+<table>
+  <tbody>
+    <%= sync partial: 'user_list_row', collection: @users %>
+    <%= sync_new partial: 'user_list_row', resource: User.new, direction: :append %>
+  </tbody>
+</table>
+```
+
+
+Controller
+
+```ruby
+def UsersController < ApplicationController
+  …
+  def create
+    @user = User.new(user_params)
+    if @user.save
+      sync_new @user      
+    end
+    respond_to do |format|
+      format.html { redirect_to users_url }
+      format.json { head :no_content }
+    end
+  end
+
+  def update
+    @user = User.find(params[:id])
+    if user.save
+    …
+    end
+
+    # Sync updates to any partials listening for this user
+    sync_update @user
+
+    redirect_to users_path, notice: "Saved!"
+  end
+
+  def destroy
+    @user = User.find(params[:id])
+    @user.destroy
+
+    # Sync destroy, telling client to remove all dom elements containing this user
+    sync_destroy @user
+
+    respond_to do |format|
+      format.html { redirect_to users_url }
+      format.json { head :no_content }
+    end
+  end
+end
+```
+

data/lib/generators/sync/install_generator.rb

@@ -0,0 +1,13 @@
+module SyncBumper
+  module Generators
+    class InstallGenerator < Rails::Generators::Base
+      def self.source_root
+        File.dirname(__FILE__) + "/templates"
+      end
+
+      def copy_files
+        template "sync_bumper.rb", "config/initializers/sync_bumper.rb"
+      end
+    end
+  end
+end

data/lib/generators/sync/templates/sync_bumper.rb

@@ -0,0 +1,10 @@
+SyncBumper.configure do |c|
+  c.url = case
+    when Rails.env.production?
+      lambda { |id| "http://example.com/todos/#{id}/bumper" }
+    when Rails.env.development?
+      lambda { |id| "http://example.com/todos/#{id}/bumper" }
+    else
+      lambda { |id| "http://example.com/todos/#{id}/bumper" }
+    end
+end

data/lib/sync_bumper.rb

@@ -0,0 +1,24 @@
+
+require 'digest/sha1'
+require 'net/http'
+require 'net/https'
+
+require 'sync_bumper/model'
+
+module SyncBumper
+
+  class << self
+    attr_accessor :url
+
+    def configure(&blk); class_eval(&blk); end
+
+  end
+end
+
+
+if defined? Rails
+  # path = Rails.root.join("config/sync_bumper.yml")
+  # SyncBumper.load_config(path, Rails.env) if path.exist?
+
+  ActiveRecord::Base.send :extend, SyncBumper::Model::ClassMethods
+end

data/lib/sync_bumper/model.rb

@@ -0,0 +1,93 @@
+module SyncBumper
+  module Model
+
+    def self.enabled?
+      Thread.current["model_sync_enabled"]
+    end
+
+    def self.context
+      Thread.current["model_sync_context"]
+    end
+
+    def self.enable!(context = nil)
+      Thread.current["model_sync_enabled"] = true
+      Thread.current["model_sync_context"] = context
+    end
+
+    def self.disable!
+      Thread.current["model_sync_enabled"] = false
+      Thread.current["model_sync_context"] = nil
+    end
+
+    def self.enable(context = nil)
+      enable!(context)
+      yield
+    ensure
+      disable!
+    end
+
+    module ClassMethods
+      attr_accessor :sync_scope
+
+      def sync(*actions)
+        include ModelActions
+        if actions.last.is_a? Hash
+          @sync_scope = actions.last.fetch :scope
+        end
+        actions = [:create, :update, :destroy] if actions.include? :all
+        actions.flatten!
+
+        if actions.include? :create
+          after_create :publish_sync_create, :on => :create#, :if => lamda { Sync::Model.enabled? }
+        end
+        if actions.include? :update
+          after_update :publish_sync_update, :on => :update#, :if => lamda { Sync::Model.enabled? }
+        end
+        if actions.include? :destroy
+          after_destroy :publish_sync_destroy, :on => :destroy#, :if => lamda { Sync::Model.enabled? }
+        end
+      end
+    end
+
+    module ModelActions
+      def sync_scope
+        return nil unless self.class.sync_scope
+        send self.class.sync_scope
+      end
+
+      def publish_sync_create
+        Thread.new do
+          uri = URI(SyncBumper.url.call(id))
+          req = Net::HTTP::Post.new(uri.request_uri)
+
+          perform_request(req, uri)
+        end
+      end
+
+      def publish_sync_update
+        Thread.new do
+          uri = URI(SyncBumper.url.call(id))
+          req = Net::HTTP::Put.new(uri.request_uri)
+
+          perform_request(req, uri)
+        end
+      end
+
+      def publish_sync_destroy
+        Thread.new do
+          uri = URI(SyncBumper.url.call(id))
+          req = Net::HTTP::Delete.new(uri.request_uri)
+
+          perform_request(req, uri)
+        end
+      end
+
+      def perform_request(req, uri)
+        req["Content-Type"] = 'text/plain;charset=UTF-8'
+        req["Content-Length"] = '0'
+
+        res = Net::HTTP.start(uri.host, uri.port) { |http| http.request(req) }
+      end
+    end
+  end
+end

metadata

@@ -0,0 +1,80 @@
+--- !ruby/object:Gem::Specification
+name: sync_bumper
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Alexey Dubovskoy
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2014-03-06 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: em-http-request
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: rails
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: 2.3.18
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: 2.3.18
+description: Bumper to involve Sync callbacks at external Rails App. Sync turns your
+  Rails partials realtime with automatic updates through Faye
+email: dubovskoy.a@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- lib/generators/sync/install_generator.rb
+- lib/generators/sync/templates/sync_bumper.rb
+- lib/sync_bumper/model.rb
+- lib/sync_bumper.rb
+- CHANGELOG.md
+- Gemfile
+- LICENSE
+- Rakefile
+- README.md
+homepage: http://github.com/dubadub/sync_bumper
+licenses: []
+metadata: {}
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - '>='
+    - !ruby/object:Gem::Version
+      version: 1.3.4
+requirements: []
+rubyforge_project: 
+rubygems_version: 2.0.14
+signing_key: 
+specification_version: 4
+summary: Bumper to involve Sync callbacks at external Rails App
+test_files: []