hyper-mesh 0.5.2 → 0.5.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 48e04a10e1ad295fd3b0d59e4bf55f376c4b7776
-  data.tar.gz: eef9862a88351836cc5a0bccfec7e3d7899d0315
+  metadata.gz: b8982a6629467339b2a91000f327e77e5d1b08f9
+  data.tar.gz: ff8f97442cfc6de5a5902c424e19d89e490a2f99
 SHA512:
-  metadata.gz: c7458271b5d897075e1769db7017ce01e4cbe87d2c756605051f42e9131ddf8ca5816d81538b12c8f04e852902e4890b86cd3fabc944f6c1c2a484ddff91572e
-  data.tar.gz: b636a901cfe8eb0434c54cd3baa61534c34f758243531a2946b2d9dd3504e21d93f3154defbdf2542a6b31e78b7044377d05fe4b6a5c2ef82415f931ba655f91
+  metadata.gz: ac64d306366dcf4eca7034e60c04ec423766d93f76d2dabef0c123d31e9447654b29046e0055daf86ef5c6b35609c9d02fec01e523f8da5fc90326e781edaabe
+  data.tar.gz: 61ae00d5f4ecf921d4acc9037808841c5539fb4ed59dbbfac712bef62e1c2512d049a89217de410719d9fb0cd89de2c04b3162fa3a19d1423f472ca3b59810af

data/CHANGELOG.md

