ALD 0.1.0 → 0.1.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 445063876e8fc4783ef501709c428536506a6dd2
-  data.tar.gz: dada4d739c9e78df7e9d5137ba84fe041fe97303
+  metadata.gz: df517c6ce5077f688d4b97fadcfa88c435007098
+  data.tar.gz: 43279871802cbc8bd078f8cf5b6f07a193988c73
 SHA512:
-  metadata.gz: bda2ebf48adbcf07d5a9e8b7daea6f82d46d5d4e9d26bf2863b2e9fd73c41c0be14e4836b22b655ad3aebef1cb461129f31f8f67e380fbca9eb173a17a1aed30
-  data.tar.gz: e4d7807db45aba618920471ae6406193e268ebfdd905bd2bb4f51b237c6538589e8740231c4efec5818690fc250c81ed26797b76203077a1e8fb842250dbd22f
+  metadata.gz: a4d738c9afd6f50106cbc3c0422c84e53a7ce1c287c0abe1cd10bb544778c1ac114b3b7dbeeeb285e404054c6c542c6604d1d02fa6b229f839bb7deac70dbc5c
+  data.tar.gz: 4806c2dd60bc0a75ccc8d3b5f1aa7e788bc1063a1bf92810be1d107c3647c0363a007bbeefc82ae4b7b7bc8cbf05e53e262a4c3b7bb2db8156926e4f95dc2d99

data/lib/ALD/api.rb

