skull_island 0.1.0 → 0.1.1

data/lib/skull_island/api_client_base.rb

@@ -0,0 +1,86 @@
+# frozen_string_literal: true
+
+module SkullIsland
+  # The API Client Base class
+  class APIClientBase
+    attr_reader :server, :base_uri
+    attr_accessor :username, :password
+
+    include Validations::APIClient
+    include Helpers::APIClient
+
+    def api_uri
+      @api_uri ||= URI.parse(server)
+      @api_uri.path = base_uri if base_uri
+      @api_uri
+    end
+
+    def authenticated?
+      raise Exceptions::APIClientNotConfigured unless configured?
+
+      @username && @password ? true : false
+    end
+
+    def configured?
+      @configured ? true : false
+    end
+
+    def json_headers
+      { content_type: :json, accept: :json }
+    end
+
+    def get(uri, data = nil)
+      client_action do |client|
+        if data
+          JSON.parse client[uri].get(json_headers.merge(params: data))
+        else
+          JSON.parse client[uri].get(json_headers)
+        end
+      end
+    end
+
+    def post(uri, data = nil)
+      client_action do |client|
+        if data
+          JSON.parse client[uri].post(json_escape(data.to_json), json_headers)
+        else
+          JSON.parse client[uri].post(nil, json_headers)
+        end
+      end
+    end
+
+    def patch(uri, data)
+      client_action do |client|
+        response = client[uri].patch(json_escape(data.to_json), json_headers)
+        if response && !response.empty?
+          JSON.parse(response)
+        else
+          true
+        end
+      end
+    end
+
+    def put(uri, data)
+      client_action do |client|
+        client[uri].put(json_escape(data.to_json), json_headers)
+      end
+    end
+
+    private
+
+    def client_action
+      raise Exceptions::APIClientNotConfigured unless configured?
+
+      yield connection
+    end
+
+    # Don't bother creating a connection until we need one
+    def connection
+      @connection ||= if authenticated?
+                        RestClient::Resource.new(api_uri.to_s, @username, @password)
+                      else
+                        RestClient::Resource.new(api_uri.to_s)
+                      end
+    end
+  end
+end

data/lib/skull_island/api_exception.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+module SkullIsland
+  # Generic Exception definition
+  class APIException < StandardError
+  end
+end

data/lib/skull_island/exceptions/api_client_not_configured.rb

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+module SkullIsland
+  module Exceptions
+    # The client must be configured before it can be used
+    class APIClientNotConfigured < APIException
+    end
+  end
+end

data/lib/skull_island/exceptions/immutable_modification.rb

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+module SkullIsland
+  module Exceptions
+    # Provided when an attempt is made to modify an immutable resource
+    class ImmutableModification < APIException
+    end
+  end
+end

data/lib/skull_island/exceptions/invalid_arguments.rb

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+module SkullIsland
+  module Exceptions
+    # Missing, incorrect argument(s) were passed
+    class InvalidArguments < APIException
+    end
+  end
+end

data/lib/skull_island/exceptions/invalid_cache_size.rb

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+module SkullIsland
+  module Exceptions
+    # Provided when a cache size is invalid
+    class InvalidCacheSize < APIException
+    end
+  end
+end

data/lib/skull_island/exceptions/invalid_options.rb

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+module SkullIsland
+  module Exceptions
+    # Missing, incorrect, or extra options were passed
+    class InvalidOptions < APIException
+    end
+  end
+end

data/lib/skull_island/exceptions/invalid_property.rb

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+module SkullIsland
+  module Exceptions
+    # Provided when property definitions use inappropriate names
+    class InvalidProperty < APIException
+    end
+  end
+end

data/lib/skull_island/exceptions/invalid_where_query.rb

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+module SkullIsland
+  module Exceptions
+    # Provided when a query is constructed but is invalid
+    class InvalidWhereQuery < APIException
+    end
+  end
+end

data/lib/skull_island/exceptions/new_instance_with_id.rb

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+module SkullIsland
+  module Exceptions
+    # ID can not be manually specified on resources
+    class NewInstanceWithID < APIException
+    end
+  end
+end

data/lib/skull_island/helpers/api_client.rb

