document error message meanings

[catmando]

Hyperloop gems may need to raise errors server side due to client problems. These errors are listed here and should be documented some place:

To aid in debugging and logging all errors can be tracked by defining this method:

module Hyperloop
  def self.on_error(err, message, details)
     # add application specific logging or debugger breakpoint here
   end
end

Some of the issues can arise because of problems with eager loading in production. For security reasons Hyperloop will not dynamically load constants in production, but assumes that eager loading has already insured all ActiveRecord models and ServerOps are defined. A good article on eager loading is here.

• :not_a_channel, "#{channel[0]} is not regulated channel class"
  attempt has been made to connect via channel[0], but there is no channel connection regulation for that class

• :non_ar_class, "#{str} is not a subclass of ActiveRecord::Base"
  the client is attempting to treat str as an AR model, but while the class is defined, it is not a subclass of ActiveRecord::Base

• :non_ar_class, "#{str} is either not defined or is not a subclass of ActiveRecord::Base"
  similar to above, but occurs if eager loading is enabled. str may either not be a subclass of ActiveRecord::Base or it may not be loaded. For example in production str may have been left out of the eager loading paths, and so is not be loaded.

• :undefined_const, "#{str} is not a loaded constant"
str be the name of a an Active Record model in the hyperloop/models folder

• :illegal_remote_op_call, "Operation: #{operation} (in production)"
  Attempt is being made to run operation remotely, but operation is not a subclass of Hyperloop::ServerOp . This occurs if eager loading is enabled. operation may either not be a subclass of Hyperloop::ServerOp or it may not be loaded. For example in production operation may have been left out of the eager loading paths, and so is not be loaded.

• :illegal_remote_op_call, "Operation: #{operation} (const not found)"
  Similar to the above, but occurs in development (non-eager loading). There is no constant named operation.

• :illegal_remote_op_call, "Operation: #{operation} (not a ServerOp subclass)"
  Similar to the above, but occurs in development (non-eager loading). The constant named operation is not a subclass of ServerOp.

• :scoped_permission_not_granted, "Last relation: #{relation}, acting_user: #{acting_user}" A scope or relationship expression did not grant permission for acting_userto access the resulting query. In Rails you can chain scopes and relationships together. When the client asks for a set of records via a scope (includingall, or unscoped) or a has_many` relationship, one of the scopes or relationships in the chain has to explicitly give permission (via a regulation) to return the data. If none of the scopes or relationships in the chain explicitly give permission then the whole chain will fail and raise this error.

• :scoped_denied, "#{relation} regulation denies scope access. Called from #{location)}"
  A scope or relationship regulation explicitly denied access to the acting_user. location gives the source position of the regulation.

• :crud_access_violation, "for #{record} - #{operation}(#{args}) acting_user: #{user}"
  The client attempted an illegal create, read, update or destroy operation on record. Create, read, update and destroy have explicity policies for each model. Read permissions are defined by the broadcast policies. For example if a record will broadcast (push) changes to an attribute, then the client may also directly read that attribute.