acfs 1.3.3 → 1.6.0

data/lib/acfs/resource/operational.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+class Acfs::Resource
+  # @api private
+  #
+  # Provide methods for creating and processing CRUD operations and
+  # handling responses. That includes error handling as well as
+  # handling stubbed resources.
+  #
+  # Should only be used internal.
+  #
+  module Operational
+    extend ActiveSupport::Concern
+
+    def operation(*args, **kwargs, &block)
+      self.class.operation(*args, **kwargs, &block)
+    end
+
+    module ClassMethods
+      # Invoke CRUD operation.
+      def operation(action, **opts, &block)
+        Acfs.runner.process ::Acfs::Operation.new(self, action, **opts, &block)
+      end
+    end
+  end
+end

data/lib/acfs/resource/persistence.rb

@@ -0,0 +1,258 @@
+# frozen_string_literal: true
+
+class Acfs::Resource
+  #
+  # Allow to track the persistence state of a model.
+  #
+  module Persistence
+    extend ActiveSupport::Concern
+
+    # @api public
+    #
+    # Check if the model is persisted. A model is persisted if
+    # it is saved after being created
+    #
+    # @example Newly created resource:
+    #   user = User.new name: "John"
+    #   user.persisted? # => false
+    #   user.save
+    #   user.persisted? # => true
+    #
+    # @example Modified resource:
+    #   user2 = User.find 5
+    #   user2.persisted? # => true
+    #   user2.name = 'Amy'
+    #   user2.persisted? # => true
+    #   user2.save
+    #   user2.persisted? # => true
+    #
+    # @return [Boolean] True if resource has been saved
+    #
+    def persisted?
+      !new?
+    end
+
+    # @api public
+    #
+    # Return true if model is a new record and was not saved yet.
+    #
+    # @return [Boolean] True if resource is newly created,
+    #   false otherwise.
+    #
+    def new?
+      !loaded?
+    end
+    alias new_record? new?
+
+    # @api public
+    #
+    # Saves the resource.
+    #
+    # It will PUT to the service to update the resource or send
+    # a POST to create a new one if the resource is new.
+    #
+    # Saving a resource is a synchronous operation.
+    #
+    # @return [Boolean] True if save operation was successful,
+    #   false otherwise.
+    # @see #save! See {#save!} for available options.
+    #
+    def save(**opts)
+      save!(**opts)
+      true
+    rescue Acfs::Error
+      false
+    end
+
+    # @api public
+    #
+    # Saves the resource. Raises an error if something happens.
+    #
+    # Saving a resource is a synchronous operation.
+    #
+    # @param opts [Hash] Hash with additional options.
+    # @option opts [Hash] :data Data to send to remote service.
+    #   Default will be resource attributes.
+    #
+    # @raise [Acfs::InvalidResource]
+    #   If remote services respond with 422 response. Will fill
+    #   errors with data from response
+    # @raise [Acfs::ErroneousResponse]
+    #   If remote service respond with not successful response.
+    #
+    # @see #save
+    #
+    def save!(**opts)
+      opts[:data] = attributes unless opts[:data]
+
+      operation((new? ? :create : :update), **opts) do |data|
+        update_with data
+      end
+    rescue ::Acfs::InvalidResource => e
+      self.remote_errors = e.errors
+      raise e
+    end
+
+    # @api public
+    #
+    # Update attributes with given data and save resource.
+    #
+    # Saving a resource is a synchronous operation.
+    #
+    # @param attrs [Hash] Hash with attributes to write.
+    # @param opts [Hash] Options passed to `save`.
+    #
+    # @return [Boolean]
+    #   True if save operation was successful, false otherwise.
+    #
+    # @see #save
+    # @see #attributes=
+    # @see #update_attributes!
+    #
+    def update_attributes(attrs, **opts)
+      check_loaded!(**opts)
+
+      self.attributes = attrs
+      save(**opts)
+    end
+
+    # @api public
+    #
+    # Update attributes with given data and save resource.
+    #
+    # Saving a resource is a synchronous operation.
+    #
+    # @param [Hash] attrs Hash with attributes to write.
+    # @param [Hash] opts Options passed to `save!`.
+    #
+    # @raise [Acfs::InvalidResource]
+    #   If remote services respond with 422 response. Will fill
+    #   errors with data from response
+    #
+    # @raise [Acfs::ErroneousResponse]
+    #   If remote service respond with not successful response.
+    #
+    # @see #save!
+    # @see #attributes=
+    # @see #update_attributes
+    #
+    def update_attributes!(attrs, **opts)
+      check_loaded! opts
+
+      self.attributes = attrs
+      save!(**opts)
+    end
+
+    # @api public
+    #
+    # Destroy resource by sending a DELETE request.
+    #
+    # Deleting a resource is a synchronous operation.
+    #
+    # @return [Boolean]
+    # @see #delete!
+    #
+    def delete(**opts)
+      delete!(**opts)
+      true
+    rescue Acfs::Error
+      false
+    end
+
+    # @api public
+    #
+    # Destroy resource by sending a DELETE request.
+    # Will raise an error in case something goes wrong.
+    #
+    # Deleting a resource is a synchronous operation.
+
+    # @raise [Acfs::ErroneousResponse]
+    #   If remote service respond with not successful response.
+    #
+    # @return [undefined]
+    # @see #delete
+    #
+    def delete!(**opts)
+      opts[:params] ||= {}
+      opts[:params] = attributes_for_url(:delete).merge opts[:params]
+
+      operation(:delete, **opts) do |data|
+        update_with data
+        freeze
+      end
+    end
+
+    private
+
+    def attributes_for_url(action)
+      arguments_for_url = self.class.location(action: action).arguments
+      attributes.slice(*arguments_for_url)
+    end
+
+    module ClassMethods
+      # @api public
+      #
+      # Create a new resource sending given data. If resource cannot be
+      # created an error will be thrown.
+      #
+      # Saving a resource is a synchronous operation.
+      #
+      # @param data [Hash{Symbol, String => Object}]
+      #   Data to send in create request.
+      #
+      # @return [self] Newly resource object.
+      #
+      # @raise [Acfs::InvalidResource]
+      #   If remote services respond with 422 response. Will fill
+      #   errors with data from response
+      #
+      # @raise [Acfs::ErroneousResponse]
+      #   If remote service respond with not successful response.
+      #
+      # @see Acfs::Model::Persistence#save! Available options. `:data`
+      #   will be overridden with provided data hash.
+      # @see #create
+      #
+      def create!(data, _opts = {})
+        new(data).tap(&:save!)
+      end
+
+      # @api public
+      #
+      # Create a new resource sending given data. If resource cannot be
+      # create model will be returned and error hash contains response
+      # errors if available.
+      #
+      # Saving a resource is a synchronous operation.
+      #
+      # @param data [Hash{Symbol, String => Object}]
+      #   Data to send in create request.
+      #
+      # @return [self] Newly resource object.
+      #
+      # @raise [Acfs::ErroneousResponse]
+      #   If remote service respond with not successful response.
+      #
+      # @see Acfs::Model::Persistence#save! Available options. `:data`
+      #   will be overridden with provided data hash.
+      # @see #create!
+      #
+      def create(data, _opts = {})
+        model = new data
+        model.save
+        model
+      end
+    end
+
+    def update_with(data)
+      self.attributes = data
+      loaded!
+    end
+
+    def check_loaded!(opts = {})
+      return if loaded? || opts[:force]
+
+      raise ::Acfs::ResourceNotLoaded.new resource: self
+    end
+  end
+end