@@ -0,0 +1,64 @@
+# frozen_string_literal: true
+
+module SkullIsland
+  module Helpers
+    # Simple helper methods for the API Client
+    module APIClient
+      def about_service
+        get '/'
+      end
+
+      def server_status
+        get '/status'
+      end
+
+      def cache(key)
+        symbolized_key = key.to_sym
+        if !@cache.has?(symbolized_key) && block_given?
+          result = yield(self)
+          @cache.store(symbolized_key, result)
+        elsif !@cache.has?(symbolized_key)
+          return nil
+        end
+        @cache.retrieve(symbolized_key)
+      end
+
+      def invalidate_cache_for(key)
+        symbolized_key = key.to_sym
+        @cache.invalidate(symbolized_key)
+      end
+
+      def lru_cache
+        @cache
+      end
+
+      # Substitute characters with their JSON-supported versions
+      # @return [String]
+      def json_escape(string)
+        json_escape = {
+          '&' => '\u0026',
+          '>' => '\u003e',
+          '<' => '\u003c',
+          '%' => '\u0025',
+          "\u2028" => '\u2028',
+          "\u2029" => '\u2029'
+        }
+        json_escape_regex = /[\u2028\u2029&><%]/u
+
+        string.to_s.gsub(json_escape_regex, json_escape)
+      end
+
+      # Provides access to the "raw" underlying rest-client
+      # @return [RestClient::Resource]
+      def raw
+        connection
+      end
+
+      # The API Client version (uses Semantic Versioning)
+      # @return [String]
+      def version
+        VERSION
+      end
+    end
+  end
+end

data/lib/skull_island/helpers/resource.rb

