hyper-mesh 0.4.0 → 0.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: e0d8993f6335ea2a758fc5f9c04765659e5ea02a
-  data.tar.gz: 57749d3dd923e09ce67aa9bffe10ea5dc1009dd6
+  metadata.gz: ed2a9b3886af2207f09a5e8ce3db7cb0383c2617
+  data.tar.gz: 3aacee91de89e22c2279324f4fc4e8ae91eb658d
 SHA512:
-  metadata.gz: 368fde4b81e66211bc22f42df68d06e9349187c8720f108bfec40758ddc7d8d0584fe6a76895a09aa095148fdd1362f1bd9fd7084c92f127eea9fa5937256533
-  data.tar.gz: aa7b20249a6ad4e8947e0870d15ab46ef842d571ced932c7517ff8193bb03c96a5138a1cab121f1d3960e9c3008a266414cd05d057293f137b26c8b1ee93c8b8
+  metadata.gz: 029224667501009cc0e60988b14bbdfda286fa2f06ebf2f0d4ff78a07035925054724481dc538e0028b0a5952343f77f124ef463af3ad590d60bdab776bc621c
+  data.tar.gz: 2997bb5b724ded7d1ebbef695385161d49a75c52e86b9a1803e11e2c7dd04dcb4fad07fef5c94c0e0cbe6d09b83d020df3d942571d073f596aaa80abeb648e2c

data/README.md

@@ -1,38 +1,25 @@
 #  ![](https://avatars3.githubusercontent.com/u/15810526?v=3&s=40&raw=true)HyperMesh
 