data/lib/acfs/resource/query_methods.rb

@@ -0,0 +1,266 @@
+# frozen_string_literal: true
+
+class Acfs::Resource
+  # Methods providing the query interface for finding resouces.
+  #
+  # @example
+  #   class MyUser < Acfs::Resource
+  #   end
+  #
+  #   MyUser.find(5)               # Find single resource
+  #   MyUser.all                   # Full or partial collection of
+  #                                # resources
+  #   Comment.where(user: user.id) # Collection with additional parameter
+  #                                # to filter resources
+  #
+  module QueryMethods
+    extend ActiveSupport::Concern
+
+    module ClassMethods
+      # @api public
+      #
+      # @overload find(id, opts = {})
+      #   Find a single resource by given ID.
+      #
+      #   @example
+      #     user = User.find(5) # Will query `http://base.url/users/5`
+      #
+      #   @param id [Fixnum] Resource IDs to fetch from remote service.
+      #   @param params [Hash] Additional options.
+      #   @option opts [Hash] :params Additional parameters added to
+      #     request. `:id` will be overridden with given ID.
+      #
+      #   @yield [resource] Callback block to be executed after resource
+      #     was fetched successfully.
+      #   @yieldparam resource [self] Fetched resources.
+      #
+      #   @return [self] Resource object if only one ID was given.
+      #
+      # @overload find(ids, opts = {})
+      #   Load collection of specified resources by given IDs.
+      #
+      #   @example
+      #     User.find([1, 2, 5]) # Will return collection and will request
+      #                          # `http://base.url/users/1`,
+      #                          # `http://base.url/users/2`
+      #                          # and `http://base.url/users/5` parallel
+      #
+      #   @param ids [Array<Integer>] List of resource IDs.
+      #   @param opts [Hash] Additional options.
+      #   @option opts [Hash] :params Additional parameters added to
+      #     request. `:id` will be overridden with individual resource ID.
+      #
+      #   @yield [collection] Callback block to be executed after collection
+      #     was fetched successfully.
+      #   @yieldparam resource [Collection] Collection with fetched resources.
+      #
+      #   @return [Collection] Collection of requested resources.
+      #
+      def find(id_or_ids, **opts, &block)
+        if id_or_ids.respond_to? :each
+          find_multiple id_or_ids, opts, &block
+        else
+          find_single id_or_ids, opts, &block
+        end
+      end
+
+      # @api public
+      #
+      # Try to load all resources.
+      #
+      # @param params [Hash] Request parameters that will be send to
+      #   remote service.
+      #
+      # @yield [collection] Callback block to be executed when resource
+      #   collection was loaded successfully.
+      # @yieldparam collection [Collection] Collection of fetched resources.
+      #
+      # @return [Collection] Collection of requested resources.
+      #
+      def all(params = {}, opts = {}, &block)
+        collection = ::Acfs::Collection.new self
+        collection.__callbacks__ << block if block
+
+        operation(:list, **opts, params: params) do |data, response|
+          data.each {|obj| collection << create_resource(obj) }
+          collection.process_response response
+          collection.loaded!
+          collection.__invoke__
+        end
+
+        collection
+      end
+      alias where all
+
+      # @api public
+      #
+      # Try to load first resource. Return nil if no object can be loaded.
+      #
+      # @param params [Hash] Request parameters that will be send
+      #   to remote service.
+      #
+      # @yield [resource] Callback block to be executed after
+      #   resource was fetched (even if nil).
+      # @yieldparam resource [self] Fetched resource, nil
+      #   if empty list is returned
+      #
+      # @return [self] Resource object, nil if empty list is returned
+      #
+      def find_by(params, &block)
+        Acfs::Util::ResourceDelegator.new(new).tap do |m|
+          m.__callbacks__ << block unless block.nil?
+          operation(:list, params: params) do |data|
+            if data.empty?
+              m.__setobj__ nil
+            else
+              m.__setobj__ create_resource(data.first, origin: m.__getobj__)
+            end
+            m.__invoke__
+          end
+        end
+      end
+
+      # @api public
+      #
+      # Try to load first resource. Raise Acfs::ResourceNotFound
+      # exception if no object can be loaded.
+      #
+      # @param params [Hash] Request parameters that will be send
+      #   to remote service.
+      #
+      # @yield [resource] Callback block to be executed after
+      #   resource was fetched successfully.
+      # @yieldparam resource [self] Fetched resource, nil
+      #   if empty list is returned
+      #
+      # @return [self] Resource object, nil if empty list is returned
+      #
+      def find_by!(params, &block)
+        find_by params do |m|
+          if m.nil?
+            raise Acfs::ResourceNotFound.new message: 'Received erroneous ' \
+              "response: no `#{name}` with params #{params} found"
+          end
+          block&.call m
+        end
+      end
+
+      # @api public
+      #
+      # Iterates over all pages returned by index action.
+      #
+      # Server must return a paginated resource.
+      #
+      # @example
+      #   User.each_page do |page|
+      #     p page.size
+      #   end
+      #   Acfs.run
+      #   # => 50
+      #   # => 50
+      #   # => 42
+      #
+      # @param opts [Hash] Options passed to {#where}.
+      #
+      # @yield [collection] Callback that will be invoked for each page.
+      # @yieldparam collection [Collection] Paginated collection.
+      #
+      # @return [Collection] First page.
+      #
+      def each_page(opts = {})
+        cb = proc do |collection|
+          yield collection
+          collection.next_page(&cb)
+        end
+        where opts, &cb
+      end
+
+      # @api public
+      #
+      # Iterates over all items of all pages returned by index action.
+      #
+      # Server must return a paginated resource.
+      #
+      # @example
+      #   index = 0
+      #   User.each_item do |page|
+      #     index += 1
+      #   end
+      #   Acfs.run
+      #   print index
+      #   # => 142
+      #
+      # @param opts [Hash] Options passed to {#each_page}.
+      #
+      # @yield [item] Callback that will be invoked for each item.
+      # @yieldparam item [self] Resource.
+      # @yieldparam collection [Acfs::Collection] Collection.
+      #
+      def each_item(opts = {})
+        each_page(opts) do |collection|
+          collection.each do |item|
+            yield item, collection
+          end
+        end
+      end
+
+      private
+
+      def find_single(id, opts, &block)
+        model = Acfs::Util::ResourceDelegator.new new
+
+        opts[:params] ||= {}
+        opts[:params].merge! id: id unless id.nil?
+
+        model.__callbacks__ << block unless block.nil?
+
+        operation(:read, **opts) do |data|
+          model.__setobj__ create_resource data, origin: model.__getobj__
+          model.__invoke__
+        end
+
+        model
+      end
+
+      def find_multiple(ids, opts, &block)
+        ::Acfs::Collection.new(self).tap do |collection|
+          collection.__callbacks__ << block unless block.nil?
+
+          counter = 0
+          ids.each_with_index do |id, index|
+            find_single(id, opts) do |resource|
+              collection[index] = resource
+              if (counter += 1) == ids.size
+                collection.loaded!
+                collection.__invoke__
+              end
+            end
+          end
+        end
+      end
+
+      def create_resource(data, **opts)
+        type = data.delete 'type'
+        klass = resource_class_lookup(type)
+        (opts[:origin].is_a?(klass) ? opts[:origin] : klass.new).tap do |m|
+          m.write_attributes(data, **opts)
+          m.loaded!
+        end
+      end
+
+      def resource_class_lookup(type)
+        return self if type.nil?
+
+        klass = type.camelize.constantize
+
+        unless klass <= self
+          raise Acfs::ResourceTypeError.new type_name: type, base_class: self
+        end
+
+        klass
+      rescue NameError
+        raise Acfs::ResourceTypeError.new type_name: type, base_class: self
+      end
+    end
+  end
+end