metasploit-model 0.25.7-java → 0.26.1-java

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 16bdcd3ce1aa7df0883325ab4ad5f9c6b26b50bf
-  data.tar.gz: 3230b2e0248005e81d3e154b580f038088ba6211
+  metadata.gz: c3a2b68f7f145be8fb8222b74a14338db405e248
+  data.tar.gz: 3e79e9872fd6176b719720e8d8858849eeae48d2
 SHA512:
-  metadata.gz: 71ab4f8e3c6c7ffab2f25b06676d845ee43bbc5999162972326de6cff7e41e46ba0aee27935aa97ad9ad2d2a58923e747f0fb329b2e1be7c9dee10487c941e14
-  data.tar.gz: 5ab795d0d8a7020ed23e24f1352da0f010cb1a032c2122621ccd0d891e25a705be5ae8bd25b4b67a7de90f8e649e7401ce10b4c99d591f06b84af85f54a7dfd8
+  metadata.gz: 067a2eecfb01ebd8e8b809774a0bf7634fd518a1aeb03302f1ad522b883a88732560dbbf56ec1ee13a55596c0883734802a1b0dc5139c81fe56aa9a2f2cceaef
+  data.tar.gz: 39a8e44825b5dbb5336e9307bcdff0e99372839d5af80786c5b445ab879e7b14193c781e7ca55790186de8031ba9818454055132301e170162c1a68068473c26

data/app/models/metasploit/model/search/operation/association.rb

@@ -0,0 +1,57 @@
+# An operation with a {Metasploit::Model::Search::Operator::Association} for
+# {Metasploit::Model::Search::Operation::Base#operator} that wraps a {#source_operation} produced by the
+# {Metasploit::Model::Search::Operator::Association#source_operator}.  This allows an arbitrary number of associations
+# to be changed together until a non-association operation is found that actually validates the value.
+class Metasploit::Model::Search::Operation::Association < Metasploit::Model::Search::Operation::Base
+  #
+  # Attributes
+  #
+
+  # @!attribute source_operation
+  #   The operation from the {Metasploit::Model::Search::Operator::Association#source_operator}.
+  #
+  #   @return [Metasploit::Model::Search::Operation::Base]
+  attr_accessor :source_operation
+
+  #
+  #
+  # Validations
+  #
+  #
+
+  #
+  # Validation Methods
+  #
+
+  validate :source_operation_valid
+
+  #
+  # Attribute Validations
+  #
+
+  validates :source_operation,
+            presence: true
+
+  #
+  # Instance Methods
+  #
+
+  # Explicitly remove value attribute so code that depends on the old behavior will break so downstream developers know
+  # to update their code to use source_operation.
+  undef_method :value
+  undef_method :value=
+
+  private
+
+  # Validates that {#source_operation} is valid.
+  #
+  # @return [void]
+  def source_operation_valid
+    # presence validation handles errors when nil
+    if source_operation
+      unless source_operation.valid?
+        errors.add(:source_operation, :invalid)
+      end
+    end
+  end
+end

data/app/models/metasploit/model/search/operator/association.rb

@@ -1,43 +1,53 @@
 # A search operator declared with
 # {Metasploit::Model::Search::Association::ClassMethods#search_association search_association}.
-class Metasploit::Model::Search::Operator::Association < Metasploit::Model::Search::Operator::Single
+class Metasploit::Model::Search::Operator::Association < Metasploit::Model::Search::Operator::Base
   #
   # Attributes
   #
 
   # @!attribute [rw] association
-  #   The association on which {Metasploit::Model::Search::Operator::Attribute#attribute} is declared searchable.
+  #   The association on which {#source_operator} was declared.
   #
   #   @return [Symbol] association on {Metasploit::Model::Search::Operator::Base#klass klass}.
   attr_accessor :association
 
-  # @!attribute [rw] attribute_operator
-  #   The {Metasploit::Model::Search::Operator::Attribute operator} as declared on the {#association} class.
+  # @!attribute [rw] source_operator
+  #   The {Metasploit::Model::Search::Operator::Base operator} as declared on the {#association} class.
   #
-  #   @return [Metasploit::Model::Search::Operator::Attribute]
-  attr_accessor :attribute_operator
+  #   @return [Metasploit::Model::Search::Operator::Base]
+  attr_accessor :source_operator
 
   #
   # Validations
   #
 
   validates :association, :presence => true
