skull_island 0.1.0 → 0.1.1

data/lib/skull_island/resource.rb

@@ -0,0 +1,198 @@
+# frozen_string_literal: true
+
+module SkullIsland
+  # A generic API resource
+  # TODO: Thread safety
+  class Resource
+    attr_accessor :api_client
+    attr_reader :errors
+
+    include Comparable
+    include Validations::Resource
+    include Helpers::Resource
+    extend Helpers::ResourceClass
+
+    # Can this type of resource be changed client-side?
+    def self.immutable(status)
+      raise Exceptions::InvalidArguments unless status.is_a?(TrueClass) || status.is_a?(FalseClass)
+
+      @immutable = status
+    end
+
+    # Define a property for a model
+    # @!macro [attach] property
+    #   The $1 property
+    # @todo add more validations on options and names
+    def self.property(name, options = {})
+      @properties ||= {}
+
+      invalid_prop_names = %i[
+        > < = class def
+        % ! / . ? * {}
+        \[\]
+      ]
+
+      raise(Exceptions::InvalidProperty) if invalid_prop_names.include?(name.to_sym)
+
+      @properties[name.to_sym] = options
+    end
+
+    def self.gen_getter_method(name, opts)
+      determine_getter_names(name, opts).each do |method_name|
+        define_method(method_name) do
+          name_as_string = name.to_s
+          reload if @lazy && !@entity.key?(name_as_string)
+
+          if opts[:postprocess]
+            send("postprocess_#{name}".to_sym, @entity[name_as_string])
+          else
+            @entity[name_as_string]
+          end
+        end
+      end
+    end
+
+    def self.gen_setter_method(name, opts)
+      determine_setter_names(name, opts).each do |method_name|
+        define_method(method_name) do |value|
+          raise Exceptions::ImmutableModification if immutable?
+
+          if opts[:validate]
+            raise Exceptions::InvalidArguments unless send("validate_#{name}".to_sym, value)
+          end
+          @entity[name.to_s] = if opts[:preprocess]
+                                 send("preprocess_#{name}".to_sym, value)
+                               else
+                                 value
+                               end
+          @tainted = true
+          @modified_properties << name.to_sym
+        end
+      end
+    end
+
+    def self.gen_property_methods
+      properties.each do |prop, opts|
+        # Getter methods
+        next if opts[:id_property]
+
+        gen_getter_method(prop, opts) unless opts[:write_only]
+
+        # Setter methods (don't make one for obviously read-only properties)
+        gen_setter_method(prop, opts) unless opts[:read_only]
+      end
+    end
+
+    # The URI (relative to the API base) for this object (or its index/list)
+    def self.relative_uri
+      route_key
+    end
+
+    def self.all(options = {})
+      # TODO: Add validations for options
+      # TODO: add validation checks for the required pieces
+
+      api_client = options[:api_client] || APIClient.instance
+
+      root = 'data' # root for API JSON response data
+      # TODO: do something with lazy requests...
+
+      ResourceCollection.new(
+        api_client.get(relative_uri)[root].collect do |record|
+          unless options[:lazy]
+            api_client.invalidate_cache_for "#{relative_uri}/#{record['id']}"
+            api_client.cache("#{relative_uri}/#{record['id']}") do
+              record
+            end
+          end
+          new(
+            entity: record,
+            lazy: (options[:lazy] ? true : false),
+            tainted: false,
+            api_client: api_client
+          )
+        end,
+        type: self,
+        api_client: api_client
+      )
+    end
+
+    def self.from_hash(hash)
+      # TODO: better options validations
+      raise Exceptions::InvalidOptions unless options.is_a?(Hash)
+
+      api_client = options[:api_client] || APIClient.instance
+
+      new(
+        entity: hash,
+        lazy: true,
+        tainted: true,
+        api_client: api_client
+      )
+    end
+
+    def self.get(id, options = {})
+      # TODO: Add validations for options
+
+      api_client = options[:api_client] || APIClient.instance
+
+      if options[:lazy]
+        new(
+          entity: { 'id' => id },
+          lazy: true,
+          tainted: false,
+          api_client: api_client
+        )
+      else
+        entity_data = api_client.cache("#{relative_uri}/#{id}") do |client|
+          client.get("#{relative_uri}/#{id}")
+        end
+
+        new(
+          entity: entity_data,
+          lazy: false,
+          tainted: false,
+          api_client: api_client
+        )
+      end
+    end
+
+    def self.where(attribute, value, options = {})
+      # TODO: validate incoming options
+      options[:comparison] ||= value.is_a?(Regexp) ? :match : '=='
+      api_client = options[:api_client] || APIClient.instance
+      all(lazy: (options[:lazy] ? true : false), api_client: api_client).where(
+        attribute, value, comparison: options[:comparison]
+      )
+    end
+
+    def initialize(options = {})
+      # TODO: better options validations
+      raise Exceptions::InvalidOptions unless options.is_a?(Hash)
+
+      @entity = options[:entity] || {}
+
+      # Allows lazy-loading if we're told this is a lazy instance
+      #  This means only the minimal attributes were fetched.
+      #  This shouldn't be set by end-users.
+      @lazy = options.key?(:lazy) ? options[:lazy] : false
+      # This allows local, user-created instances to be differentiated from fetched
+      # instances from the backend API. This shouldn't be set by end-users.
+      @tainted = options.key?(:tainted) ? options[:tainted] : true
+      # This is the API Client used to get data for this resource
+      @api_client = options[:api_client] || APIClient.instance
+      @errors = {}
+      # A place to store which properties have been modified
+      @modified_properties = []
+
+      validate_mutability
+      validate_id
+
+      self.class.class_eval { gen_property_methods }
+    end
+
+    def relative_uri
+      "#{self.class.relative_uri}/#{id}"
+    end
+  end
+end