@@ -0,0 +1,178 @@
+# frozen_string_literal: true
+
+module SkullIsland
+  module Helpers
+    # Simple helper methods for Resources
+    module Resource
+      def datetime_from_params(params, actual_key)
+        DateTime.new(
+          params["#{actual_key}(1i)"].to_i,
+          params["#{actual_key}(2i)"].to_i,
+          params["#{actual_key}(3i)"].to_i,
+          params["#{actual_key}(4i)"].to_i,
+          params["#{actual_key}(5i)"].to_i
+        )
+      end
+
+      def fresh?
+        !tainted?
+      end
+
+      def host_regex
+        /^(([\w]|[\w][\w\-]*[\w])\.)*([\w]|[\w][\w\-]*[\w])$/
+      end
+
+      def id_property
+        self.class.properties.select { |_, opts| opts[:id_property] }.keys.first || 'id'
+      end
+
+      def id
+        @entity[id_property.to_s]
+      end
+
+      def immutable?
+        self.class.immutable?
+      end
+
+      # ActiveRecord ActiveModel::Name compatibility method
+      def model_name
+        self.class
+      end
+
+      def new?
+        !@entity.key?(id_property.to_s)
+      end
+
+      # ActiveRecord ActiveModel::Model compatibility method
+      def persisted?
+        !new?
+      end
+
+      def postprocess_created_at(value)
+        Time.at(value).utc.to_datetime
+      end
+
+      def postprocess_updated_at(value)
+        Time.at(value).utc.to_datetime
+      end
+
+      def properties
+        self.class.properties
+      end
+
+      def required_properties
+        properties.select { |_key, value| value[:required] }
+      end
+
+      def tainted?
+        @tainted ? true : false
+      end
+
+      # ActiveRecord ActiveModel::Conversion compatibility method
+      def to_key
+        new? ? [] : [id]
+      end
+
+      # ActiveRecord ActiveModel::Conversion compatibility method
+      def to_model
+        self
+      end
+
+      # ActiveRecord ActiveModel::Conversion compatibility method
+      def to_param
+        new? ? nil : id.to_s
+      end
+
+      def destroy
+        raise Exceptions::ImmutableModification if immutable?
+
+        unless new?
+          @api_client.delete(relative_uri.to_s)
+          @api_client.invalidate_cache_for(relative_uri.to_s)
+          @lazy = false
+          @tainted = true
+          @entity.delete('id')
+        end
+        true
+      end
+
+      def reload
+        if new?
+          # Can't reload a new resource
+          false
+        else
+          @api_client.invalidate_cache_for(relative_uri.to_s)
+          entity_data = @api_client.cache(relative_uri.to_s) do |client|
+            client.get(relative_uri.to_s)
+          end
+          @entity  = entity_data
+          @lazy    = false
+          @tainted = false
+          true
+        end
+      end
+
+      def save
+        saveable_data = prune_for_save(@entity)
+        validate_required_properties(saveable_data)
+
+        if new?
+          @entity  = @api_client.post(save_uri.to_s, saveable_data)
+          @lazy    = true
+        else
+          @api_client.invalidate_cache_for(relative_uri.to_s)
+          @entity = @api_client.put(relative_uri, saveable_data)
+        end
+        @tainted = false
+        true
+      end
+
+      def save_uri
+        self.class.relative_uri
+      end
+
+      # ActiveRecord ActiveModel compatibility method
+      def update(params)
+        new_params = {}
+        # need to convert multi-part datetime params
+        params.each do |key, value|
+          if /([^(]+)\(1i/.match?(key)
+            actual_key = key.match(/([^(]+)\(/)[1]
+            new_params[actual_key] = datetime_from_params(params, actual_key)
+          else
+            new_params[key] = value
+          end
+        end
+
+        new_params.each do |key, value|
+          setter_key = "#{key}=".to_sym
+          raise Exceptions::InvalidProperty unless respond_to?(setter_key)
+
+          send(setter_key, value)
+        end
+        save
+      end
+
+      def <=>(other)
+        if id < other.id
+          -1
+        elsif id > other.id
+          1
+        elsif id == other.id
+          0
+        else
+          raise Exceptions::InvalidArguments
+        end
+      end
+
+      def prune_for_save(data)
+        data.reject do |k, v|
+          k.to_sym == id_property ||
+            !properties[k.to_sym] ||
+            properties[k.to_sym][:read_only] ||
+            v.nil?
+        end
+      end
+    end
+  end
+end

data/lib/skull_island/helpers/resource_class.rb

@@ -0,0 +1,74 @@
+# frozen_string_literal: true
+
+module SkullIsland
+  module Helpers
+    # Simple helper class methods for Resource
+    module ResourceClass
+      # Determine a list of names to use to access a resource entity attribute
+      # @param original_name [String,Symbol] the name of the underlying attribute
+      # @param opts [Hash] property options as defined in a {Resource} subclass
+      # @return [Array<Symbol>] the list of names
+      def determine_getter_names(original_name, opts)
+        names = []
+        names << (opts[:type] == :boolean ? "#{original_name}?" : original_name)
+        if opts[:as]
+          Array(opts[:as]).each do |new_name|
+            names << (opts[:type] == :boolean ? "#{new_name}?" : new_name)
+          end
+        end
+        names.map(&:to_sym).uniq
+      end
+
+      # Determine a list of names to use to set a resource entity attribute
+      # @param original_name [String,Symbol] the name of the underlying attribute
+      # @param opts [Hash] property options as defined in a {Resource} subclass
+      # @return [Array<Symbol>] the list of names
+      def determine_setter_names(original_name, opts)
+        names = ["#{original_name}="]
+        names.concat(Array(opts[:as]).map { |new_name| "#{new_name}=" }) if opts[:as]
+        names.map(&:to_sym).uniq
+      end
+
+      # Produce a more human-readable representation of {#i18n_key}
+      # @note ActiveRecord ActiveModel::Name compatibility method
+      # @return [String]
+      def human
+        i18n_key.humanize
+      end
+
+      # Check if a resource class is immutable
+      def immutable?
+        @immutable ||= false
+      end
+
+      # A mock internationalization key based on the class name
+      # @note ActiveRecord ActiveModel::Name compatibility method
+      # @return [String]
+      def i18n_key
+        name.split('::').last.to_underscore
+      end
+
+      alias singular_route_key i18n_key
+
+      # A symbolized version of {#i18n_key}
+      # @note ActiveRecord ActiveModel::Name compatibility method
+      # @return [Symbol]
+      def param_key
+        i18n_key.to_sym
+      end
+
+      # All the properties defined for this Resource class
+      # @return [Hash{Symbol => Hash}]
+      def properties
+        @properties ||= {}
+      end
+
+      # A route key for building URLs
+      # @note ActiveRecord ActiveModel::Name compatibility method
+      # @return [String]
+      def route_key
+        i18n_key.en.plural
+      end
+    end
+  end
+end

data/lib/skull_island/lru_cache.rb

@@ -0,0 +1,175 @@
+# frozen_string_literal: true
+
+module SkullIsland
+  # A very simple Least Recently Used (LRU) cache implementation. Stores data
+  # in a Hash, uses a dedicated Array for storing and sorting keys (and
+  # implementing the LRU algorithm), and doesn't bother storing access
+  # information for cache data. It stores hit and miss counts for the
+  # entire cache (not for individual keys). It also uses three mutexes for
+  # thread-safety: a write lock, a read lock, and a metadata lock.
+  class LRUCache
+    attr_reader :max_size, :keys
+
+    # @raise [Exceptions::InvalidCacheSize] if the max_size isn't an Integer
+    def initialize(max_size = 100)
+      raise Exceptions::InvalidCacheSize unless max_size.is_a?(Integer)
+
+      @max_size     = max_size
+      @hits         = 0
+      @misses       = 0
+      @keys         = []
+      @data         = {}
+      @read_mutex   = Mutex.new
+      @write_mutex  = Mutex.new
+      @meta_mutex   = Mutex.new
+    end
+
+    # Does the cache contain the requested item?
+    # This doesn't count against cache misses
+    # @param key [Symbol] the index of the potentially cached object
+    def has?(key)
+      @meta_mutex.synchronize { @keys.include?(key) }
+    end
+
+    alias has_key? has?
+    alias include? has?
+
+    # The number of items in the cache
+    # @return [Fixnum] key count
+    def size
+      @meta_mutex.synchronize { @keys.size }
+    end
+
+    # Convert the contents of the cache to a Hash
+    # @return [Hash] the cached data
+    def to_hash
+      @read_mutex.synchronize { @data.dup }
+    end
+
+    # Return a raw Array of the cache data without its keys.
+    # Not particularly useful but it may be useful in the future.
+    # @return [Array] just the cached values
+    def values
+      @read_mutex.synchronize { @data.values }
+    end
+
+    # Allow iterating over the cached items, represented as key+value pairs
+    def each(&block)
+      to_hash.each(&block)
+    end
+
+    # Invalidate a cached item by its index / key. Returns `nil` if the object
+    # doesn't exist.
+    # @param key [Symbol] the cached object's index
+    def invalidate(key)
+      invalidate_key(key)
+      @write_mutex.synchronize { @data.delete(key) }
+    end
+
+    alias delete invalidate
+
+    # Remove all items from the cache without clearing statistics
+    # @return [Boolean] was the truncate operation successful?
+    def truncate
+      @read_mutex.synchronize do
+        @write_mutex.synchronize do
+          @meta_mutex.synchronize { @keys = [] }
+          @data = {}
+        end
+        @data.empty?
+      end
+    end
+
+    # Similar to {#truncate} (in fact, it calls it) but it also clears the
+    # statistical metadata.
+    # @return [Boolean] was the flush operation successful?
+    def flush
+      if truncate
+        @meta_mutex.synchronize do
+          @hits = 0
+          @misses = 0
+        end
+        true
+      else
+        false
+      end
+    end
+
+    # Provides a hash of the current metadata for the cache. It provides the
+    # current cache size (`:size`),the number of cache hits (`:hits`), and
+    # the number of cache misses (`:misses`).
+    # @return [Hash] cache statistics
+    def statistics
+      {
+        size: size,
+        hits: @meta_mutex.synchronize { @hits },
+        misses: @meta_mutex.synchronize { @misses }
+      }
+    end
+
+    # Store some data (`value`) indexed by a `key`. If an object exists with
+    # the same key, and the value is different, it will be overwritten.
+    # Storing a value causes its key to be moved to the end of the keys array
+    # (meaning it is the __most recently used__ item), and this happens on
+    # #store regardless of whether or not the key previously existed.
+    # This behavior is relied upon by {#retrieve} to allow reorganization of
+    # the keys without necessarily modifying the data it indexes.
+    # Uses recursion for overwriting existing items.
+    #
+    # @param key [Symbol] the index to use for referencing this cached item
+    # @param value [Object] the data to cache
+    def store(key, value)
+      if has?(key)
+        if @read_mutex.synchronize { @data[key] == value }
+          invalidate_key(key)
+          @meta_mutex.synchronize { @keys << key }
+          value
+        else
+          invalidate(key)
+          store(key, value)
+        end
+      else
+        invalidate(@keys.first) until size < @max_size
+
+        @write_mutex.synchronize do
+          @meta_mutex.synchronize { @keys << key }
+          @data[key] = value
+        end
+      end
+    end
+
+    alias []= store
+
+    # Retrieve an item from the cache. Returns `nil` if the item does not
+    # exist. Relies on {#store} returning the stored value to ensure the LRU
+    # algorithm is maintained safely.
+    # @param key [Symbol] the index to retrieve
+    def retrieve(key)
+      if has?(key)
+        @meta_mutex.synchronize { @hits += 1 }
+        # Looks dumb, but it actually only reorganizes the keys Array
+        store(key, @read_mutex.synchronize { @data[key] })
+      else
+        @meta_mutex.synchronize { @misses += 1 }
+        nil
+      end
+    end
+
+    alias [] retrieve
+
+    def marshal_dump
+      [@max_size, @hits, @misses, @keys, @data]
+    end
+
+    def marshal_load(array)
+      @max_size, @hits, @misses, @keys, @data = array
+    end
+
+    private
+
+    # Invalidate just the key of a cached item. Dangerous if used incorrectly.
+    def invalidate_key(key)
+      @meta_mutex.synchronize { @keys.delete(key) }
+    end
+  end
+end