-HyperMesh gives your HyperReact components CRUD access to your ActiveRecord models on the client, using the the standard ActiveRecord API.
-Furthermore HyperMesh implements push notifications (via a number of possible
+
+[![Join the chat at https://gitter.im/reactrb/chat](https://badges.gitter.im/Join%20Chat.svg)](https://gitter.im/reactrb/chat?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge&utm_content=badge)
+[![Gem Version](https://badge.fury.io/rb/hyper-mesh.svg)](https://badge.fury.io/rb/hyper-mesh)
+
+HyperMesh gives your HyperReact components CRUD access to your server side ActiveRecord models, using the the standard ActiveRecord API.
+In addition HyperMesh implements push notifications (via a number of possible
 technologies) so changes to records on the server are dynamically pushed to all authorised clients.
 
 *Its Isomorphic Ruby in action.*
 
-In other words browser 1 creates, updates, or destroys a model, and the changes are persisted in
+In other words one browser creates, updates, or destroys a model, and the changes are persisted in
 active record models and then broadcast to all other authorised clients.
 
-## Quick Start Guides
-
-Use one of the following guides if you are in a hurry to get going.
-
-If you don't care about synchronizing clients (i.e you just want a simple single client CRUD type application) use this
-[guide.](docs/no_synchronization_quickstart.md)
-
-Otherwise you will need to choose a data push transport.  The following guides add the additional configuration
-information needed to get two way push communications back to the clients.
-
-The easiest way to setup client push is to use the Pusher-Fake gem.  Get started with this [guide.](docs/pusher_faker_quickstart.md)
-
-If you are already using Pusher follow this [guide.](docs/pusher_quickstart.md)
-
-If you are on Rails 5 already, and want to try ActionCable use this [guide.](docs/action_cable_quickstart.md)
-
-All of the above use websockets.  For ultimate simplicity use Polling as explained [here.](docs/simple_poller_quickstart.md)
-
 ## Overview
 
 + HyperMesh is built on top of HyperReact.
 + HyperReact is a Ruby DSL (Domain Specific Language) to build [React.js](https://facebook.github.io/react/) UI components in Ruby.  As data changes on the client (either from user interactions or external events) HyperReact re-draws whatever parts of the display is needed.
-+ HyperMesh provides a [flux dispatcher and data store](https://facebook.github.io/flux/docs/overview.html) backed by [Rails Active Record models](http://guides.rubyonrails.org/active_record_basics.html). You access your model data in your HyperReact components just like you would on the server or in an ERB or HAML view file.
-+ If a push transport is connected HyperMesh broadcasts any changes to your ActiveRecord models as they are persisted on the server.
++ HyperMesh provides a [flux dispatcher and data store](https://facebook.github.io/flux/docs/overview.html) backed by [Rails Active Record models](http://guides.rubyonrails.org/active_record_basics.html).  
+You access your model data in your HyperReact components just like you would on the server or in an ERB or HAML view file.
++ If an optional push transport is connected HyperMesh broadcasts any changes made to your ActiveRecord models as they are persisted on the server.
 
 For example consider a simple model called `Dictionary` which might be part of Wiktionary type app.
 
@@ -55,22 +42,18 @@ class WordOfTheDay < React::Component::Base
 
   def pick_entry!  
     # pick a random word and assign the selected record to entry
-
     @entry = Dictionary.defined.all[rand(Dictionary.defined.count)]
     force_update! # redraw our component when the word changes
-
     # Notice that we use standard ActiveRecord constructs to select our
     # random entry value
   end
 
-  # before we mount (draw the first time) our component pick an entry...
-
+  # pick an initial entry before we mount our component...
   before_mount :pick_entry
 
   # Again in our render block we use the standard ActiveRecord API, such
-  # as the 'defined' scope, and the 'word', 'pronunciation', & 'definition'
-  # attribute getters.  
-
+  # as the 'defined' scope, and the 'word', 'pronunciation', and
+  # 'definition' attribute getters.  
   render(DIV) do
     DIV { "total definitions: #{Dictionary.defined.count}" }
     DIV do
@@ -82,197 +65,66 @@ class WordOfTheDay < React::Component::Base
   end
 ```    
 
+## Basic Installation and Setup
 
+The easiest way to install is to use the `hyper-rails` gem.
 
-A minimal HyperMesh configuration consists of a simple initializer file, and at least one *Policy* class that will *authorize* who gets to see what.
-
-The initializer file specifies what transport will be used.  Currently you can use [Pusher](http://pusher.com), ActionCable (if using Rails 5), Pusher-Fake (for development) or a Simple Poller for testing etc.
-
-HyperMesh also adds some features to the `ActiveRecord` `scope` method to manage scopes updates.  Details [here.](docs/client_side_scoping.md)  
-
-## Authorization
-
-Each application defines a number of *channels* and *authorization policies* for those channels and the data sent over the channels.
-
-Policies are defined with *Policy* classes.  These are similar and compatible with [Pundit](https://github.com/elabs/pundit) but
-you do not need to use the pundit gem (but can if you want.)
-
-Examples:
-
-```ruby
-class ApplicationPolicy
-  # define policies for the Application
-
-  # all clients can connect to the Application
-  always_allow_connection
-end
-
-class ProductionCenterPolicy
-  # define policies for the ProductionCenter model
-
-  # any time a ProductionCenter model is updated
-  # broadcast the total_jobs_shipped attribute over the
-  # application channel (i.e. this is public data anybody can see)
-  regulate_broadcast do |policy|
-    policy.send_only(:total_jobs_shipped).to(Application)
-  end
-end
-
-class UserPolicy
-  # define policies for the User channel and Model
+1. Add `gem 'hyper-rails'` to your Rails `Gemfile` development section.
+2. Install the Gem: `bundle install`
+3. Run the generator: `bundle exec rails g hyperloop:install --hyper-mesh` (or use `--all` to install all hyperloop gems)
+4. Update the bundle: `bundle update`
 
-  # connect a channel for each logged in user
-  regulate_instance_connection { self }
-
-  # users can see all but one field of their own data
-  regulate_broadcast do |policy|
-    policy.send_all_but(:gross_margin_contribution).to(self)
-  end
-end
-```
+You will find a `public` folder has been added to the `app/models` folder.  To access a model on the client, move it into the public directory.  If you are on Rails 5, you will also need to move the `application_record.rb` into the public directory.
 
-For complete details see [Authorization Policies](docs/authorization-policies.md)
+You will also find an `app/policies` folder with a simple access policy suited for development.  Policies are how you will provide detailed access control to to your public models.  More details [here](/docs/authorization-policies.md).
 
-## Installation
+Once you have run the hyperloop installer you can move models to the `app/models/public` directory and they will be accessible on both the server and client.
 
-If you do not already have hyper-react installed, then use the reactrb-rails-generator gem to setup hyper-react, reactive-record and associated gems.
+## Setting up the Push Transport
 
-Then add this line to your application's Gemfile:
+To have changes to your models on the server  broadcast to authorized clients, add a HyperMesh initializer file and specify a transport.  For example to setup a simple polled transport add this file:
 
 ```ruby
-gem 'HyperMesh'
-```
-
-And then execute:
-
-    $ bundle install
-
-Also you must `require 'hyper-tracemesh'` from your client side code.  The easiest way is to
-find the `require 'reactive-record'` line (typically in `components.rb`) and replace it with
- `require 'HyperMesh'`.  
-
-## Configuration
-
-Add an initializer like this:
-
-```ruby
-# for rails this would go in: config/initializers/HyperMesh.rb
-HyperMesh.configuration do |config|
-  config.transport = :simple_poller # or :none, action_cable, :pusher - see below)
-end
-# for a minimal setup you will need to define at least one channel, which you can do
-# in the same file as your initializer.
-# Normally you would put these policies in the app/policies/ directory
-class ApplicationPolicy
-  # allow all clients to connect to the Application channel
-  regulate_connection { true } # or always_allow_connection for short
-  # broadcast all model changes over the Application channel *DANGEROUS*
-  regulate_all_broadcasts { |policy| policy.send_all }
+# config/initializers/hyper_mesh.rb
+HyperMesh.configuration |config|
+  config.transport = :simple_poller
 end
 ```
 
-### Action Cable Configuration
+After restarting, and reloading your browsers you will see changes broadcast to the clients.  You can also play with this by firing up a rails console, and creating, changing or destroying models at the console.
 
-If you are on Rails 5 you can use ActionCable out of the box.
-
-```ruby
-#config/initializers/HyperMesh.rb
-HyperMesh.configuration do |config|
-  config.transport = :action_cable
-end
-```
+For setting up the other possible transports following one of these guides:
 
-If you have not yet setup action cable all you have to do is include the `action_cable` js file in your assets
+The easiest way to setup a true push transport is to use the Pusher-Fake gem.  Get started with this [guide.](docs/pusher_faker_quickstart.md)
 
-```javascript
-//application.js
-...
-//= require action_cable
-...
-```
+or if you are already using Pusher follow this [guide.](docs/pusher_quickstart.md)
 
-The rest of the setup will be handled by HyperMesh.
+or if you are on Rails 5, and want to use ActionCable follow this [guide.](docs/action_cable_quickstart.md)
 
-HyperMesh will not interfere with any ActionCable connections and channels you may have already defined.  
+## Basic Configuration
 
-### Pusher Configuration
+For complete details on configuration settings go [here](/docs/configuration_details.md)
 
-Add `gem 'pusher'` to your gem file, and add `//= require 'HyperMesh/pusher'` to your application.js file.
+## ActiveRecord API
 
-```ruby
-# typically config/initializers/HyperMesh.rb
-HyperMesh.configuration do |config|
-  config.transport = :pusher
-  config.opts = {
-    app_id: '2xxxx2',
-    key:    'dxxxxxxxxxxxxxxxxxx9',
-    secret: '2xxxxxxxxxxxxxxxxxx2',
-    encrypted: false # optional defaults to true
-  }
-  config.channel_prefix = 'syncromesh' # or any other string you want
-end
-```
+HyperMesh uses a large subset of the ActiveRecord API modified only when necessary to accommodate the asynchronous nature of the client.
 
-### Pusher-Fake
+See this [guide](/docs/activerecord_api.md) for details.
 
-You can also use the [Pusher-Fake](https://github.com/tristandunn/pusher-fake) gem while in development.  Setup is a little tricky.  First
-add `gem 'pusher-fake'` to the development and/or test section of your gem file. Then setup your config file:
+**Warning** currently the `attributes` method is supported, but please do not use it as some details of the semantics will be changing in an upcoming release.  Instead of `foo.attributes[:xyz]` use `foo.send('xyz')` for now.
 
-```ruby
-# typically config/initializers/HyperMesh.rb
-# or you can do a similar setup in your tests (see this gem's specs)
-require 'pusher'
-require 'pusher-fake'
-# The app_id, key, and secret need to be assigned directly to Pusher
-# so PusherFake will work.
-Pusher.app_id = "MY_TEST_ID"      # you use the real or fake values
-Pusher.key =    "MY_TEST_KEY"
-Pusher.secret = "MY_TEST_SECRET"
-# The next line actually starts the pusher-fake server (see the Pusher-Fake readme for details.)
-require 'pusher-fake/support/base' # if using pusher with rspec change this to pusher-fake/support/rspec
-# now copy over the credentials, and merge with PusherFake's config details
-HyperMesh.configuration do |config|
-  config.transport = :pusher
-  config.channel_prefix = "HyperMesh"
-  config.opts = {
-    app_id: Pusher.app_id,
-    key: Pusher.key,
-    secret: Pusher.secret
-  }.merge(PusherFake.configuration.web_options)
-end
-```
+## Client Side Scoping
 
-### Simple Poller Details
+By default scopes will be recalculated on the server.  To offload this to the client HyperMesh adds some features to the `ActiveRecord` `scope` method.  Details [here.](docs/client_side_scoping.md)  
 
-Setup your config like this:
-```ruby
-HyperMesh.configuration do |config|
-  config.transport = :simple_poller
-  config.channel_prefix = "HyperMesh"
-  config.opts = {
-    seconds_between_poll: 5, # default is 0.5 you may need to increase if testing with Selenium
-    seconds_polled_data_will_be_retained: 1.hour  # clears channel data after this time, default is 5 minutes
-  }
-end
-```
-
-## The Cache store
-
-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.
+## Authorization
 
-Check in `config/development.rb` and make sure that `cache_store` is never being set to `:null_store`.  
+Each application defines a number of *channels* and *authorization policies* for those channels and the data sent over the channels.
 
-If you would like to be able to interact via
-the `rails console` you should set the store to be something like this:
+Policies are defined with *Policy* classes.  These are similar and compatible with [Pundit](https://github.com/elabs/pundit) but
+you do not need to use the pundit gem (but can if you want.)
 
-```ruby
-# config/development.rb
-Rails.application.configure do
-  ...
-  config.cache_store = :file_store, './rails_cache_dir'
-  ...
-end
-```
+For complete details see [Authorization Policies](docs/authorization-policies.md)
 
 ## Common Errors
 
@@ -283,7 +135,7 @@ By default HyperMesh will look for a `ApplicationPolicy` class.
 - Wrong version of pusher-fake  (pusher-fake/base vs. pusher-fake/rspec)  
 See the Pusher-Fake gem repo for details.
 
-- Forgetting to add require pusher in application.js file  
+- Forgetting to add `require pusher` in application.js file  
 this results in an error like this:
 ```text
 Exception raised while rendering #<TopLevelRailsComponent:0x53e>
@@ -296,10 +148,6 @@ You must explicitly allow changes to the models to be made by the client. If you
 see 500 responses from the server when you try to update.  To open all access do this in
 your application policy: `allow_change(to: :all, on: [:create, :update, :destroy]) { true }`
 
-- `Cannot Run HyperMesh with cache_store == :null_store`  
-You will get this error on boot if you are trying to use the :null cache.  
-See notes above on why you cannot use the :null cache store.
-
 - Cannot connect to real pusher account:  
 If you are trying to use a real pusher account (not pusher-fake) but see errors like this  
 ```text
@@ -315,6 +163,16 @@ HyperMesh will always try to use pusher-fake if it sees the gem included.  Remov
 - Attributes are not being converted from strings, or do not have their default values  
 Eager loading is probably turned off.  HyperMesh needs to eager load `models/public` so it can find all the column information for all public models.
 
+- When starting rails you get a message on the rails console `couldn't find file 'browser'`  
+Hyper-React v0.10.0 removed the dependency on opal-browser.  You will have to add the 'opal-browser' gem to your Gemfile.
+
+- On page load you get a message yacking about super class mismatch for `DummyValue`  
+You are still have the old `reactive-record` gem in your Gemfile, remove it from your gemfile and your components.rb manifest.
+
+- On page load you get a message yacking about no method `session` for `nil`  
+You are still referencing the old reactive-ruby or reactrb gems either directly or indirectly though a gem like reactrb-router.  Replace any gems like
+`reactrb-router` with `hyper-router`.  You can also just remove `reactrb`, as `hyper-react` will be included by the `hyper-mesh` gem.
+
 ## Debugging
 
 Sometimes you need to figure out what connections are available, or what attributes are readable etc.
@@ -362,14 +220,13 @@ You can of course simulate server side changes to your models through this conso
 ## Development
 
 The original `ReactiveRecord` specs were written in opal-rspec.  These are being migrated to
-use server rspec with isomorphic helpers.  There are about 150 of the original tests left and to run
-these you
+use server rspec with isomorphic helpers.  There are about 170 of the original tests left and to run these you
 
 1. cd to `reactive_record_spec/test_app`
 2. do a bundle install/update as needed,
-3. rake db:reset db:test:prepare,
+3. `rake db:reset db:test:prepare`,
 4. start the server: `bundle exec rails s`,
-5. then visit localhost/spec-opal.
+5. then visit `localhost:3000/spec-opal`.
 
 If you want to help **PLEASE** consider spending an hour and migrate a spec file to the new format.  You can
 find examples by looking in the `spec/reactive_record/` directory and matching to the original file in
@@ -385,12 +242,10 @@ bundle exec rspec spec
 
 You can run the specs in firefox by adding `DRIVER=ff` (best for debugging.)  You can add `SHOW_LOGS=true` if running in poltergeist (the default) to see what is going on, but ff is a lot better for debug.
 
-
 ## Contributing
 
 Bug reports and pull requests are welcome on GitHub at https://github.com/reactive-ruby/HyperMesh. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the [Contributor Covenant](contributor-covenant.org) code of conduct.
 
-
 ## License
 
 The gem is available as open source under the terms of the [MIT License](http://opensource.org/licenses/MIT).

data/config/routes.rb

@@ -1,4 +1,4 @@
-ReactiveRecord::Engine.routes.draw do
+HyperMesh::Engine.routes.draw do
   root :to => "reactive_record#fetch", via: :post
   match 'save', to: 'reactive_record#save', via: :post
   match 'destroy', to: 'reactive_record#destroy', via: :post

data/docs/action_cable_quickstart.md

@@ -1,29 +1,21 @@
 ### Action Cable Quickstart
 
-Action Cable is production ready transport built into Rails 5.
+Action Cable is a production ready transport built into Rails 5.
 
 #### 1 Get Rails 5
 
 You need to be on rails 5 to use ActionCable.  Make sure you upgrade to rails 5 first.
 
-#### 2 Add ReactRb
+#### 2 Add HyperLoop gems
 
-If you have not already installed the `reactrb` and `reactive-record` gems, then do so now using the [reactrb-rails-generator](https://github.com/hyper-react/reactrb-rails-generator) gem.
+If you have not already installed the `hyper-react` and `hyper-mesh` gems, then do so now using the [hyper-rails](https://github.com/ruby-hyperloop/hyper-rails) gem.
 
-- add `gem 'reactrb-rails-generator'` to your gem file (in the development section)
+- add `gem 'hyper-rails'` to your gem file (in the development section)
 - run `bundle install`
-- run `rails g hyper-react:install --all` (make sure to use the --all option)
+- run `rails g hyperloop:install --all` (make sure to use the --all option)
 - run `bundle update`
 
-#### 3 Reactrb and ReactiveRecord is replaced with HyperMesh
-
-- replace the `'reactive-record'` and `'reactrb'` gems with  
-`gem 'hyper-mesh', git: 'https://github.com/ruby-hyperloop/hyper-mesh'`  
-**note:** you must remove `gem 'reactive-record'`
-- then `bundle install`  
-- and in `app/views/components.rb` replace `require 'reactive-record'` with `require 'hyper-mesh'`  
-
-#### 4 Set the transport
+#### 3 Set the transport
 
 Once you have HyperMesh installed then add this initializer:
 ```ruby
@@ -33,28 +25,13 @@ HyperMesh.configuration do |config|
 end
 ```
 
-#### 5 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
-```
-
-#### 6 Setup ActionCable
+#### 4 Setup ActionCable
 
 If you are already using ActionCable in your app that is fine, as HyperMesh will not interfere with your existing connections.
 
 Otherwise go through the following steps to setup ActionCable.
 
-##### 6.1 Add the action_cable.js file
-
-Include the `action_cable` js file in your assets
+##### Make sure the `action_cable` js file in your assets
 
 ```javascript
 //app/assets/javascripts/application.js
@@ -63,7 +40,7 @@ Include the `action_cable` js file in your assets
 Opal.load('components');
 ```
 
-##### 6.2 Make sure you have a cable.yml file
+##### Make sure you have a cable.yml file
 
 ```yml
 # config/cable.yml
@@ -78,7 +55,7 @@ production:
   url: redis://localhost:6379/1
 ```
 
-##### 6.3 Set allowed request origins (optional)
+##### Set allowed request origins (optional)
 
 By default action cable will only allow connections from localhost:3000 in development.  If you are going to something other than localhost:3000 you need to add something like this to your config:
 
@@ -89,7 +66,7 @@ Rails.application.configure do
 end
 ```
 
-#### 7 Try It Out  
+#### 5 Try It Out  
 
 If you don't already have a model to play with,  add one now:
 
@@ -101,7 +78,7 @@ Whatever model(s) you will plan to access on the client need to moved to the `ap
 
 **Important** in rails 5 there is also a base `ApplicationRecord` class, that all other models are built from.  This class must be moved to the public directory as well.
 
-If you don't already have a simple component to play with,  here is a simple one (make sure you add the Word model):
+If you don't already have a simple component to play with,  here is a simple one (make sure you added the Word model):
 
 ```ruby
 # app/views/components/app.rb
@@ -148,4 +125,4 @@ Fire up rails with `bundle exec rails s` and open your app in a couple of browse
 
 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)
+If you want to go into more details with the example check out [words-example](/docs/words-example.md)