hyperstack-org
expose_as_operations method
This is a nice standalone module that adds two class level methods to ActiveRecord Models, that will expose server side methods to the client as operations.
Unlike server_methods, methods exposed using expose_as_operation run as server operations. The method is asynchronously executed on the server, and the client gets a promise that resolves when the method completes.
This is much more useful than server_methods if the you are trying to trigger some server side operation in an event handler. The downside is that unlike server_methods there will be no automatic client re-render when the operation returns.
So the rule is: If its returning data for the user - use a server_method. If its triggering an operation on the server then expose it as an operation.
Add the ExposeAsOperation module to hyperstack/models, and then include the module in ApplicationRecord:
# hyperstack/models/application_record.rb
class ApplicationRecord < ActiveRecord::Base
...
include ExposeAsOperations
...
end
Now to expose a method as an operation say this in your model defintion:
# hyperstack/models/my_model.rb
class MyModel < ApplicationRecord
def foo(value)
... do something on the server ...
end
...
expose_as_operation(:foo)
end
somewhere on the client (usually in an event handler) you can say
my_model_instance.foo(12)
Note that foo returns a promise so you can add a .then clause to do anything you need to when the operation completes:
my_model_instance.foo(12).then { |ret_value| mutate @foo_ret_value = ret_value }
The expose_as_operation method can take a block that is used to protect the method from illegal access. Like other policy regulations, the block is executed with self equal to the model instance, and the acting_user attribute of self set to the current acting user, so you can say for example:
expose_as_operation(:admins_only) { acting_user.admin? }
Returning a falsy value, or raising an error will abort the method call, and return an access violation error to the client.
You can expose multiple methods at once:
expose_as_operations(:foo, :bar, :baz) { ... common regulation ... }
Typically the exposed methods will either be in a separate file visible on the server, or will be surrounded by an
unless RUBY_ENGINE == 'opal' guard.
class MyModel < ApplicationRecord
include MyModelServerDefinitions unless RUBY_ENGINE == 'opal' # defines meth1, and meth2 plus others...
expose_as_operation(:meth1, :meth2)
end
We may eventually include this code in Hyperstack, but for now its easy enough to add the file to your models directory:
# hyperstack/models/expose_as_operations.rb
# frozen_string_literal: true
# ExposeAsOperations adds the following methods to ActiveRecord models
# expose_as_operations(list of method names) { security block }
# each of the method names will now be callable from the client
# as an ServerOp. In otherwords on the client the method will
# return a promise that will resolve (or reject) when the method
# completes execution on the server.
#
# The optional security block will be called before the method is invoked
# and is passed the method name, and the arguments. Within the block
# self is the active record instance, and will have the current value
# of acting_user. If the security block returns a falsy value or
# raises an error, the operation will not be executed, and
# the operation will fail with a Hyperstack::AccessViolation error.
#
# For example
# expose_as_operations(:set_brightness, :toggle_switch) do
# users.includes? acting_user
# end
#
# For readability you can also use expose_as_operation for a single method.
#
# Caveat: The record must be saved. I.e. you cannot execute the methods
# from the client on unsaved records.
#
module ExposeAsOperations
def self.included(base)
base.extend ClassMethods
end
# each class calling exposing_as_operation will create its subclass
# of the Base operation. Each subclass of Base has its own internal
# list of exposed methods, with an associated security block.
# The Base operation simply validates the operation using the security
# block, and then calls the method on the parent class.
class Base < Hyperstack::ServerOp
param :acting_user, nils: true
param :id
param :method
param :args
unless RUBY_ENGINE == 'opal'
# Abort with a nice message unless we can find the record using the id.
validate :insure_record_exists
# Call the security block to validate the method is callable,
validate :with_security_block
# and convert any failures above to AccessViolations.
failed { raise Hyperstack::AccessViolation }
# If we get here then we have a valid record, and we are allowed to call
# the method. Any errors in the method will get sent back to the client.
step { @record.send(params.method, *params.args) }
def insure_record_exists
@record =
self.class.parent.find_by(self.class.parent.primary_key => params.id)
return true if @record
add_error(
:id, :not_found, "#{self.class.parent} id: #{params.id} not found."
)
# abort so we skip the conversion of failures to access violations.
abort!
end
def with_security_block
@record.acting_user = params.acting_user
@record.instance_exec(
params.method.to_sym,
*params.args,
&self.class.security_blocks[params.method.to_sym]
)
end
# list of security blocks indexed by the method name
def self.security_blocks
@security_blocks ||= {}
end
end
end
# define the two class methods
module ClassMethods
def expose_as_operations(*methods, &security_block)
methods.each { |method| add_security_block(method, security_block) }
end
alias expose_as_operation expose_as_operations
private
# the runner method insures that each class that uses expose_as_operations
# has its own subclass of the Base operation, which we call MethodRunner
def runner
return self::MethodRunner if defined? self::MethodRunner
const_set 'MethodRunner', Class.new(Base)
end
if RUBY_ENGINE == 'opal'
# on the client we dont really add a security block, but instead
# just make sure that the MethodRunner API is defined and then
# define the method. The method first makes sure that the id of
# model is loaded, and then calls the MethodRunner's run method
def add_security_block(method, _security_block)
runner # insure runner is defined
define_method(method) do |*args|
Hyperstack::Model.load { id }.then do |id|
self.class::MethodRunner.run(id: id, method: method, args: args)
end
end
end
else
# on the server we add the security block for the method. If no
# security block is provided we create a proc that will return true.
def add_security_block(method, security_block)
runner.security_blocks[method] = security_block || ->(*) { true }
end
end
end
end