@@ -0,0 +1,34 @@
+# Change Log
+
+All notable changes to this project will be documented in this file starting with v0.8.4.
+This project *tries* to adhere to [Semantic Versioning](http://semver.org/), even before v1.0.
+
+Changes are grouped as follows:
+- **Added** for new features.
+- **Changed** for changes in existing functionality.
+- **Deprecated** for once-stable features to be removed in upcoming releases.
+- **Removed** for deprecated features removed in this release.
+- **Fixed** for any bug fixes.
+- **Security** to invite users to upgrade in case of vulnerabilities.
+
+<!--
+Whitespace conventions:
+- 4 spaces before ## titles
+- 2 spaces before ### titles
+- 1 spaces before normal text
+ -->
+
+## [0.5.3] - 2017-01-03
+
+
+### Added
+
+- Fixed problem with synchronizing multiple requests to same record within one render cycle (#20)
+- Add *finder* methods.  I.e. server side methods that return a single record using a custom query. (#12)
+- Allow `save` even if records are loading (#10)
+- `ReactiveRecord.Load` will automatically apply `.itself` to the final value of the load block (#9)
+
+
+### Fixed
+
+- Can't create AR records from within Rake Tasks. (#20)

data/README.md

@@ -1,10 +1,9 @@
 #  ![](https://avatars3.githubusercontent.com/u/15810526?v=3&s=40&raw=true)HyperMesh
 
-
 [![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.
+HyperMesh gives your HyperReact components CRUD access to your server side ActiveRecord models, using 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.
 
@@ -27,7 +26,7 @@ For example consider a simple model called `Dictionary` which might be part of W
 class Dictionary < ActiveRecord::Base
 
   # attributes
-  #   word: string
+  #   word: string   
   #   definition: text
   #   pronunciation: string
 
@@ -69,7 +68,7 @@ For more complete examples with *push* updates checkout any of the apps in the `
 
 + [Rails 5 with ActionCable](/docs/action_cable_quickstart.md)
 + [Using Pusher.com](/docs/pusher_quickstart.md)
-+ [Using Pusher-Faker](/docs/pusher_quickstart.md)
++ [Using Pusher-Faker](/docs/pusher_faker_quickstart.md)
 + [Using Simple Polling](/docs/simple_poller_quickstart.md)  
 
 ## Basic Installation and Setup
@@ -93,7 +92,7 @@ To have changes to your models on the server  broadcast to authorized clients, a
 
 ```ruby
 # config/initializers/hyper_mesh.rb
-HyperMesh.configuration |config|
+HyperMesh.configuration do |config|
   config.transport = :simple_poller
 end
 ```
@@ -104,7 +103,7 @@ For setting up the other possible transports following one of these guides:
 
 + [Rails 5 with ActionCable](/docs/action_cable_quickstart.md)
 + [Using Pusher.com](/docs/pusher_quickstart.md)
-+ [Using Pusher-Faker](/docs/pusher_quickstart.md)
++ [Using Pusher-Faker](/docs/pusher_faker_quickstart.md)
 + [Using Simple Polling](/docs/simple_poller_quickstart.md)
 
 ## Advanced Configuration
@@ -142,29 +141,29 @@ By default HyperMesh will look for a `ApplicationPolicy` class.
 See the Pusher-Fake gem repo for details.
 
 - Forgetting to add `require pusher` in application.js file  
-this results in an error like this:
+this results in an error like this:   
 ```text
 Exception raised while rendering #<TopLevelRailsComponent:0x53e>
     ReferenceError: Pusher is not defined
 ```  
 To resolve make sure you `require 'pusher'` in your application.js file if using pusher.  **DO NOT** require pusher from your components manifest as this will cause prerendering to fail.
 
-- No create/update/destroy policies
+- No create/update/destroy policies   
 You must explicitly allow changes to the models to be made by the client. If you don't you will
 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 connect to real pusher account:  
 If you are trying to use a real pusher account (not pusher-fake) but see errors like this  
-```text
+```text   
 pusher.self.js?body=1:62 WebSocket connection to
 'wss://127.0.0.1/app/PUSHER_API_KEY?protocol=7&client=js&version=3.0.0&flash=false'
 failed: Error in connection establishment: net::ERR_CONNECTION_REFUSED
-```
+```   
 Check to see if you are including the pusher-fake gem.  
 HyperMesh will always try to use pusher-fake if it sees the gem included.  Remove it and you should be good to go.  See [issue #5](https://github.com/hyper-react/HyperMesh/issues/5) for more details.
 
-- Cannot connect with ActionCable.  Make sure that `config.action_cable.allowed_request_origins` includes the url you use for development (including the port) and that you are useing `Puma`.
+- Cannot connect with ActionCable.  Make sure that `config.action_cable.allowed_request_origins` includes the url you use for development (including the port) and that you are using `Puma`.
 
 - 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.

data/docs/activerecord_api.md

@@ -1,12 +1,12 @@
 ## ActiveRecord API
 
-HyperMesh uses a subset of the standard ActiveRecord API to give your client side HyperReact components access to your server side models.  As much as possible HyperMesh follows the syntax as semantics of ActiveRecord.  
+HyperMesh uses a subset of the standard ActiveRecord API to give your client side HyperReact components access to your server side models.  As much as possible HyperMesh follows the syntax and semantics of ActiveRecord.  
 
 ### Interfacing to React
 
-HyperMesh uses the React to deliver your model data to the client without you having to create extra APIs or specialized controllers.  The key idea of React is that when state (or params) change, the portions of the display effected by this data will be updated.
+HyperMesh integrates with React to deliver your model data to the client without you having to create extra APIs or specialized controllers.  The key idea of React is that when state (or params) change, the portions of the display effected by this data will be updated.
 
-HyperMesh automatically creates state objects that will be updated as server side data is loaded, or changes.  
+HyperMesh automatically creates react state objects that will be updated as server side data is loaded or changes.  When these states change the associated parts of the display will be updated.
 
 A brief overview of how this works will help you understand the how HyperMesh gets the job done.
 
@@ -14,23 +14,27 @@ A brief overview of how this works will help you understand the how HyperMesh ge
 
 On the UI you will be reading models in order to display data.
 
-If during the rendering of the display the model data is not yet loaded placeholder values (the default values from the `columns_hash`) will be returned by HyperMesh.  
+If during the rendering of the display the model data is not yet loaded, placeholder values (the default values from the `columns_hash`) will be returned by HyperMesh.  
 
 HyperMesh then keeps track of where these placeholders (or `DummyValue`s) are displayed, and when they do get loaded, those parts of the display will re-render.
 
 If later the data changes (either due to local user actions, or receiving push updates) then again any parts of the display that were dependent on the current values will be re-rendered.
 
-You normally do not have to be aware of this.  Just access your models using the normal scopes and finders, to compute values and  display attributes as you would on the server.  Initially the display will show the placeholder values and then will be replaced with the real values.
-
+You normally do not have to be aware of this.  Just access your models using the normal scopes and finders, then compute values and display attributes as you would on the server.  Initially the display will show the placeholder values and then will be replaced with the real values.
 
 #### Prerendering
 
-During server-side pre-rendering, we do know all the values immediately so on initial page load all the values will be loaded and present.  
+During server-side pre-rendering, HyperMesh has direct access to the server so on initial page load all the values will be loaded and present.  
 
-#### Load Cycle Methods
+#### Lazy Loading
 
-There are a number of methods that allow you to interact with this load cycle when needed.  These are documented [below].
+HyperMesh lazy loads values, and does not load any thing until an explicit displayable value is requested.  For example `Todo.all` will have no action, but `Todo.all.pluck[:title]` will return an array of titles.
 
+At the end of the rendering cycle the set of all values requested will be merged into a tree structure and sent to the server, returning the minimum amount of data needed.
+
+#### Load Cycle Methods
+
+There are a number of methods that allow you to interact with this load cycle when needed.  These are documented [below](#other-methods-for-interacting-with-the-load-and-render-cycle).
 
 ### Class Methods
 
@@ -38,16 +42,16 @@ There are a number of methods that allow you to interact with this load cycle wh
 
 `new`: Takes a hash of attributes and initializes a new unsaved record.  The values of any attributes not specified in the hash will be taken from the models default values specified in the `columns_hash`.
 
-If new is passed a native javascript object it will be treated as a hash and converted accordingly.
+If `new` is passed a native javascript object it will be treated as a hash and converted accordingly.
 
 `create`: Short hand for `new(...).save`.  See the `save` instance method for details on how saving is done.
 
 #### Scoping and Finding
 
-`scope` and `default_scope`:  HyperMesh adds four new options to these methods: `joins`, `client`, `select` and `server`.  The `joins` option provides information on how the scope will be joined with other models.  The `client` and `select` options allow scoping to be done on the client side to offload this from the server, and the `server` option is there just for symmetry with the othe options.  See the [Client Side Scoping](/docs/client_side_scoping.md) page for more details.
+`scope` and `default_scope`:  HyperMesh adds four new options to these methods: `joins`, `client`, `select` and `server`.  The `joins` option provides information on how the scope will be joined with other models.  The `client` and `select` options allow scoping to be done on the client side to offload this from the server, and the `server` option is there just for symmetry with the other options.  See the [Client Side Scoping](/docs/client_side_scoping.md) page for more details.
 
 ```ruby
-# the scope proc is executed on the server
+# the active scope proc is executed on the server
 scope :active, -> () { where(completed: true) }
 
 # if the scope does a join (or include) this must be indicated
@@ -61,7 +65,7 @@ scope :with_recent_comments,
 # locally at the client
 scope :completed,
       server: -> { where(complete: true) }
-      client: -> { complete }
+      client: -> { complete } # return true if the record should be included
 ```
 
 `unscoped` and `all`: These builtin scopes work just like standard ActiveRecord.
@@ -70,25 +74,27 @@ scope :completed,
 Word.all.each { |word| LI { word.text }}
 ```
 
-`limit` and `offset`: These builtin scopes behave as they do on the server:
-
-```ruby
-Word.offset(500).limit(20) # get words 500-519
-```
+BTW: to save typing you can skip the `all`:  Models will respond like enumerators
 
-`find`: takes an id and returns the corresponding record.
+`find`: takes an id and delivers the corresponding record.
 
-`find_by`: takes single item hash indicating an attribute value pair to find.
+`find_by`: takes a single item hash indicating an attribute value pair to find.
 
-`find_by_...`: i.e. `find_by_first_name` these will find the first record with a matching attribute.
+`find_by_...`: i.e. `find_by_first_name` these methods will find the first record with a matching attribute.
 
 ```ruby
 Word.find_by_text('hello') # short for Word.find_by(text: 'hello')
 ```
 
+`limit` and `offset`: These builtin scopes behave as they do on the server:
+
+```ruby
+Word.offset(500).limit(20) # get words 500-519
+```
+
 #### Relationships and Aggregations
 
-`belongs_to, has_many, has_one`:  These all work as on the server.  However it is important that you fully specify both sides of the relationship.  This is not always necessary on the server because ActiveRecord uses the table schema to work things out.
+`belongs_to, has_many, has_one`:  These all work as on the server.  However it is important that you fully specify both sides of the relationship.  
 
 ```ruby
 class Todo < ActiveRecord::Base
@@ -100,8 +106,22 @@ class User < ActiveRecord::Base
 end
 ```
 
+Note that on the client the linkages between relationships are live and direct.  In the above example this works:
+
+```ruby
+Todo.create(assigned_to: some_user)
+```
+
+but this may not:
+
+```ruby
+Todo.create(assigned_to_id: some_user.id)
+```
+
 `composed_of`: You can create aggregate models like ActiveRecord.
 
+Similar to the linkages in relationships, aggregate records are represented on the client as actual independent objects.
+
 #### Defining server methods
 
 Normally an application defined instance method will run on the client and the server:
@@ -114,7 +134,7 @@ class User < ActiveRecord::Base
 end
 ```
 
-Sometimes it is desirable to only run method on the server.  This can be done using the `server_method` macro:
+Sometimes it is desirable to only run the method on the server.  This can be done using the `server_method` macro:
 
 ```ruby
 class User < ActiveRecord::Base
@@ -124,7 +144,7 @@ class User < ActiveRecord::Base
 end
 ```
 
-When the method is first called on the client the default value will be returned, and there will be a reactive update when the true value is  returned from the server.
+When the method is first called on the client the default value will be returned, and there will be a reactive update when the true value is returned from the server.
 
 To force the value to be recomputed at the server append a  `!` to the end of the name, otherwise the last value returned from the server will continue to be returned.
 
@@ -140,11 +160,11 @@ To force the value to be recomputed at the server append a  `!` to the end of th
 
 #### Attribute and Relationship Getter and Setters
 
-All attributes have an associated getter and setter. All relationships have a getter.  All belongs_to relationships have a setter.  `has_many` relationships can be updated using the push (`<<`) operator or using the `delete` method.
+All attributes have an associated getter and setter. All relationships have a getter.  All `belongs_to` relationships also have a setter.  `has_many` relationships can be updated using the push (`<<`) operator or using the `delete` method.
 
 ```ruby
-  puts my_todo.name
-  my_todo.name = "neuname"
+  puts my_todo.title
+  my_todo.title = "neutitle"
   my_todo.comments << a_new_comment
   a_new_comment.todo == my_todo # true!
 ```
@@ -161,7 +181,7 @@ my_todo.save(validate: false).then do |result|
 end
 ```
 
-After saving the models will have an `errors` hash with any validation problems.
+After a save operation completes the models will have an `errors` hash (just like on the server) with any validation problems.
 
 During the save operation the method `saving?` will return `true`.  This can be used to instead of (or with) the promise to update the screen:
 
@@ -183,7 +203,7 @@ end
 
 Like `save` destroy returns a promise that is resolved when the destroy completes.
 
-After the destroy completes the records `destroyed?` method will return true.
+After the destroy completes the record's `destroyed?` method will return true.
 
 #### Other Instance Methods
 
@@ -201,17 +221,17 @@ After the destroy completes the records `destroyed?` method will return true.
 
 `dup` duplicate the instance.
 
-`==` two instances are the same if they reference the same underlying table row.  
+`==` two instances are the same if it is known that they reference the same underlying table row.  
 
 `..._changed?` (i.e. name_changed?) returns true if the specific attribute has changed.
 
-`itself` returns the record, but will also force a load of at least the model's id.
+`itself` returns the record, but will override lazy loading and force a load of at least the model's id.
 
-#### Other Methods for Interacting with the Load & Render Cycle
+### Other Methods for Interacting with the Load and Render Cycle
 
 #### `loading?` and `loaded?`
 
-All Ruby objects will respond to these methods.  If you want to put up a "Please Wait" message, spinner, etc, you can use the `loaded?` or `loading?` method to determine if the object represents a real loaded value or not.
+All Ruby objects will respond to these methods.  If you want to put up a "Please Wait" message, spinner, etc, you can use the `loaded?` or `loading?` method to determine if the object represents a real loaded value or not.  Any value for which `loaded?` returns `false` (or `loading?` returns `true`) will eventually load and cause a re-render
 
 #### The `HyperMesh.load` Method
 
@@ -229,17 +249,13 @@ end.then |result|
 end
 ```
 
-
-
 #### Force Loading Attributes
 
-Like
-
 Normally you will simply display attributes as part of the render method, and when the values are loaded from the server the component will re-render.
 
 Sometimes outside of the render method you may need to insure an attribute (or a server side method) is loaded before proceeding.  This is typically when you are building some kind of higher level store.  
 
-The `load` takes a list of attributes (symbols) and will insure these are loaded.  Load returns a promise that is resolved when the load completes, or can be passed a block that will execute when the load completes.
+The `load` method takes a list of attributes (symbols) and will insure these are loaded.  Load returns a promise that is resolved when the load completes, or can be passed a block that will execute when the load completes.
 
 ```ruby
 before_mount do
@@ -250,4 +266,4 @@ before_mount do
 end
 ```
 
-Think hard about how you are using this, as HyperMesh already acts as flux store, and is managing state for you.
+Think hard about how you are using this, as HyperMesh already acts as flux store, and is managing state for you.  It may be you are just creating a redundant store!

data/docs/authorization-policies.md

@@ -1,8 +1,12 @@
 ### HyperMesh Authorization Policies
 
-Each time an ActiveRecord model changes, HyperMesh broadcasts the changed attributes over *channels*.
+Access to your models is controlled by *Policies* that describe how the current *acting_user* and *channels* may access your models.
 
-An application can have several channels and each channel and each active record model can have different *policies* to determine which attributes are sent when a record changes.
+Each browser session has an *acting_user* (which may be nil) and you will define `create`, `update`, and `destroy` policies giving (or denying) the `acting_user` the ability to do these operations.
+
+Read and *broadcast* access is defined based on *channels* which are connected based again on the current `acting_user`.  Read access is initiated when a specific browser tries to read a record attribute, and broadcasts are initiated whenever a model changes.
+
+An application can have several channels and each channel and each active record model can have different policies to determine which attributes are sent when a record changes.
 
 For example a Todo application might have an *instance* of a channel for each currently logged in user; an instance of a channel for each team if that team has one or more logged in users; and a general `AdminUser` channel shared by all administrators that are logged in.
 
@@ -20,8 +24,8 @@ class UserPolicy # defines policies for the User class
   # The policy is defined by a block that is executed in the context of the
   # current acting_user.
 
-  # For our User instance connection the policy is that there must be logged in
-  # user, and the connection is made to that user:
+  # For our User instance connection the policy is that there must be a
+  # logged-in user, and the connection is made to that user:
   regulate_instance_connections { self }
   # If there is no logged in user self will be nil, and no connection will be
   # made.
@@ -206,7 +210,7 @@ Typically connections are made to ActiveRecord models, and if those are in the `
 
 #### Acting User
 
-HyperMesh uses the same `acting_user` method that reactive-record permissions uses.  This method is typically defined in the ApplicationController and would normally pick up the current session user, and return an appropriate object.
+HyperMesh looks for an `acting_user` method typically defined in the ApplicationController and would normally pick up the current session user, and return an appropriate object.
 
 ```ruby
 class ApplicationController < ActiveController::Base
@@ -405,6 +409,59 @@ class MessagePolicy
 end
 ```
 
+#### Browser Initiated Change policies
+
+To allow code in the browser to create, update or destroy a model, there must be a change access policy defined for that operation.
+
+Each change access policy executes a block in the context of the record that will be accessed.  The current value of `acting_user` is also defined for the life of the block.
+
+If the block returns a truthy value access will be allowed, otherwise if the block returns a falsy value or raises an exception, access will be denied.
+
+In the below examples we assume that your user model responds to `admin?` but this is not built into HyperMesh.
+
+```ruby
+class TodoPolicy
+  # allow creation to any logged in user
+  allow_create { acting_user }
+  # only allow the owner, author any any admin to update a todo
+  allow_update { acting_user == owner || acting_user == author || acting_user.admin? }
+  # don't allow Todo's to be destroyed
+  # this is the default behavior so its not actually needed
+  allow_destroy { false }
+end
+```
+
+There are several variants of the access policy method:
+
+```ruby
+class ConfigDataPolicy
+  allow_change(on: [:create, :update, :destroy]) { acting_user.admin? }
+  # which can be shortened to:
+  allow_change { acting_user.admin? }
+end
+```
+
+```ruby
+class ApplicationPolicy
+  # do any thing to all models unless we are in production!  Be careful!
+  allow_change(to: :all) { true } unless Rails.env.production?
+  # and always allow admins to destroy models globally:
+  allow_change(to: :all, on: :destroy) { acting_user.admin? }
+  # which is the same as saying:
+  allow_destroy(to: :all) { acting_user.admin? }
+  # you can create model specific policies in the Application Policy as well.
+  # Here we allow the author of a message to destroy the message within 5
+  # minutes of creation.
+  allow_destroy(to: Message) do
+    return true if acting_user == author && created_at > 5.minutes.ago
+    return true if acting_user.admin?
+  end
+end
+```
+
+Note that there is no `allow_read` method.  Read access is granted if this browser would have the attribute broadcast to it.  
+
+
 #### Method Summary and Name Space Conflicts
 
 Policy classes (and the HyperMesh::PolicyMethods module) define the following class methods:
@@ -433,17 +490,3 @@ class ProductionCenterPolicy < MyPolicyClass
   ...
 end
 ```  
-
-#### Setting the policy directory
-
-*HyperMesh auto-connect needs to know about all policies ahead of time so cannot rely on rails auto loading.  Sorry about that!*
-
-By default HyperMesh will load all the files in the `app/policies` directory.  To change the directory set the policy_directory in the synchromesh initializer.  
-
-```ruby
-HyperMesh.configuration do |config|
-  ...
-  config.policy_directory = File.join(Rails.root, 'app', 'synchromesh-authorization')
-  # can also be set to nil if you want to manually require your files
-end
-```