data/lib/skull_island/resource_collection.rb

@@ -0,0 +1,193 @@
+# frozen_string_literal: true
+
+module SkullIsland
+  # The ResourceCollection class
+  # Should not allow or use mixed types
+  class ResourceCollection
+    include Enumerable
+    include Comparable
+
+    # @return [Class] a collection of this {Resource} subclass
+    attr_reader :type
+
+    def initialize(list, options = {})
+      # TODO: better options validations
+      raise Exceptions::InvalidOptions unless options.is_a?(Hash)
+      raise Exceptions::InvalidArguments if list.empty? && options[:type].nil?
+
+      @api_client = options[:api_client] || APIClient.instance
+      @list = list
+      @type = options[:type] || list.first.class
+    end
+
+    def each(&block)
+      @list.each(&block)
+    end
+
+    # Does the collection contain anything?
+    # @return [Boolean]
+    def empty?
+      @list.empty?
+    end
+
+    # Provide the first (or first `number`) entries
+    # @param number [Fixnum] How many to provide
+    # @return [ResourceCollection,Resource]
+    def first(number = nil)
+      if number
+        self.class.new(@list.first(number), type: @type, api_client: @api_client)
+      else
+        @list.first
+      end
+    end
+
+    # Provide the last (or last `number`) entries
+    # @param number [Fixnum] How many to provide
+    # @return [ResourceCollection,Resource]
+    def last(number = nil)
+      if number
+        self.class.new(@list.last(number), type: @type, api_client: @api_client)
+      else
+        @list.last
+      end
+    end
+
+    # Merge two collections
+    # @param other [ResourceCollection]
+    # @return [ResourceCollection]
+    def merge(other)
+      raise Exceptions::InvalidArguments unless other.is_a?(self.class)
+
+      self + (other - self)
+    end
+
+    # An alias for {#type}
+    def model
+      type
+    end
+
+    # Hacked together #or() method in the same spirit as #where().
+    # This method can be chained for multiple / more specific queries.
+    #
+    # @param attribute [Symbol] the attribute to query
+    # @param value [Object] the value to compare against
+    #   - allowed options are "'==', '!=', '>', '>=', '<', '<=', and 'match'"
+    # @raise [Exceptions::InvalidWhereQuery] if not the right kind of comparison
+    # @return [ResourceCollection]
+    def or(attribute, value, options = {})
+      options[:comparison] ||= value.is_a?(Regexp) ? :match : '=='
+      if empty?
+        @type.where(attribute, value, comparison: options[:comparison], api_client: @api_client)
+      else
+        merge first.class.where(
+          attribute, value,
+          comparison: options[:comparison],
+          api_client: @api_client
+        )
+      end
+    end
+
+    # Pass pagination through to the Array (which passes to will_paginate)
+    def paginate(*args)
+      @list.paginate(*args)
+    end
+
+    # Returns the number of Resource instances in the collection
+    # @return [Fixnum]
+    def size
+      @list.size
+    end
+
+    # Allow complex sorting like an Array
+    # @return [ResourceCollection] sorted collection
+    def sort(&block)
+      self.class.new(super(&block), type: @type, api_client: @api_client)
+    end
+
+    # Horribly inefficient way to allow querying Resources by their attributes.
+    # This method can be chained for multiple / more specific queries.
+    #
+    # @param attribute [Symbol] the attribute to query
+    # @param value [Object] the value to compare against
+    #   - allowed options are "'==', '!=', '>', '>=', '<', '<=', and 'match'"
+    # @raise [Exceptions::InvalidWhereQuery] if not the right kind of comparison
+    # @return [ResourceCollection]
+    def where(attribute, value, options = {})
+      valid_comparisons = %i[== != > >= < <= match]
+      options[:comparison] ||= value.is_a?(Regexp) ? :match : '=='
+      unless valid_comparisons.include?(options[:comparison].to_sym)
+        raise Exceptions::InvalidWhereQuery
+      end
+
+      self.class.new(
+        @list.collect do |item|
+          if item.send(attribute).nil?
+            nil
+          elsif item.send(attribute).send(options[:comparison].to_sym, value)
+            item
+          end
+        end.compact,
+        type: @type,
+        api_client: @api_client
+      )
+    end
+
+    alias and where
+
+    # Return the collection item at the specified index
+    # @return [Resource,ResourceCollection] the item at the requested index
+    def [](index)
+      if index.is_a?(Range)
+        self.class.new(@list[index], type: @type, api_client: @api_client)
+      else
+        @list[index]
+      end
+    end
+
+    # Return a collection after subtracting from the original
+    # @return [ResourceCollection]
+    def -(other)
+      if other.respond_to?(:to_a)
+        self.class.new(@list - other.to_a, type: @type, api_client: @api_client)
+      elsif other.is_a?(Resource)
+        self.class.new(@list - Array(other), type: @type, api_client: @api_client)
+      else
+        raise Exceptions::InvalidArguments
+      end
+    end
+
+    # Return a collection after adding to the original
+    #   Warning: this may cause duplicates or mixed type joins! For safety,
+    #   use #merge
+    # @return [ResourceCollection]
+    def +(other)
+      if other.is_a?(self.class)
+        self.class.new(@list + other.to_a, type: @type, api_client: @api_client)
+      elsif other.is_a?(@type)
+        self.class.new(@list + [other], type: @type, api_client: @api_client)
+      else
+        raise Exceptions::InvalidArguments
+      end
+    end
+
+    def <<(other)
+      raise Exceptions::InvalidArguments, 'Resource Type Mismatch' unless other.class == @type
+
+      @list << other
+    end
+
+    def <=>(other)
+      collect(&:id).sort <=> other.collect(&:id).sort
+    end
+
+    # Allow comparison of collection
+    # @return [Boolean] do the collections contain the same resource ids?
+    def ==(other)
+      if other.is_a? self.class
+        collect(&:id).sort == other.collect(&:id).sort
+      else
+        false
+      end
+    end
+  end
+end

