acfs 0.16.0 → 0.17.0

data/lib/acfs/messaging/receiver.rb

@@ -0,0 +1,119 @@
+module Acfs::Messaging
+
+  # @macro experimental
+  #
+  # A {Receiver} subscribes to a messaging queue and
+  # reacts to received messages.
+  #
+  # @example
+  #   class UserWelcomeReceiver < Acfs::Receiver
+  #
+  module Receiver
+    extend ActiveSupport::Concern
+
+    included do
+      Acfs::Messaging::Client.register self
+    end
+
+    def init(client)
+      @channel  = client.channel
+      @queue    = @channel.queue self.class.queue, options
+      @queue.bind client.exchange, routing_key: self.class.routing_key
+
+      @queue.subscribe do |delivery_info, metadata, payload|
+        process_received delivery_info, metadata, payload
+      end
+    end
+
+    def process_received(delivery_info, metadata, payload)
+      return if delivery_info.nil?
+
+      payload = MessagePack.unpack payload
+      payload.symbolize_keys! if payload.is_a? Hash
+      receive delivery_info, metadata, payload
+    end
+
+    def options
+      @options ||= self.class.options
+    end
+
+    # @macro experimental
+    #
+    # Handle incoming messages. Should be overridden by derived class.
+    #
+    def receive(delivery_info, metadata, payload)
+
+    end
+
+    module ClassMethods
+
+      # @macro experimental
+      #
+      # @overload queue
+      #   Return name of queue to listen on. Default name will be
+      #   generated based on full class name.
+      #
+      #   @return [String] Name of queue to listen on.
+      #
+      # @overload queue(name)
+      #   Set queue name to listen on.
+      #
+      #   @param [String] name Queue name to listen on.
+      #   @return [String] Set name of queue to listen on.
+      #
+      def queue(*args)
+        raise ArgumentError.new 'Receiver.queue accepts zero or one argument.' if args.size > 1
+
+        @queue ||= self.name.underscore.gsub('/', '.')
+        @queue = args[0].nil? ? nil : args[0].to_s if args.size > 0
+        @queue
+      end
+
+      # @macro experimental
+      #
+      # Specify routing key for this receiver. The routing key defines
+      # which exchanges should be subscribed to receive messages from.
+      #
+      # @param [#to_s] key Routing key.
+      #
+      def route(key)
+        @routing_key = key.to_s
+      end
+
+      # @macro experimental
+      #
+      # @overload options
+      #   Return configured options for this receiver.
+      #
+      #   @return [Hash] Configured options.
+      #
+      # @overload options(opts)
+      #   Set configuration options.
+      #
+      #   @param [Hash] opts Messaging channel options.
+      #   @return [Hash] Configured options.
+      #
+      def options(opts = nil)
+        @options ||= {}
+        return @options if opts.nil?
+
+        @options = opts.to_hash if opts.respond_to? :to_hash
+      end
+
+      # @api private
+      #
+      # Return configured routing key if any.
+      # Default value is `#`.
+      #
+      # @return [String, Nil] Routing key or `nil`.
+      #
+      def routing_key
+        @routing_key ||= '#'
+      end
+
+      def instance
+        @instance ||= new
+      end
+    end
+  end
+end

data/lib/acfs/model.rb

@@ -11,6 +11,9 @@ require 'acfs/model/relations'
 require 'acfs/model/service'
 
 module Acfs
+
+  # @api public
+  #
   module Model
     extend ActiveSupport::Concern
 

data/lib/acfs/model/attributes.rb

@@ -1,9 +1,10 @@
 module Acfs::Model
 
-  # == Acfs Attributes
+  # = Acfs Attributes
   #
   # Allows to specify attributes of a class with default values and type safety.
   #
+  # @example
   #   class User
   #     include Acfs::Model
   #     attribute :name, :string, default: 'Anon'
@@ -18,13 +19,23 @@ module Acfs::Model
     extend ActiveSupport::Concern
     include ActiveModel::AttributeMethods
 
-    def initialize(*attrs) # :nodoc:
+    # @api public
+    #
+    # Write default attributes defined in resource class.
+    #
+    # @see #write_attributes
+    # @see ClassMethods#attributes
+    #
+    def initialize(*attrs)
       self.write_attributes self.class.attributes, change: false
       super
     end
 
+    # @api public
+    #
     # Returns ActiveModel compatible list of attributes and values.
     #
+    # @example
     #   class User
     #     include Acfs::Model
     #     attribute :name, type: String, default: 'Anon'
@@ -32,24 +43,58 @@ module Acfs::Model
     #   user = User.new(name: 'John')
     #   user.attributes # => { "name" => "John" }
     #