-  validates :attribute_operator, :presence => true
+  validates :source_operator, :presence => true
 
   #
   # Methods
   #
 
-  delegate :attribute,
-           :attribute_set,
-           :help,
-           :type,
-           :to => :attribute_operator
+  delegate :help,
+           to: :source_operator
 
   # The name of this operator.
   #
-  # @return [String] <association>.<attribute>
+  # @return [String] <association>.<source_operator.name>
   def name
-    @name ||= "#{association}.#{attribute}".to_sym
+    @name ||= "#{association}.#{source_operator.name}".to_sym
+  end
+
+  # Creates a {Metasploit::Model::Search::Operation::Association} to wrap the original operation returned by
+  #   {#source_operator}'s `#operate_on`.
+  #
+  # @param formatted_value [#to_s] Formatted value to pass to {#source_operator}.
+  # @return [Metasploit::Model::Search::Operation::Association] Association operation with the original operation from
+  #   {#source_operator} operating on `formatted_value`.
+  def operate_on(formatted_value)
+    Metasploit::Model::Search::Operation::Association.new(
+        operator: self,
+        source_operation: source_operator.operate_on(formatted_value)
+    )
   end
 end

data/app/models/metasploit/model/search/operator/base.rb

@@ -1,7 +1,23 @@
-# @abstract Declare search operators using {Metasploit::Model::Search::ClassMethods#search_attribute} and include
-#   operators from associations with {Metasploit::Model::Search::ClassMethods#search_association}.
+# Instead of writing an operator completely from scratch, you can subclass
+# {Metasploit::Model::Search::Operator::Base}.
+#
+#     class MyOperator < Metasploit::Model::Search::Operator::Base
+#       # Name of this operator.  The name of the operator is matched to the string before the ':' in a formatted
+#       # operation.
+#       #
+#       # @return [Symbol]
+#       def name
+#         # ...
+#       end
+#
+#       # Creates a one or more operations based on `formatted_value`.
+#       #
+#       # @return [#operator, Array<#operator>] Operation with this operator as the operation's `operator`.
+#       def operate_on(formatted_value)
+#         # ...
+#       end
+#     end
 #
-# A search operator.
 class Metasploit::Model::Search::Operator::Base < Metasploit::Model::Base
   include ActiveModel::Validations
   include Metasploit::Model::Search::Operator::Help

data/app/models/metasploit/model/search/operator/single.rb

@@ -1,4 +1,24 @@
-# @abstract Operator that only returns a single operation from {#operate_on}.
+# If all you want do is customize the name and operation `Class` that your custom operator class returns from
+# `#operate_on`, then you can subclass {Metasploit::Model::Search::Operator::Single} instead of
+# {Metasploit::Model::Search::Operator::Base}.
+#
+#     class MyOperator < Metasploit::Model::Search::Operator::Single
+#       # Name of this operator.  The name of the operator is matched to the string before the ':' in a formatted
+#       # operation.
+#       #
+#       # @return [Symbol]
+#       def name
+#         # ...
+#       end
+#
+#       # `Class.name` of `Class` returned from {Metasploit::Model::Search::Operator::Single#operate_on}.
+#       #
+#       # @return [String] a `Class.name`
+#       def operation_class_name
+#         # ...
+#       end
+#     end
+#
 class Metasploit::Model::Search::Operator::Single < Metasploit::Model::Search::Operator::Base
   #
   # CONSTANTS

data/app/models/metasploit/model/search/query.rb

@@ -1,4 +1,23 @@
-# A search query on a {#klass}.  Parses query from {#formatted} string.
+# Once {Metasploit::Model::Search::Operator search operators} are {Metasploit::Model::Search defined}, a formatted
+# query, composed of space separated formatted operation, `<operator.name>:<formatted_value>`, can be parsed to
+# produce a validatable query.
+#
+#     query = Metasploit::Model::Search::Query.new(
+#       formatted: 'parts.number:1 parts.number:2 parts.uuid:EX,QR'
+#     )
+#
+# Operations using the same operator are unioned together, while operations with different operator are intersected
+# together, so the above formatted query can be thought of as
+# `(parts.number:1 || parts.number:2) && parts.uuid:EX,QR`.
+#
+# # Results
+#
+# Once a {Metasploit::Model::Search::Query} is defined, it needs to be converted to a data store specific visitor.
+#
+# Visitors for `ActiveRecord` are defined in
+# {http://rubydoc.info/gems/metasploit_data_models/MetasploitDataModels/Search/Visitor MetasploitDataModels::Search::Visitor}.
+#
+# If you want to define your own visitors, you can subclass {Metasploit::Model::Visitation::Visitor}.
 class Metasploit::Model::Search::Query < Metasploit::Model::Base
   #
   # Attributes