data/lib/skull_island/resources/certificate.rb

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+module SkullIsland
+  # Resource classes go here...
+  module Resources
+    # The Certificate resource class
+    #
+    # @see https://docs.konghq.com/0.14.x/admin-api/#certificate-object Certificate API definition
+    class Certificate < Resource
+      property :cert, required: true, validate: true
+      property :key, required: true, validate: true
+      property :snis, validate: true
+      property :created_at, read_only: true, postprocess: true
+
+      private
+
+      # Used to validate {#cert} on set
+      def validate_cert(value)
+        # only String is allowed
+        value.is_a?(String)
+      end
+
+      # Used to validate {#key} on set
+      def validate_key(value)
+        # only String is allowed
+        value.is_a?(String)
+      end
+
+      # Used to validate {#snis} on set
+      def validate_snis(value)
+        # only Array is allowed
+        value.is_a?(Array)
+      end
+    end
+  end
+end

data/lib/skull_island/resources/consumer.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+module SkullIsland
+  # Resource classes go here...
+  module Resources
+    # The Consumer resource class
+    #
+    # @see https://docs.konghq.com/0.14.x/admin-api/#consumer-object Consumer API definition
+    class Consumer < Resource
+      property :username
+      property :custom_id
+      property :created_at, read_only: true, postprocess: true
+
+      # Provides a collection of related {Plugin} instances
+      def plugins
+        Plugin.where(:consumer, self, api_client: api_client)
+      end
+    end
+  end
+end