@@ -0,0 +1,285 @@
+require_relative 'item_collection'
+require_relative 'user_collection'
+require_relative 'item'
+require_relative 'user'
+require_relative 'exceptions'
+
+require 'net/http'
+require 'net/http/digest_auth'
+require 'json'
+
+module ALD
+  # Public: Access the ALD API programatically.
+  class API
+
+    # Public: Create a new instance to access an ALD server.
+    #
+    # root_url - a String pointing to the root URL of the server's API.
+    #
+    # Example
+    #
+    #   api = ALD::API.new('http://api.my_ald_server.com/v1/')
+    def initialize(root_url)
+      @root_url = URI(root_url)
+      @item_store, @user_store = {}, {}
+    end
+
+    # Public: Get current authentication information Hash (see #auth=)
+    attr_reader :auth
+
+    # Public: Set authentication information for future requests.
+    #
+    # auth - a Hash containing the authentication information:
+    #        :name     - the user name to use
+    #        :password - the plaintext password to use
+    #
+    # Returns the hash that was passed.
+    #
+    # Raises ArgumentError if the passed hash does not have the specified keys.
+    def auth=(auth)
+      raise ArgumentError unless valid_auth?(auth)
+      @auth = auth
+    end
+
+    # Public: Get a collection of items from this server. This calls
+    # ItemCollection#where on the collection of all items. This method might
+    # trigger a HTTP request.
+    #
+    # conditions - a Hash of conditions the items should meet.
+    #              Valid conditions are documented at ItemCollection#where.
+    #
+    # Example
+    #
+    #   api.items.each { |i| puts i.name }
+    #   api.items(name: 'MyApp') # equivalent to api.items.where(name: 'MyApp')
+    #
+    # Returns an ALD::API::ItemCollection containing the items.
+    #
+    # Raises ArgumentError if the specified conditions are invalid.
+    def items(conditions = nil)
+      @all_items ||= ItemCollection.new(self)
+      @all_items.where(conditions)
+    end
+
+    # Public: Get a collection of users on this server. This calls
+    # UserCollection#where on the collection of all users. This method might
+    # trigger a HTTP request.
+    #
+    # conditions - a Hash of conditions the users should meet.
+    #              Valid conditions are documented at UserCollection#where.
+    #
+    # Returns an ALD::API::UserCollection containing the users.
+    def users(conditions = nil)
+      @all_users ||= UserCollection.new(self)
+      @all_users.where(conditions)
+    end
+
+    # Public: Get the API version supported by the server. This method triggers a HTTP
+    # request.
+    #
+    # Returns the semver version string of the API.
+    def version
+      @version ||= request('/version')['version']
+    end
+
+    # Public: Get an individual item. This method is roughly equivalent to calling
+    # ItemCollection#[] on API#items. Calling this method might trigger a HTTP
+    # request.
+    #
+    # Examples
+    #
+    #   api.item('185d265f24654545aad3f88e8a383339')
+    #   api.item('MyApp', '0.9.5')
+    #
+    #   # unlike ItemCollection#[], this also supports passing a Hash (and a Boolean):
+    #   api.item({'id' => '185d265f24654545aad3f88e8a383339',
+    #            'name' => 'MyApp',
+    #            'version' => '4.5.6'})
+    #   # However, this last form is only meant to be used internally and should
+    #   # never be called by library consumers.
+    #
+    # Returns the ALD::API::Item instance representing the item, or nil if not
+    # found.
+    #
+    # Raises ArgumentError if the arguments are not of one of the supported forms.
+    #
+    # Signature
+    #
+    #   item(id)
+    #   item(name, version)
+    #
+    # id      - the GUID String of the item to return
+    # name    - a String containing the item's name
+    # version - a String containing the item's semver version
+    def item(*args)
+      if args.first.is_a? Hash # used internally to avoid multiple Item instances
+        args.first['id'] = normalize_id(args.first['id'])
+        @item_store[args.first['id']] ||= Item.new(self, *args)
+      elsif args.length == 1 && args.first.is_a?(String) # GUID
+        @item_store[normalize_id(args.first)] || items[args.first]
+      elsif args.length == 2 # name and version
+        items[*args]
+      else
+        raise ArgumentError
+      end
+    end
+
+    # Public: Get an individual user. This method is roughly equivalent to calling
+    # UserCollection#[] on API#users. Calling this method might trigger a HTTP
+    # request.
+    #
+    # Examples
+    #
+    #   api.user('6a309ac8a4304f5cb1e6a2982f680ca5')
+    #   api.user('Bob')
+    #
+    #   # As #item, this method also supports being passed a Hash (and a Boolean),
+    #   # which should only be used internally.
+    #
+    # Returns the ALD::API::User instance representing the user, or nil if not
+    # found.
+    #
+    # Raises ArgumentError if the arguments are not of one of the supported forms.
+    #
+    # Signature
+    #
+    #   user(id)
+    #   user(name)
+    #
+    # id   - a 32-character GUID string containing the user's ID
+    # name - a String containing the user's name
+    def user(*args)
+      if args.first.is_a? Hash # used internally to avoid multiple User instances
+        args.first['id'] = normalize_id(args.first['id'])
+        @user_store[args.first['id']] ||= User.new(self, *args)
+      elsif args.length == 1 && args.first.is_a?(String)
+        @user_store[normalize_id(args.first)] || users[args.first]
+      else
+        raise ArgumentError
+      end
+    end
+
+    # Internal: Given a GUID string, bring it into a standardized form. This
+    # is used internally to make comparing GUIDs easier.
+    #
+    # id - the GUID String to normalize
+    #
+    # Returns the normalized GUID String.
+    def normalize_id(id)
+      id.upcase.gsub(/[^0-9A-F]/, '')
+    end
+
+    # Internal: The default headers to be used in #request.
+    DEFAULT_HEADERS = {
+      'Accept' => 'application/json'
+    }
+
+    # Internal: Make a raw request to the ALD server. This is used internally,
+    # and library consumers should only call it if they are familiar with the
+    # ALD API.
+    #
+    # url     - the URL String, relative to the root URL, to request against.
+    # method  - a Symbol indicating the HTTP method to use. Supported: :get, :post
+    # headers - a Hash containing additional headers (for the defaults see
+    #           ::DEFAULT_HEADERS).
+    # body    - If method is :post, a request body to use.
+    #
+    # Returns The response body; as Hash / Array if the 'Content-type' header
+    # indicates a JSON response; as raw String otherwise.
+    #
+    # Raises ArgumentError is method is not supported.
+    #
+    # Raises API::RequestError if the response code is not in (200...300).
+    def request(url, method = :get, headers = {}, body = nil)
+      Net::HTTP.start(@root_url.host, @root_url.port) do |http|
+        url = @root_url + url
+
+        request = create_request(method, url)
+        DEFAULT_HEADERS.merge(headers).each do |k, v|
+          request[k] = v
+        end
+
+        response = http.request(request)
+        response = request_with_auth(http, request, url, response) if response.code.to_i == 401
+
+        raise RequestError unless (200...300).include?(response.code.to_i)
+        if response['Content-type'].include?('application/json')
+          JSON.parse(response.body)
+        else
+          response.body
+        end
+      end
+    end
+
+    private
+
+    # Internal: Create a new Net::HTTPRequest for the given method.
+    #
+    # method - a Symbol indicating the HTTP verb (lowercase
+    # url    - the URI to request
+    #
+    # Returns a Net::HTTPRequest for the given method.
+    #
+    # Raises ArgumentError if the verb is not supported.
+    def create_request(method, url)
+      case method
+        when :get
+          Net::HTTP::Get.new url.request_uri
+        when :post
+          Net::HTTP::Post.new url.request_uri
+        else
+          raise ArgumentError
+      end
+    end
+
+    # Internal: Retry a request with authentication
+    #
+    # http            - a Net::HTTP object to use for the request
+    # request         - the Net::HTTPRequest to use
+    # url             - the URI that is requested
+    # failed_response - the response that was given when requesting without auth
+    #
+    # Returns a successful Net::HTTPResponse for the request.
+    #
+    # Raises NoAuthError if @auth is not set.
+    #
+    # Raises UnsupportedAuthMethodError if the server uses a not supported auth
+    # method.
+    #
+    # Raises InvalidAuthError if the authenticated request yields a 401 response.
+    def request_with_auth(http, request, url, failed_response)
+      raise NoAuthError if @auth.nil?
+      case auth_method(failed_response)
+        when :basic
+          request.basic_auth(@auth[:name], @auth[:password])
+        when :digest
+          url.user, url.password = @auth[:name], @auth[:password]
+          request.add_field 'Authorization', Net::HTTP::DigestAuth.new.auth_header(url, failed_response['WWW-Authenticate'], request.method)
+        else
+          raise UnsupportedAuthMethodError
+      end
+
+      response = http.request(request)
+      raise InvalidAuthError if response.code.to_i == 401
+      response
+    end
+
+    # Internal: Get the authentication method used by a server
+    #
+    # response - the Net::HTTPResponse to examine
+    #
+    # Returns the used method as Symbol, e.g. :digest or :basic
+    def auth_method(response)
+      response['WWW-Authenticate'].strip.split(' ')[0].downcase.to_sym
+    end
+
+    # Internal: Check if a Hash contains valid auth data
+    #
+    # auth - the Hash to check
+    #
+    # Returns true, if the Hash contains the necessary keys, false otherwise.
+    def valid_auth?(auth)
+      auth.is_a?(Hash) && %w[name password].all? { |k| auth.key?(k.to_sym) }
+    end
+  end
+end