+    # @return [ HashWithIndifferentAccess{ Symbol => Object } ] Attributes and their values.
+    #
     def attributes
       HashWithIndifferentAccess.new self.class.attributes.keys.inject({}) { |h, k| h[k.to_sym] = public_send k; h }
     end
 
-    # Update all attributes with given hash.
+    # @api public
+    #
+    # Update all attributes with given hash. Attribute values will be casted
+    # to defined attribute type.
+    #
+    # @example
+    #   user.attributes = { :name => 'Adam' }
+    #   user.name # => 'Adam'
+    #
+    # @param [ Hash{ String, Symbol => Object }, #each{|key, value|} ] attributes to set in resource.
+    # @see #write_attributes Delegates attributes hash to `#write_attributes`.
     #
     def attributes=(attributes)
       write_attributes attributes
     end
 
-    # Read an attribute.
+    # @api public
+    #
+    # Read an attribute from instance variable.
+    #
+    # @param [ Symbol, String ] name Attribute name.
+    # @return [ Object ] Attribute value.
     #
     def read_attribute(name)
       instance_variable_get :"@#{name}"
     end
 
+    # @api public
+    #
     # Write a hash of attributes and values.
     #
+    # If attribute value is a `Proc` it will be evaluated in the context
+    # of the resource after all non-proc attribute values are set. Values
+    # will be casted to defined attribute type.
+    #
+    # The behavior is used to apply default attributes from resource
+    # class definition.
+    #
+    # @example
+    #   user.write_attributes { :name => 'john', :email => lambda{ "#{name}@example.org" } }
+    #   user.name  # => 'john'
+    #   user.email # => 'john@example.org'
+    #
+    # @param [ Hash{ String, Symbol => Object, Proc }, #each{|key, value|} ] attributes to write.
+    # @see #write_attribute Delegates attribute values to `#write_attribute`.
+    #
     def write_attributes(attributes, opts = {})
       return false unless attributes.respond_to? :each
 
@@ -66,37 +111,58 @@ module Acfs::Model
       procs.each do |key, proc|
         write_attribute key, instance_exec(&proc), opts
       end
+
       true
     end
 
-    # Write an attribute.
+    # @api public
+    #
+    # Write single attribute with given value. Value will be casted
+    # to defined attribute type.
+    #
+    # @param [ String, Symbol ] name Attribute name.
+    # @param [ Object ] value Value to write.
+    # @raise [ ArgumentError ] If no attribute with given name is defined.
     #
     def write_attribute(name, value, opts = {})
       if (type = self.class.attribute_types[name.to_sym]).nil?
-        raise "Unknown attribute `#{name}`."
+        raise ArgumentError.new "Unknown attribute `#{name}`."
       end
 
       write_raw_attribute name, value.nil? ? nil : type.cast(value), opts
     end
 
-    # Write an attribute without checking type and existence or casting
-    # value to attributes type.
+    # @api private
+    #
+    # Write an attribute without checking type or existence or casting
+    # value to attributes type. Value be stored in an instance variable
+    # named after attribute name.
+    #
+    # @param [ String, Symbol ] name Attribute name.
+    # @param [ Object ] value Attribute value.
     #
     def write_raw_attribute(name, value, _ = {})
       instance_variable_set :"@#{name}", value
     end
 
-    module ClassMethods # :nodoc:
+    module ClassMethods
 
+      # @api public
+      #
       # Define a model attribute by name and type. Will create getter and
       # setter for given attribute name. Existing methods will be overridden.
       #
+      # Available types can be found in `Acfs::Model::Attributes::*`.
+      #
+      # @example
       #   class User
       #     include Acfs::Model
       #     attribute :name, :string, default: 'Anon'
+      #     attribute :email, :string, default: lambda{ "#{name}@example.org"}
       #   end
       #
-      # Available types can be found in `Acfs::Model::Attributes::*`.
+      # @param [ #to_sym ] name Attribute name.
+      # @param [ Symbol, String, Class ] type Attribute type identifier or type class.
       #
       def attribute(name, type, opts = {})
         if type.is_a? Symbol or type.is_a? String
@@ -106,8 +172,11 @@ module Acfs::Model
         define_attribute name.to_sym, type, opts
       end
 
+      # @api public
+      #
       # Return list of possible attributes and default values for this model class.
       #
+      # @example
       #   class User
       #     include Acfs::Model
       #     attribute :name, :string
@@ -115,20 +184,36 @@ module Acfs::Model
       #   end
       #   User.attributes # => { "name": nil, "age": 25 }
       #