data/lib/skull_island/resources/plugin.rb

@@ -0,0 +1,144 @@
+# frozen_string_literal: true
+
+module SkullIsland
+  # Resource classes go here...
+  module Resources
+    # The Plugin resource class
+    #
+    # @see https://docs.konghq.com/0.14.x/admin-api/#plugin-object Plugin API definition
+    class Plugin < Resource
+      property :name
+      property :enabled, type: :boolean
+      # property :run_on  # 1.0.x only
+      property :config, validate: true
+      property :consumer_id, validate: true, preprocess: true, postprocess: true, as: :consumer
+      property :route_id, validate: true, preprocess: true, postprocess: true, as: :route
+      property :service_id, validate: true, preprocess: true, postprocess: true, as: :service
+      property :created_at, read_only: true, postprocess: true
+
+      def self.enabled_names(api_client: APIClient.instance)
+        api_client.get("#{relative_uri}/enabled")['enabled_plugins']
+      end
+
+      def self.schema(name, api_client: APIClient.instance)
+        api_client.get("#{relative_uri}/schema/#{name}")
+      end
+
+      private
+
+      # TODO: 1.0.x requires refactoring as `consumer_id` becomes `consumer`
+      def postprocess_consumer_id(value)
+        if value.is_a?(Hash)
+          Consumer.new(
+            entity: value,
+            lazy: true,
+            tainted: false
+          )
+        elsif value.is_a?(String)
+          Consumer.new(
+            entity: { 'id' => value },
+            lazy: true,
+            tainted: false
+          )
+        else
+          value
+        end
+      end
+
+      # TODO: 1.0.x requires refactoring as `consumer_id` becomes `consumer`
+      def preprocess_consumer_id(input)
+        if input.is_a?(Hash)
+          input['id']
+        elsif input.is_a?(Consumer)
+          input.id
+        else
+          input
+        end
+      end
+
+      # TODO: 1.0.x requires refactoring as `route_id` becomes `route`
+      def postprocess_route_id(value)
+        if value.is_a?(Hash)
+          Route.new(
+            entity: value,
+            lazy: true,
+            tainted: false
+          )
+        elsif value.is_a?(String)
+          Route.new(
+            entity: { 'id' => value },
+            lazy: true,
+            tainted: false
+          )
+        else
+          value
+        end
+      end
+
+      # TODO: 1.0.x requires refactoring as `route_id` becomes `route`
+      def preprocess_route_id(input)
+        if input.is_a?(Hash)
+          input['id']
+        elsif input.is_a?(Route)
+          input.id
+        else
+          input
+        end
+      end
+
+      # TODO: 1.0.x requires refactoring as `service_id` becomes `service`
+      def postprocess_service_id(value)
+        if value.is_a?(Hash)
+          Service.new(
+            entity: value,
+            lazy: true,
+            tainted: false
+          )
+        elsif value.is_a?(String)
+          Service.new(
+            entity: { 'id' => value },
+            lazy: true,
+            tainted: false
+          )
+        else
+          value
+        end
+      end
+
+      # TODO: 1.0.x requires refactoring as `service_id` becomes `service`
+      def preprocess_service_id(input)
+        if input.is_a?(Hash)
+          input['id']
+        elsif input.is_a?(Service)
+          input.id
+        else
+          input
+        end
+      end
+
+      # Used to validate {#config} on set
+      def validate_config(value)
+        # only Hashes are allowed
+        value.is_a?(Hash)
+      end
+
+      # Used to validate {#consumer} on set
+      def validate_consumer_id(value)
+        # allow either a Consumer object or a Hash of a specific structure
+        value.is_a?(Consumer) || (value.is_a?(Hash) && value['id'].is_a?(String))
+      end
+
+      # Used to validate {#route} on set
+      def validate_route_id(value)
+        # allow either a Route object or a Hash of a specific structure
+        value.is_a?(Route) || (value.is_a?(Hash) && value['id'].is_a?(String))
+      end
+
+      # Used to validate {#service} on set
+      def validate_service_id(value)
+        # allow either a Service object or a Hash of a specific structure
+        value.is_a?(Service) || (value.is_a?(Hash) && value['id'].is_a?(String))
+      end
+    end
+  end
+end