data/lib/ALD/collection.rb

@@ -0,0 +1,96 @@
+module ALD
+  class API
+    # Internal: Base class for collections of entries returned by a request to
+    # the ALD API.
+    #
+    # Child classes inheriting from this class must support:
+    #
+    #   @data                  - Array of Hashes necessary to create a new
+    #                            entry of this collection, initially nil
+    #   #entry_filter          - From the given argument array, make a filter
+    #                            Hash that identifies the entry indicated by
+    #                            the arguments.
+    #   #entry(hash, complete) - create a new entry from the given Hash
+    #   #request               - load the @data Array
+    #   #request_entry(filter) - From the given filter Hash, load all
+    #                            information regarding the entry identified by
+    #                            it.
+    class Collection
+
+      # This class includes the Enumerable module.
+      include Enumerable
+
+      # Internal: Create a new Collection
+      #
+      # api        - the ALD::API instance this collection belongs to
+      # conditions - a Hash of conditions entries in this collection must meet
+      # data       - an Array of Hashes for @data. May be nil.
+      def initialize(api, conditions = {}, data = nil)
+        @api, @conditions, @data = api, conditions, data
+      end
+
+      # Public: Iterate over the entries in this collection
+      #
+      # Yields an entry, as returned by #entry
+      def each
+        request unless initialized?
+        @data.each do |hash|
+          yield entry(hash)
+        end
+      end
+
+      # Internal: Access an entry in the collection.
+      #
+      # Actual arguments and behaviour depends on child classes.
+      #
+      # Returns an entry of the collection, or nil if none is found.
+      #
+      # Raises ArgumentError if the given arguments are invalid.
+      def [](*args)
+        if args.length == 1 && args.first.is_a?(Integer)
+          request unless initialized?
+          entry(@data[args.first])
+        else
+          filter = entry_filter(args)
+
+          if initialized?
+            entry = @data.find { |hash| filter.keys.all? { |k| hash[k.to_s] == filter[k] } }
+            full_entry = false
+          else
+            entry = request_entry(filter)
+            full_entry = true
+          end
+
+          entry.nil? ? nil : entry(entry, full_entry)
+        end
+      end
+
+      # Public: Indicate if all data in this collection is present. If false,
+      # accessing an entry or iterating over entries in this collection may
+      # trigger a HTTP request.
+      #
+      # Returns a Boolean; true if all data is present, false otherwise
+      def initialized?
+        !@data.nil?
+      end
+
+      private
+
+      # Internal: Get filter conditions for an entry. Used by #[] to get an
+      # entry based on the given arguments.
+      #
+      # This method is a mere placeholder. Child classes must override it to
+      # implement their access semantics for entries.
+      #
+      # args - an Array of arguments to convert into conditions
+      #
+      # Returns the Hash of conditions, where each key represents a property
+      # of the entry to be found that must equal the corresponding value.
+      #
+      # Raises ArgumentError if the arguments cannot be converted.
+      def entry_filter(args)
+        {}
+      end
+    end
+  end
+end