+      # @return [ Hash{ String => Object, Proc } ] Attributes with default values.
+      #
       def attributes
         @attributes ||= {}
       end
 
+      # @api public
+      #
       # Return hash of attributes and there types.
       #
+      # @example
+      #   class User
+      #     include Acfs::Model
+      #     attribute :name, :string
+      #     attribute :age, :integer, default: 25
+      #   end
+      #   User.attributes # => { "name": Acfs::Model::Attributes::String, "age": Acfs::Model::Attributes::Integer }
+      #
+      # @return [ Hash{ Symbol => Class } ] Attributes and their types.
+      #
       def attribute_types
         @attribute_types ||= {}
       end
 
       private
-      def define_attribute(name, type, opts = {}) # :nodoc:
+      def define_attribute(name, type, opts = {})
+        name             = name.to_s
         default_value    = opts.has_key?(:default) ? opts[:default] : nil
         default_value    = type.cast default_value unless default_value.is_a? Proc or default_value.nil?
+
         attributes[name] = default_value
         attribute_types[name.to_sym] = type
         define_attribute_method name
@@ -147,7 +232,7 @@ end
 
 # Load attribute type classes.
 #
-Dir[File.dirname(__FILE__) + "/attributes/*.rb"].sort.each do |path|
+Dir[File.dirname(__FILE__) + '/attributes/*.rb'].sort.each do |path|
   filename = File.basename(path)
   require "acfs/model/attributes/#{filename}"
 end

data/lib/acfs/model/attributes/boolean.rb

@@ -1,8 +1,11 @@
 module Acfs::Model
   module Attributes
 
+    # @api public
+    #
     # Boolean attribute type. Use it in your model as an attribute type:
     #
+    # @example
     #   class User
     #     include Acfs::Model
     #     attribute :name, :boolean
@@ -13,10 +16,17 @@ module Acfs::Model
     #
     #  true, on, yes
     #
-    module Boolean # :nodoc:
+    module Boolean
 
       TRUE_VALUES = %w(true on yes)
 
+      # @api public
+      #
+      # Cast given object to boolean.
+      #
+      # @param [Object] obj Object to cast.
+      # @return [TrueClass, FalseClass] Casted boolean.
+      #
       def self.cast(obj)
         return true if obj.is_a? TrueClass
         return false if obj.is_a? FalseClass

data/lib/acfs/model/attributes/integer.rb

@@ -1,15 +1,25 @@
 module Acfs::Model
   module Attributes
 
+    # @api public
+    #
     # Integer attribute type. Use it in your model as an attribute type:
     #
+    # @example
     #   class User
     #     include Acfs::Model
     #     attribute :name, :integer
     #   end
     #
-    module Integer # :nodoc:
+    module Integer
 
+      # @api public
+      #
+      # Cast given object to integer.
+      #
+      # @param [Object] obj Object to cast.
+      # @return [Fixnum] Casted object as fixnum.
+      #
       def self.cast(obj)
         obj.to_i
       end

data/lib/acfs/model/attributes/string.rb

@@ -1,15 +1,25 @@
 module Acfs::Model
   module Attributes
 
+    # @api public
+    #
     # String attribute type. Use it in your model as an attribute type:
     #
+    # @example
     #   class User
     #     include Acfs::Model
     #     attribute :name, :string
     #   end
     #
-    module String # :nodoc:
+    module String
 
+      # @api public
+      #
+      # Cast given object to string.
+      #
+      # @param [Object] obj Object to cast.
+      # @return [String] Casted string.
+      #
       def self.cast(obj)
         obj.to_s
       end

data/lib/acfs/model/dirty.rb

@@ -7,12 +7,16 @@ module Acfs
       extend ActiveSupport::Concern
       include ActiveModel::Dirty
 
-      # Resets all changes. Do not touch previous changes.
+      # @api private
+      #
+      # Resets all changes. Does not touch previous changes.
       #
       def reset_changes
         changed_attributes.clear
       end
 
+      # @api private
+      #
       # Save current changes as previous changes and reset
       # current one.
       #
@@ -21,15 +25,21 @@ module Acfs
         reset_changes
       end
 
-      def save!(*) # :nodoc:
-        super.tap { |__| swap_changes }
+      # @api private
+      #
+      def save!(*)
+        super.tap { |_| swap_changes }
       end
 
-      def loaded! # :nodoc:
+      # @api private
+      #
+      def loaded!
         reset_changes
         super
       end
 
+      # @api private
+      #
       def write_raw_attribute(name, value, opts = {}) # :nodoc:
         attribute_will_change! name if opts[:change].nil? or opts[:change]
         super