data/lib/skull_island/resources/route.rb

@@ -0,0 +1,83 @@
+# frozen_string_literal: true
+
+module SkullIsland
+  # Resource classes go here...
+  module Resources
+    # The Route resource class
+    #
+    # @see https://docs.konghq.com/0.14.x/admin-api/#route-object Route API definition
+    class Route < Resource
+      property :name
+      property :methods
+      property :paths
+      property :protocols,      validate: true
+      property :hosts,          validate: true
+      property :regex_priority, validate: true
+      property :strip_path,     type: :boolean
+      property :preserve_host,  type: :boolean
+      # The following are 1.0.x only
+      # property :snis
+      # property :sources
+      # property :destinations
+      property :service, validate: true, preprocess: true, postprocess: true
+      property :created_at, read_only: true, postprocess: true
+      property :updated_at, read_only: true, postprocess: true
+
+      # Provides a collection of related {Plugin} instances
+      def plugins
+        Plugin.where(:route, self, api_client: api_client)
+      end
+
+      private
+
+      def postprocess_service(value)
+        if value.is_a?(Hash)
+          Service.new(
+            entity: value,
+            lazy: true,
+            tainted: false
+          )
+        else
+          value
+        end
+      end
+
+      def preprocess_service(input)
+        if input.is_a?(Hash)
+          input
+        else
+          { 'id' => input.id }
+        end
+      end
+
+      # Used to validate {#protocols} on set
+      def validate_protocols(value)
+        value.is_a?(Array) &&                     # Must be an array
+          (1..4).cover?(value.size) &&            # Must be exactly 1..4 in size
+          value.uniq == value &&                  # Must not have duplicate values
+          (value - %w[http https tls tcp]).empty? # Must only contain appropriate protocols
+      end
+
+      # Used to validate {#hosts} on set
+      def validate_hosts(value)
+        # allow only valid hostnames
+        value.each do |host|
+          return false unless host.match?(host_regex) && !host.match?(/_/)
+        end
+        true
+      end
+
+      # Used to validate {#regex_priority} on set
+      def validate_regex_priority(value)
+        # only positive Integers are allowed
+        value.is_a?(Integer) && (value.positive? || value.zero?)
+      end
+
+      # Used to validate {#service} on set
+      def validate_service(value)
+        # allow either a Service object or a Hash of a specific structure
+        value.is_a?(Service) || (value.is_a?(Hash) && value['id'].is_a?(String))
+      end
+    end
+  end
+end