Module: Shamu::Services::ActiveRecordCrud

Extended by:
ActiveSupport::Concern
Defined in:
lib/shamu/services/active_record_crud.rb

Overview

Adds standard CRUD builders to an ActiveRecordService to reduce boilerplate for common methods.

Examples:


class UsersService < Shamu::Services::Service
  include Shamu::Services::Crud

  # Define the resource that the service will manage
  resource UserEntity, Models::User

  # Define finder methods #find, #list and #lookup using the given
  # default scope.
  finders Models::User.active

  # Define change methods
  create
  update

  # Common update/change behavior for #create and #update
  change do |request, model|
    model.last_updated_at = Time.now
  end

  # Standard destroy method
  destroy

  # Build the entity class from the given record.
  build_entities do |records|
    records.map do |record|
      parent = lookup_association( record.parent_id, self ) do
                 records.pluck( :parent_id )
               end

      scorpion.fetch UserEntity, { parent: parent }, {}
    end
  end
end

Constant Summary collapse

DSL_METHODS =

Known DSL methods defined by Shamu::Services::ActiveRecordCrud.

%i( create update change destroy find list lookup finders ).freeze

Class Method Summary collapse

Instance Method Summary collapse

Class Method Details

.apply_changes {|request, record| ... }

This method returns an undefined value.

Define a private method apply_changes on the service used by the create and change defined methods to apply changes in a Request to the model.

Yields:

  • (request, record) —

    a block that applies changes in the request to the record.

Yield Parameters:

  • request (Request) —

    the Request containing all the changes that should be applied to the record.

  • record (ActiveRecord::Base) —

    the record to be updated.

Yield Returns:

  • (void) 


227
228
229
230
 
# File 'lib/shamu/services/active_record_crud.rb', line 227

def apply_changes( &block )
  define_method :apply_changes, &block
  private :apply_changes
end

.build_entities {|records| ... }

This method returns an undefined value.

Define a private build_entities( records ) method that constructs an Entities::Entity for each of the given records.

If no block is given, creates a simple builder that simply constructs an instance of the entity_class passing record: record to the initializer.

See Service#lookup_association for details on association caching.

Yields:

  • (records)

Yield Parameters:

  • records (ActiveRecord::Relation) —

    to be mapped to entities.

Yield Returns:



344
345
346
347
348
349
350
351
352
353
354
355
356
357
 
# File 'lib/shamu/services/active_record_crud.rb', line 344

def build_entities( &block )
  if block_given?
    define_method :build_entities, &block
  else
    define_method :build_entities do |records|
      records.map do |record|
        entity = scorpion.fetch( entity_class, { record: record }, {} )
        authorize! :read, entity
      end
    end
  end

  private :build_entities
end

.change(method = :update) {|request, record| ... } ⇒ Result, void

Define an change method on the service that takes the id of the resource to modify and a corresponding Request parameter.

See apply_changes for details.

Yields:

  • (request, record) —

    a block that applies changes in the request to the record.

Yield Parameters:

  • request (Request) —

    the Request containing all the changes that should be applied to the record.

  • record (ActiveRecord::Base) —

    the record to be updated.

Returns:

  • (Result) —

    the result of the request.

  • (void) 


176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
 
# File 'lib/shamu/services/active_record_crud.rb', line 176

def change( method = :update, &block )
  define_method method do |id, params = nil|
    klass = request_class( method )

    id, params = id.id, id if id.is_a?( klass ) && !params

    with_request params, klass do |request|
      record = model_class.find( id.to_model_id )
      authorize! method, build_entity( record ), request

      request.apply_to( record )

      if block
        yield( request, record )
      elsif respond_to? :apply_changes
        apply_changes( request, record )
      end

      next record unless record.save
      build_entity record
    end
  end
end

.create {|request, record| ... }

This method returns an undefined value.

Define a #create method on the service that takes a single Request parameter.

See apply_changes for details.

Yields:

  • (request, record) —

    a block that applies changes in the request to the record.

Yield Parameters:

  • request (Request) —

    the Request containing all the changes that should be applied to the record.

  • record (ActiveRecord::Base) —

    the record to be updated.



148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
 
# File 'lib/shamu/services/active_record_crud.rb', line 148

