RubyGems - hyper-mesh - Versions diffs - 0.6.0 → 1.0.0.lap22 - Mend

hyper-mesh 0.6.0 → 1.0.0.lap22

Files changed (722) hide show

data/docs/action_cable_quickstart.md DELETED

@@ -1,134 +0,0 @@
-### Action Cable Quickstart
-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 Hyperloop gems
-If you have not already installed the `hyper-component` and `hyper-model` gems, then do so now using the [hyper-rails](https://github.com/ruby-hyperloop/hyper-rails) gem.
-- add `gem 'hyper-rails'` to your gem file (in the development section)
-- run `bundle install`
-- run `rails g hyperloop:install --all` (make sure to use the --all option)
-- run `bundle update`
-#### 3 Set the transport
-TODO check below
-Once you have Hyperloop installed then add this initializer:
-```ruby
-#config/initializers/hyperloop.rb
-Hyperloop.configuration do |config|
-  config.transport = :action_cable
-end
-```
-#### 4 Setup ActionCable
-If you are already using ActionCable in your app that is fine, as Hyperloop will not interfere with your existing connections.
-Otherwise go through the following steps to setup ActionCable.
-##### Make sure the `action_cable` js file is required in your assets
-Typically `app/assets/javascripts/application.js` will finish with a `require_tree .` and this will pull in the `cable.js` file which will pull in `action_cable.js`
-However at a minimum if `application.js` simply does a `require action_cable` that will be sufficient for Hyperloop.
-##### Make sure you have a cable.yml file
-```yml
-# config/cable.yml
-development:
-  adapter: async
-test:
-  adapter: async
-production:
-  adapter: redis
-  url: redis://localhost:6379/1
-```
-#### 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:
-```ruby
-# config/environments/development.rb
-Rails.application.configure do
-  config.action_cable.allowed_request_origins = ['http://localhost:3000', 'http://localhost:5000']
-end
-```
-#### 5 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`
-Move `app/models/word.rb` to `app/hyperloop/models/word.rb` and move
-`app/models/application_record.rb` to `app/hyperloop/models/application_record.rb`
-**Leave** `app/models/model.rb` where it is.  This is your models client side manifest file.
-Whatever model(s) you will plan to access on the client need to moved to the `app/hyperloop/models` directory.  This allows Hyperloop to build a client side proxy for the Models.  Models not moved will be completely invisible on the client or in your Isomorphic code.
-**Important** in rails 5 there is also a base `ApplicationRecord` class, that all other models are built from.  This class must be moved to `app/hyperloop/models` directory as well.
-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
-class App < Hyperloop::Component
-  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 the example check out [words-example](/docs/words-example.md)
-TODO check link above

data/docs/activerecord_api.md DELETED

@@ -1,275 +0,0 @@
-## ActiveRecord API
-Hyperloop uses a subset of the standard ActiveRecord API to give your Isomorphic Components, Operations and Stores access to your server side Models.  As much as possible Hyperloop follows the syntax and semantics of ActiveRecord.
-### Interfacing to React
-Hyperloop integrates with React (through Components) 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.
-Hyperloop 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 Hypeloop gets the job done.
-#### Rendering Cycle
-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 Hyperloop.
-Hyperloop 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, 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, Hyperloop has direct access to the server so on initial page load all the values will be loaded and present.
-#### Lazy Loading
-Hyperloop 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
-TODO check link below
-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
-#### New and Create
-`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.
-`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`:  Hyperloop 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.
-TODO check link above
-```ruby
-# 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
-# using the joins: option.
-scope :with_recent_comments,
-      -> { joins(:comments).where('comment.created_at >= ?', Time.now-1.week) },
-      joins: ['comments'] # or joins: 'comments'
-# the server side proc can be indicated by the server: option
-# an optional client side proc can be provided to compute the scope
-# locally at the client
-scope :completed,
-      server: -> { where(complete: true) }
-      client: -> { complete } # return true if the record should be included
-```
-`unscoped` and `all`: These builtin scopes work just like standard ActiveRecord.
-```ruby
-Word.all.each { |word| LI { word.text }}
-```
-BTW: to save typing you can skip the `all`:  Models will respond like enumerators.
-`find`: takes an id and delivers the corresponding record.
-`find_by`: takes a single item hash indicating an attribute value pair to find.
-`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.**
-```ruby
-class Todo < ActiveRecord::Base
-  belongs_to :assigned_to, class_name: 'User'
-end
-class User < ActiveRecord::Base
-  has_many :todos, foreign_key: 'assigned_to_id'
-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:
-```ruby
-class User < ActiveRecord::Base
-  def full_name
-    "#{first_name} #{last_name}"
-  end
-end
-```
-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
-  server_method :full_name, default: '' do
-    "#{first_name} #{last_name}"
-  end
-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.
-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.
-#### Model Information
-`column_names`: returns a list of the database columns.
-`columns_hash`: returns the details of the columns specification.  Note that on the server `columns_hash` returns a hash of objects specifying column information.  On the client the entire structure is just one big hash of hashes.
-`abstract_class=`, `abstract_class?`, `primary_key`, `primary_key=`, `inheritance_column`, `inheritance_column=`, `model_name`:  All work as on the server.  See ActiveRecord documentation for more info.
-### Instance Methods
-#### Attribute and Relationship Getter and Setters
-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.title
-  my_todo.title = "neutitle"
-  my_todo.comments << a_new_comment
-  a_new_comment.todo == my_todo # true!
-```
-In addition if the attribute getter ends with a bang (!) then this will force a fetch of the attribute from the server.  This is typically not necessary if push updates are configured.
-#### Saving
-The `save` method works like ActiveRecord save, *except* it returns a promise that is resolved when the save completes (or fails.)
-```ruby
-my_todo.save(validate: false).then do |result|
-  # result is a hash with {success: ..., message: , models: ....}
-end
-```
-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:
-```ruby
-render do
-  ...
-  if some_model.saving?
-    ... display please wait ...
-  elsif some_model.errors.any?
-    ... highlight the errors ...
-  else
-    ... display data ...
-  end
-  ...
-end
-```
-#### Destroy
-Like `save` destroy returns a promise that is resolved when the destroy completes.
-After the destroy completes the record's `destroyed?` method will return true.
-#### Other Instance Methods
-`new?` returns true if the model is new and not yet saved.
-`primary_key` returns the primary key for the model
-`id` returns the value of the primary key for this instance
-`model_name` returns the model_name.
-`revert` Undoes any unsaved changes to the instance.
-`changed?` returns true if any attributes have changed (always true for a new model)
-`dup` duplicate the instance.
-`==` 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 override lazy loading and force a load of at least the model's id.
-### 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.  Any value for which `loaded?` returns `false` (or `loading?` returns `true`) will eventually load and cause a re-render
-TODO check below (was HyperMesh.load)
-#### The `HyperModel.load` Method
-Sometimes it is necessary to insure values are loaded outside of the rendering cycle.  For this you can use the `HyperModel.load` method:
-```ruby
-HyperModel.load do
-  x = my_model.some_attribute
-  OtherModel.find(x+12).other_attribute
-  # code in here can be arbitrarily complex and load
-  # will re-execute it until all values are loaded
-  # the final expression is passed to the promise
-end.then |result|
-  puts result
-end
-```
-#### Force Loading Attributes
-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` 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
-  Todo.find(1).load(:name).then do |name|
-    @name = name;
-    state.loaded! true
-  end
-end
-```
-Think hard about how you are using this, as Hyperloop 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 DELETED

@@ -1,502 +0,0 @@
-### Hyperloop Authorization Policies
-TODO: Move this doc to a Policy Section
-Access to your Isomorphic Models is controlled by *Policies* that describe how the current *acting_user* and *channels* may access your Models.
-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.
-Lets say a specific `Todo` changes, which is part of team id 123's Todo list, and users 7 and 8 who are members of that team are currently logged in as well as two of the `AdminUsers`.
-When the `Todo` changes we want all the attributes of the `Todo` broadcast on team 123's channel, as well on the `AdminUser`'s channel.  Now lets say User 7 sends User 8 a private message, adding a new record to the `Message` model.  This update should only be sent to user 7 and user 8's private channels, as well as to the AdminUser channel.
-We can define all these policies by creating the following classes:
-```ruby
-class UserPolicy # defines policies for the User class
-  # The regulate_instance_connections method enables instances of the User
-  # class to be treated as a channel.
-  # 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 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.
-end
-class TeamPolicy # defines policies for the Team class
-  # Users can only connect to Teams that they belong to
-  regulate_instance_connections { teams }
-end
-class AdminUserPolicy
-  # All AdminUsers share the same connection so we setup a class wide
-  # connection available to any users who are admins.
-  regulate_class_connection { admin? }
-  # The AdminUser channel will receive all attributes
-  # of all records, unless the attribute is named :password
-  regulate_all_broadcasts do |policy|
-    policy.send_all_but(:password)
-  end
-end
-class TodoPolicy
-  # Policies can be established for models that are not channels as well.
-  # The regulate_broadcast method will describe what attributes to send
-  # when a Todo model changes.
-  # The blocks of broadcast policies run in the context of the changed model
-  # so we have access to all the models methods.  In this case Todo
-  # belongs to a Team through the 'team' relationship.
-  regulate_broadcast do |policy|
-    # send all Todo attributes to the todo's team channel
-    policy.send_all.to(team)
-  end
-end
-class MessagePolicy
-  # Broadcast policies can be arbitrarily complex.  In this case we
-  # want to broadcast the entire message to the sender and the
-  # recipient's instance channels.
-  # In addition if the message is not private, then we want to send to all
-  # the team instance channels that are shared between the sender and
-  # recipient's teams.
-  regulate_broadcast do |policy|
-    policy.send_all.to(sender, recipient)
-    policy.send_all.to(sender.teams.merge(recipient.teams)) unless private?
-  end
-end
-```
-Before we begin using these channels and policies we need to first define the Reactive-Record `acting_user` method in our ApplicationController:
-```ruby
-class ApplicationController < ActionController::Base
-  def acting_user
-    # The acting_user method should return nil, or some object that corresponds to a
-    # logged in user.  Specifics will depend on your application and whatever other
-    # authentication mechanisms you are using.
-    @acting_user ||= session[:current_user_id] && User.find_by_id(session[:current_user_id])
-    end
-  end
-end
-```
-Note that `acting_user` is also used by ReactiveRecord's permission system.
-Our entire set of policies is defined in 29 lines of code of which 8 actually execute the policies.  Our existing classes form the foundation, and we simply add Hyperloop specific policy directives.  Pretty sweet huh?
-### Details
-Hyperloop uses *Policies* to *regulate* what *connections* are opened between clients and the server and what data is distributed over those connections.
-Connections are made on *channels* of data flowing between the server and a number of clients.  Each channel is associated with either a class or an instance of a class.  Typically the channel class represents an entity (or is associated with an entity) that can be authenticated like a `User`, an  `AdminUser`, or a `Team` of users.  A channel associated with the class itself broadcasts data that is received by any member of that class.  A channel associated with an instance is for data that is available only to that specific instance.
-As Models on the server change (i.e. created, updated, or destroyed) the changes are broadcast over open channels.  What specific attributes are sent (if any) is determined by broadcast policies.
-Broadcast policies can be associated with Models.  As the Model changes the broadcast policy will regulate what attributes of the changed model will be sent over which channels.
-Broadcast policies can also be associated with a channel and will regulate *all* model changes over specific channels.  In other words this is just a convenient way to associate a common policy with *all* Models.
-Note that Models that are associated with channels can also broadcast their changes on the same or different channels.
-#### Defining Policies and Policy Classes
-The best way to define policies is to use a *Policy Class*.  A policy class has the same class name as the class it is regulating, with `Policy` added to the end.  Policy classes are compatible with `Pundit`, and you can add regular pundit policies as well.
-Policies are defined using four methods:
-+ `regulate_class_connection` controls connections to the class channels,
-+ `regulate_instance_connections` controls connections to instance channels,
-+ `regulate_broadcast` controls what data will be sent when a model or object changes and,
-+ `regulate_all_broadcasts` controls what data will be sent of some channels when any model changes.
-In addition `always_allow_connection` is short hand for `regulate_class_connection { true }`
-A policy class can be defined for which there is no regulated class.  This is useful for application wide connections, which are typically open even if no one is logged in:
-```ruby
-#app/policies/application.rb
-class ApplicationPolicy
-  regulate_class_connection { true }
-end
-```
-Note that by default policy classes go in the `app/policies` directory.  Hyperloop will require all the files in this directory.
-TODO check the name of the module below
-If you wish, you can also add policies directly in your Models by including the `Hyperloop::PolicyMethods` module in your model.  You can then use the `regulate_class_connection`, `regulate_instance_connections`, `regulate_all_broadcasts` and `regulate_broadcast` methods directly in the model.
-```ruby
-class User < ActiveRecord::Base
-  include Hyperloop::PolicyMethods
-  regulate_class_connection ...
-  regulate_instance_connections ...
-  regulate_all_broadcasts ...
-  regulate_broadcast ...
-end
-```
-Normally the policy methods are regulating the class with the prefix as the policy, but you can override this by providing specific class names to the policy method.  This allows you to group several different class policies together, and to reuse policies:
-```ruby
-class ApplicationPolicy
-  regulate_connection { ... }  # Application is assumed
-  regulate_class_connection(User) { ... }
-  # regulate_class_connection, regulate_instance_connections and
-  # regulate_all_broadcasts can take a list of channels.
-  regulate_all_broadcasts(User, Application)
-  # regulate_broadcast takes a list of object classes which
-  # may also be channels.
-  regulate_broadcast(Todo, Message, User) { ... }
-end
-```
-#### Channels and the connection policies
-Any ruby class that has a connection policy is a Hyperloop channel. The fully scoped name of the class becomes the root of the channel name.
-The purpose of having channels is to restrict what gets broadcast when models change, therefore typically channels represent *connections* to
-+ the application, or some function within the application
-+ or some class which is *authenticated* like a User or Administrator,
-+ instances of those classes,
-+ or instances of related classes.
-So a channel that is connected to the User class would get information readable by any logged-in user, while a channel that is connected to a specific User instance would get information readable by that specific user.
-The `regulate_class_connection` takes a block that will execute in the context of the current acting_user (which may be nil), and if the block returns any truthy value, the connection will be made.
-The `regulate_instance_connections` likewise takes a block that is executed in the context of the current acting_user.  The block may do one of following:
-+ raise an error meaning the connection cannot be made,
-+ return a falsy value also meaning the connection cannot be made,
-+ return a single object meaning the connection can be made to that object,
-+ return a enumerable of objects meaning the connection can made to any member of the enumerable.
-Note that the object (or objects) returned are expected to be of the same class as the regulated policy.
-```ruby
-# Create a class connection only if the acting_user is non-nil (i.e. logged in:)
-regulate_class_connection { self }
-# Always open the connection:
-regulate_class_connection { true }
-# Which can be shortened to:
-always_allow_connection
-# Create a class level connection if the acting_user is an admin:
-regulate_class_connection { admin? }
-# Create an instance connection for the current user:
-regulate_instance_connections { self }
-# Create an instance connection for the current user if the user is an admin:
-regulate_instance_connections { self if admin? }
-# create an instance_connection to the users' group
-regulate_instance_connections { group }
-# create an instance connection for any team the user belongs to
-regulate_instance_connections { teams }
-```
-#### Class Names, Instances and IDs
-While establishing connections, classes are represented as their fully scoped name, and instances are represented as the class name plus the result of calling `id` on the instance.
-Typically connections are made to ActiveRecord models, and if those are in the `app/hyperloop/models` folder everything will work fine.
-#### Acting User
-Hyperloop 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
-  def acting_user
-    @acting_user ||= session[:current_user_id] && User.find_by_id(session[:current_user_id])
-    end
-  end
-end
-```
-#### Automatic Connection
-Connections to channels available to the current `acting_user` are automatically made on the initial page load.  This behavior can be turned off with the `auto_connect` option.
-```ruby
-class TeamPolicy
-  # Allow current users to establish connections to any teams they are
-  # members of, but disable_auto_connect
-  regulate_instance_connections(auto_connect: false) { teams }
-end
-```
-Its important to consider turning off automatic connections for cases like the above where
-the user is likely to be a member of many teams.  Typically the client application will
-want to dynamically determine which specific teams to connect to given the current state of
-the application.
-### Manually Connecting to Channels
-Normally the client will automatically connect to the available channels when a page loads, but you can also
-manually connect on the client in response to some user action like logging in, or the user deciding to
-display a specific team status on their dashboard.
-TODO check below Hyperloop.connect
-To manually connect a client use the `Hyperloop.connect` method.
-The `connect` method takes any number of arguments each of which is either a class, an object, a String or Array.
-If the argument is a class then the connection will be made to the matching class channel on the server.
-```ruby
-# connect the client to the AdminUser class channel
-Hyperloop.connect(AdminUser)
-# if the connection is successful the client will begin getting updates on the
-# AdminUser class channel
-```
-If the argument is an object then a connection will be made to the matching object on the server.
-```ruby
-# assume current_user is an instance of class User
-Hyperloop.connect(current_user)
-# current_user.id is used to establish which User instance to connect to on the
-# server
-```
-The argument can also be a string, which matches the name of a class on the server
-```ruby
-Hyperloop.connect('AdminUser')
-# same as AdminUser class
-```
-or the argument can be an array with a string and the id:
-```ruby
-Hyperloop.connect(['User', current_user.id])
-# same as saying current_user
-```
-You can make several connections at once as well:
-```ruby
-Hyperloop.connect(AdminUser, current_user)
-```
-Finally falsy values are ignored.
-You can also send `connect` directly to ActiveRecord models:
-```ruby
-AdminUser.connect!    # same as Hyperloop.connect(AdminUser)
-current_user.connect! # same as Hyperloop.connect(current_user)
-```
-#### Connection Sequence Summary
-For class connections:
-1. The client calls `Hyperloop.connect`.
-2. Hyperloop sends the channel name to the server.
-3. Hyperloop has its own controller which will determine the `acting_user`,
-4. and call the channel's `regulate_class_connection` method.
-5. If `regulate_class_connection` returns a truthy value then the connection is made,
-6. otherwise a 500 error is returned.
-For instance connections:
-1. The process is the same but the channel name and id are sent to the server.
-2. The Hyperloop controller will do a `find` of the id passed to get the instance,
-3. and if successful `regulate_instance_connections` is called,
-4. which must return an either the same instance, or an enumerable with that instance as a member.
-5. Otherwise a 500 error is returned.
-Note that the same sequence is used for auto connections and manually invoked connections.
-#### Disconnecting
-TODO check Hyperloop.disconnect(
-Calling `Hyperloop.disconnect(channel)` or `channel.disconnect!` will disconnect from the channel.
-#### Broadcasting and Broadcast Policies
-Broadcast policies can be defined for channels using the `regulate_all_broadcasts` method, and for individual objects (typically ActiveRecord models) using the `regulate_broadcast` method.  A `regulate_all_broadcasts` policy is essentially a `regulate_broadcast` that will be run for every record that changes in the system.
-After an ActiveRecord Model change is committed, all active class channels run their channel broadcast policies, and then the instance broadcast policy associated with the changing Model is run.  So for any change there may be multiple channel broadcast policies involved, but only one (at most) regulate_broadcast.
-The result is that each channel may get a filtered copy of the record which is broadcast on that channel.
-The purpose of the policies then is to determine which channel sees what.  Each broadcast policy receives the instance of the policy which responds to the following methods
-+ `send_all`: send all the attributes of the record.
-+ `send_only`: send only the listed attributes of the record.
-+ `send_all_but`: send all the attributes except the ones listed.
-The result of the `send...` method is then directed to the set of channels using the `to` method:
-```ruby
-policy.send_all_but(:password).to(AdminUser)
-```
-Within channel broadcast policies the channel is assumed to be the channel in question:
-```ruby
-class AdminUserPolicy
-  regulate_all_broadcasts do |policy|
-    policy.send_all_but(:password) #.to(AdminUser) is not needed.
-  end
-end
-```
-The `to` method can take any number of arguments:
-+ a class naming a channel,
-+ an object that is instance channel,
-+ an ActiveRecord collection,
-+ any falsy value which will be ignored,
-+ or an array that will be flattened and merged with the other arguments.
-The broadcast policy executes in the context of the model that has just changed, so the policy can use all the methods of that model, especially relationships.  For example:
-```ruby
-class Message < ActiveRecord::Base
-  belongs_to :sender, class: "User"
-  belongs_to :recipient, class: "User"
-end
-class MessagePolicy
-  regulate_broadcast do |policy|
-    # send all attributes to both the sender, and recipient User instance channels
-    policy.send_all.to(sender, recipient)
-    # send all attributes to intersection
-    policy.send_all.to(sender.teams.merge(recipient.teams)) unless private?
-  end
-end
-```
-It is possible that the same channel may be sent a record from different policies, in this case the minimum set of attributes will be sent regardless of the order of the send operations.  For example:
-```ruby
-policy.send_all_but(:password).to(MyChannel)
-# ... later
-policy.send_all.to(MyChannel)
-# MyChannel gets everything but the password
-```
-or even
-```ruby
-policy.send_only(:foo, :bar).to(MyChannel)
-policy.send_only(:baz).to(MyChannel)
-# MyChannel gets nothing
-```
-Keep in mind that the broadcast policies are sent a copy of the policy object so you can use helper methods in your policies. Also you can add policy specific methods to your models using
-`class_eval` thus keeping policy logic out of your models.
-So we could for example we can rewrite the above MessagePolicy like this:
-```ruby
-class MessagePolicy
-  Message.class_eval do
-    scope :teams_for_policy, -> () { sender.teams.merge(recipient.teams) }
-  end
-  def teams  # the obj method returns the instance being regulated
-    [obj.sender, obj.recipient, !obj.private? && obj.teams_for_policy]
-  end
-  regulate_broadcast { |policy| policy.send_all.to(policy.teams) }
-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 Hyperloop.
-```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 Hyperloop::PolicyMethods module) define the following class methods:
-+ `regulate_connection`
-+ `regulate_all_broadcasts`
-+ `regulate_broadcast`
-As well as the following instance methods:
-+ `send_all`
-+ `send_all_but`
-+ `send_only`
-+ `obj`
-TODO check `synchromesh_internal_policy_object` new name
-To avoid name space conflicts with your classes, Hyperloop policy classes (and the Hyperloop::PolicyMethods module) maintain class and instance `attr_accessor`s named `synchromesh_internal_policy_object`.   The above methods call methods of the same name in the appropriate internal policy object.
-You may thus freely redefine of the class and instance methods if you have name space conflicts
-```ruby
-class ProductionCenterPolicy < MyPolicyClass
-  # MyPolicyClass already defines our version of obj
-  # so we will call it 'this'
-  def this
-    synchromesh_internal_policy_object.obj
-  end
-  ...
-end
-```