data/lib/metasploit/model/association/tree.rb

@@ -0,0 +1,130 @@
+module Metasploit
+  module Model
+    module Association
+      # Functions for turning a compact tree of compact as passed to
+      # {Metasploit::Model::Search::Association::ClassMethods#search_associations} into an expanded
+      # {Metasploit::Model::Search::Association::ClassMethods#search_association_tree}.
+      module Tree
+        # Expands a `compact` association into an expanded association tree.
+        #
+        # @param compact [Array, Hash{Symbol => Array,Hash,Symbol}, Symbol] a compact association as passed to
+        #   {Metasploit::Model::Search::Association::ClassMethods#search_associations}.
+        # @return [Hash{Symbol => Hash,nil}]
+        def self.expand(compact)
+          case compact
+            when Array
+              compact.reduce({}) { |hash, association|
+                hash.merge(expand(association))
+              }
+            when Hash
+              child_by_parent = compact
+
+              child_by_parent.each_with_object({}) { |(parent, child), hash|
+                hash[parent] = expand(child)
+              }
+            when Symbol
+              association = compact
+
+              {association => nil}
+          end
+        end
+
+        # @note Unlike `Hash#deep_merge`, `second_expanded`'s values aren't favored over `first`'s values.  Instead whichever
+        #   side is present is used and if both `first` and `second_expanded` are present, then their `Hash#key`s' values are
+        #   recursively merged.
+        #
+        # Merges two expanded association trees.
+        #
+        # @param first_expanded [nil, Hash{Symbol => nil,Hash}] An expanded association tree as from {expand}
+        # @param second_expanded [nil, Hash{Symbol => nil,Hash}] An expanded association tree as from {expand}
+        # @return [nil, Hash{Symbol => nil,Hash}] a new expanded association tree.
+        def self.merge(first_expanded, second_expanded)
+          if first_expanded.nil? && second_expanded.nil?
+            nil
+          elsif !first_expanded.nil? && second_expanded.nil?
+            first_expanded
+          elsif first_expanded.nil? && !second_expanded.nil?
+            second_expanded
+          else
+            first_keys = first_expanded.keys
+            key_set = Set.new(first_keys)
+
+            second_keys = second_expanded.keys
+            key_set.merge(second_keys)
+
+            key_set.each_with_object({}) do |key, merged|
+              first_child = first_expanded[key]
+              second_child = second_expanded[key]
+
+              merged[key] = merge(first_child, second_child)
+            end
+          end
+        end
+
+        # Calculates association operators for the `expanded` association tree.
+        #
+        # @param expanded [Hash{Symbol => Hash,nil}, nil] An expanded association tree.
+        # @param options [Hash{Symbol => Class}]
+        # @option options [Class, #reflect_on_association] :class The `Class` on which the top-level key associations in
+        #   `expanded` are declared.
+        # @return [Array<Metasploit::Model::Search::Operator::Association>]
+        def self.operators(expanded, options={})
+          expanded ||= {}
+
+          options.assert_valid_keys(:class)
+          klass = options.fetch(:class)
+
+          expanded.flat_map { |parent_association, child_tree|
+            reflection = reflect_on_association_on_class(parent_association, klass)
+            association_class = reflection.klass
+
+            association_search_with_operators = association_class.search_with_operator_by_name.each_value
+
+            child_tree_operators = operators(
+                child_tree,
+                class: reflection.klass
+            )
+
+            [association_search_with_operators, child_tree_operators].flat_map { |enumerator|
+              enumerator.map { |source_operator|
+                Metasploit::Model::Search::Operator::Association.new(
+                    association: parent_association,
+                    klass: klass,
+                    source_operator: source_operator
+                )
+              }
+            }
+          }
+        end
+
+        private
+
+        # Return the association reflection for `association` on `klass`.
+        #
+        # @param association [Symbol] name of an association on `klass`.
+        # @param klass [#reflect_on_association] `Class` on which `association` is declared.
+        # @return [#klass] Association reflection that can give the `#klass` pointed to by the association.
+        # @raise [Metasploit::Model::Association::Error] if `association` is not declared on `klass`.
+        # @raise [NameError] if `klass` does not respond to `reflect_on_association`.
+        def self.reflect_on_association_on_class(association, klass)
+          begin
+            reflection = klass.reflect_on_association(association)
+          rescue NameError
+            raise NameError,
+                  "#{self} does not respond to reflect_on_association.  " \
+                      "It can be added to ActiveModels by including Metasploit::Model::Association into the class."
+          end
+
+          unless reflection
+            raise Metasploit::Model::Association::Error.new(
+                      model: klass,
+                      name: association
+                  )
+          end
+
+          reflection
+        end
+      end
+    end
+  end
+end