data/lib/ALD/collection_entry.rb

@@ -0,0 +1,77 @@
+module ALD
+  class API
+    # Internal: Base class for entries in a collection returned by the ALD API.
+    # This class is used internally and should not be called by library
+    # consumers.
+    #
+    # Child classes inheriting from this class must support:
+    #
+    #   @data        - a Hash containing the entry's data
+    #   @initialized - a Boolean indicating whether @data is yet complete or
+    #                  not
+    #   #request     - load missing information into @data
+    class CollectionEntry
+      # Internal: Create a new entry with the given data
+      #
+      # api         - the ALD:API instance this entry belongs to
+      # data        - the initial, possibly uncomplete @data hash
+      # initialized - a Boolean indicating whether data is already complete or
+      #               not
+      def initialize(api, data, initialized = false)
+        @api, @data, @initialized = api, data, initialized
+        self.class.define_attributes!
+      end
+
+      # Public: Indicate whether all data concerning this entry is available
+      # or not. If false, a property retrieval from this entry *may* trigger a
+      # HTTP request.
+      #
+      # Returns a Boolean, true if all data is present, false otherwise.
+      def initialized?
+        @initialized
+      end
+
+      # Internal: Child classes override this to specify attributes that are
+      # always present in @data. For each such attribute, a retrieval method is
+      # dynamically defined.
+      #
+      # Returns an Array of attribute names (String)
+      def self.initialized_attributes
+        []
+      end
+
+      # Internal: Child classes override this to specify attributes that are
+      # *not* always present in @data. For each such attribute, a retrieval
+      # method including a call to #request is dynamically defined.
+      #
+      # Returns an Array of attribute names (String)
+      def self.requested_attributes
+        []
+      end
+
+      # Internal: Dynamically define attributes determined by child classes.
+      # This is called by ::new to define the attributes child classes define
+      # in ::initialized_attributes and ::requested_attributes.
+      #
+      # Returns nothing.
+      def self.define_attributes!
+        return if @attributes_defined
+
+        initialized_attributes.each do |attr|
+          self.send(:define_method, attr.to_sym) do
+            @data[attr]
+          end
+        end
+
+        requested_attributes.each do |attr|
+          self.send(:define_method, attr.to_sym) do
+            request unless initialized?
+            @data[attr]
+          end
+        end
+
+        @attributes_defined = true
+      end
+    end
+  end
+end