def create( &block )
  define_method :create do |params = nil|
    with_request params, request_class( :create ) do |request|
      authorize! :create, entity_class, request

      record = request.apply_to( model_class.new )
      if block
        yield( request, record )
      elsif respond_to? :apply_changes
        apply_changes( request, record )
      end

      next record unless record.save
      build_entity record
    end
  end
end

.destroy(default_scope = model_class.all)

This method returns an undefined value.

Define a destroy( id ) method that takes an Entities::Entity Entities::Entity#id and destroys the resource.

Parameters:

  • default_scope (ActiveRecord::Relation) (defaults to: model_class.all) —

    to use when finding records.



320
321
322
323
324
325
326
327
328
 
# File 'lib/shamu/services/active_record_crud.rb', line 320

def destroy( default_scope = model_class.all )
  define_method :destroy do |id|
    wrap_not_found do
      record = default_scope.find( id.to_model_id )
      authorize! :destroy, build_entity( record )
      record.destroy
    end
  end
end

.entity_class ⇒ Class

The Entities::Entity class that the service will return from it's methods.

Returns:

  • (Class) —

    the Entities::Entity class that the service will return from it's methods.



131
132
133
 
# File 'lib/shamu/services/active_record_crud.rb', line 131

def entity_class
  resource_not_configured
end

.find(default_scope = model_class.all) {|id| ... }

This method returns an undefined value.

Define a find( id ) method on the service that returns the entity with the given id if found or raises a NotFoundError if the entity does not exist.

Parameters:

  • default_scope (ActiveRecord::Relation) (defaults to: model_class.all) —

    to use when finding records.

Yields:

  • (id)

Yield Returns:

  • (ActiveRecord::Base) —

    the found record.



255
256
257
258
259
260
261
262
263
264
265
266
267
268
 
# File 'lib/shamu/services/active_record_crud.rb', line 255

def find( default_scope = model_class.all, &block )
  if block_given?
    define_method :find do |id|
      wrap_not_found do
        record = yield( id )
        authorize! :read, build_entity( record )
      end
    end
  else
    define_method :find do |id|
      authorize! :read, find_by_lookup( id )
    end
  end
end

.finders(default_scope = model_class.all, only: nil, except: nil)

This method returns an undefined value.

Define the standard finder methods find, lookup and list.

Parameters:

  • default_scope (ActiveRecord::Relation) (defaults to: model_class.all) —

    to use when finding records.



237
238
239
240
241
242
243
244
 
# File 'lib/shamu/services/active_record_crud.rb', line 237

def finders( default_scope = model_class.all, only: nil, except: nil )
  methods = Array( only || [ :find, :lookup, :list ] )
  methods -= Array( except ) if except

  methods.each do |method|
    send method, default_scope
  end
end

.list(default_scope = model_class.all) {|scope| ... }

This method returns an undefined value.

Define a list( params = nil ) method that takes a Entities::ListScope and returns all the entities selected by that scope.

Parameters:

  • default_scope (ActiveRecord::Relation) (defaults to: model_class.all) —

    to use when finding records.

Yields:

  • (scope)

Yield Parameters:

  • scope (ListScope) —

    to apply.

Yield Returns:

  • (ActiveRecord::Relation) —

    records matching the given scope.



302
303
304
305
306
307
308
309
310
311
312
 
# File 'lib/shamu/services/active_record_crud.rb', line 302

def list( default_scope = model_class.all, &block )
  define_method :list do |params = nil|
    list_scope = Entities::ListScope.for( entity_class ).coerce( params )
    authorize! :list, entity_class, list_scope

    records    = block_given? ? yield( scope ) : scope_relation( default_scope, list_scope )
    records    = authorize_relation( :read, records, list_scope )

    entity_list records
  end
end

.lookup(default_scope = model_class.all) {|uncached_ids| ... }

This method returns an undefined value.

Define a lookup( *ids ) method that takes a list of entity ids to find. Calls #build_entities to map all found records to entities, or constructs a Entities::NullEntity for ids that were not found.

Parameters:

  • default_scope (ActiveRecord::Relation) (defaults to: model_class.all) —

    to use when finding records.