data/lib/metasploit/model/search.rb

@@ -2,6 +2,65 @@ module Metasploit
   module Model
     # DSL to define associations and attributes that can be searched.  Making an association searchable, will expose
     # the attributes that association's class defined as searchable.
+    #
+    # # Operators
+    #
+    # Search operators define how to search against a given `Class`.
+    #
+    # ## Attributes
+    #
+    # Boolean, `Date`, `Integer`, and `String` attributes can be searched with
+    # {Metasploit::Model::Search::Attribute::ClassMethods#search_attribute search_attribute}.  `Integer` and `String`
+    # attributes can be further restricted to a defined `Set` of values.
+    #
+    #     class Part
+    #       include Metasploit::Model::Search
+    #
+    #       search_attribute :part,
+    #                        :integer
+    #     end
+    #
+    # The above defines the `:part` operator on `Part`.
+    #
+    # ## Custom search operators
+    #
+    # If a search operator does not directly correspond to an attribute or a the attribute needs custom validation, then
+    # a custom {Metasploit::Model::Search::Operator operator class} can be setup as the search operator
+    #
+    #     class Search::Operator::UUID
+    #       def name
+    #         :uuid
+    #       end
+    #     end
+    #
+    #     class Part
+    #       include Metasploit::Model::Search
+    #
+    #       search_with Search::Operator::UUID
+    #     end
+    #
+    # The above defines the `:uuid` operator on `Part`.
+    #
+    # ## Associations
+    #
+    # Search operators registered with
+    # {Metasploit::Model::Search::Attribute::ClassMethods#search_attribute search_attribute} or
+    # {Metasploit::Model::Search::With::ClassMethods#search_with search_with} on an associated `Class` can be searched
+    # with {Metasploit::Model::Search::Association::ClassMethods#search_association}:
+    #
+    #     class Widget
+    #       include Metasploit::Model::Search
+    #
+    #       # declare parts association
+    #
+    #       search_association :parts
+    #     end
+    #
+    # The above will define the `:'parts.number'` and `:'parts.uuid'` operator on `Widget`.
+    #
+    # # Queries
+    #
+    # {include:Metasploit::Model::Search::Query}
     module Search
       extend ActiveSupport::Concern
 
@@ -25,33 +84,8 @@ module Metasploit
               @search_operator_by_name[operator.name] = operator
             end
 
-            search_association_set.each do |association|
-              begin
-                reflection = reflect_on_association(association)
-              rescue NameError
-                raise NameError,
-                      "#{self} does not respond to reflect_on_association.  " \
-                      "It can be added to ActiveModels by including Metasploit::Model::Association into the class."
-              end
-
-              unless reflection
-                raise Metasploit::Model::Association::Error.new(:model => self, :name => association)
-              end
-
-              association_class = reflection.klass
-
-              # don't use search_operator_by_name as association operators on operators won't work
-              association_class.search_with_operator_by_name.each_value do |with_operator|
-                # non-attribute operators on association are assumed not to work
-                if with_operator.respond_to? :attribute
-                  association_operator = Metasploit::Model::Search::Operator::Association.new(
-                      :association => association,
-                      :attribute_operator => with_operator,
-                      :klass => self
-                  )
-                  @search_operator_by_name[association_operator.name] = association_operator
-                end
-              end
+            search_association_operators.each do |operator|
+              @search_operator_by_name[operator.name] = operator
             end
           end