Yields:

  • (uncached_ids)

Yield Parameters:

  • ids (Array<Object>) —

    that need to be fetched from the underlying resource.

Yield Returns:

  • (ActiveRecord::Relation) —

    records for ids found in the underlying resource.



282
283
284
285
286
287
288
289
290
 
# File 'lib/shamu/services/active_record_crud.rb', line 282

def lookup( default_scope = model_class.all, &block )
  define_method :lookup do |*ids|
    cached_lookup( ids ) do |uncached_ids|
      records = block_given? ? yield( uncached_ids ) : default_scope.where( id: uncached_ids )
      records = authorize_relation :read, records
      entity_lookup_list records, uncached_ids, entity_class.null_entity
    end
  end
end

.model_class ⇒ Class

Returns the ActiveRecord::Base class used to store the data managed by the service.

Returns:

  • (Class) —

    the ActiveRecord::Base class used to store the data managed by the service.



137
138
139
 
# File 'lib/shamu/services/active_record_crud.rb', line 137

def model_class
  resource_not_configured
end

.resource(entity_class, model_class, methods: nil) {|records| ... }

This method returns an undefined value.

Declare the entity and resource classes used by the service.

Creates instance and class level methods entity_class and model_class.

See build_entities for build_entities block details.

Parameters:

  • entity_class (Class) —

    the Entities::Entity class that will be returned by finders and mutator methods.

  • model_class (Class) —

    the ActiveRecord::Base model

  • methods (Array<Symbol>) (defaults to: nil) —

    the DSL methods to include (eg :create, :update, :find, etc.)

Yields:

  • (records)

Yield Parameters:

  • records (ActiveRecord::Relation) —

    to be mapped to an entity.

Yield Returns:



115
116
117
118
119
120
121
122
123
124
125
126
127
 
# File 'lib/shamu/services/active_record_crud.rb', line 115

def resource( entity_class, model_class, methods: nil, &block )
  private define_method( :entity_class )   { entity_class }
  define_singleton_method( :entity_class ) { entity_class }

  private define_method( :model_class )    { model_class }
  define_singleton_method( :model_class )  { model_class }

  ( Array( methods ) & DSL_METHODS ).each do |method|
    send method
  end

  build_entities( &block )
end

.update {|request, record| ... }

This method returns an undefined value.

Define an update method on the service that takes the id of the resource to update and a Request parameter. After applying the changes the record is persisted and the updated entity result is returned.

See apply_changes for details.

Yields:

  • (request, record) —

    a block that applies changes in the request to the record.

Yield Parameters:

  • request (Request) —

    the Request containing all the changes that should be applied to the record.

  • record (ActiveRecord::Base) —

    the record to be updated.



212
213
214
 
# File 'lib/shamu/services/active_record_crud.rb', line 212

def update( &block )
  change :update, &block
end

Instance Method Details

#authorize!(method, resource, additional_context = nil) ⇒ resource

Hook to allow a security module to authorize actions taken by the standard CRUD methods. If authorization is not granted, then an exception should be raised. Default behavior is a no-op.

Parameters:

  • method (Symbol) —

    on the service that was invoked.

  • resource (Entities::Entity, Class, Symbol) —

    the entity, class or arbitrary symbol describing the resource that the service method applies to.

  • additional_context (Object) (defaults to: nil) —

    that the security module might consider when authorizing the transaction.

Returns:

  • (resource) —

    the resource given to authorize.



76
77
78
 
# File 'lib/shamu/services/active_record_crud.rb', line 76

def authorize!( method, resource, additional_context = nil )
  resource
end

#authorize_relation(method, relation, additional_context = nil) ⇒ relation

Hook to allow a security module to pre-filter ActiveRecord queries for the standard crud methods. Default behavior is a no-op.

Parameters:

  • method (Symbol) —

    on the service that was invoked.

  • relation (ActiveRecord::Relation) —

    to filter

  • additional_context (Object) (defaults to: nil) —

    that the security module might consider when authorizing the transaction.

Returns:

  • (relation) —

    the filtered relation.



91
92
93
 
# File 'lib/shamu/services/active_record_crud.rb', line 91

def authorize_relation( method, relation, additional_context = nil )
  relation
end