atum 0.5.0

data/lib/atum/core/errors.rb

@@ -0,0 +1,20 @@
+module Atum
+  module Core
+    class SchemaError < StandardError; end
+
+    class ResponseError < StandardError; end
+
+    class ApiError < StandardError
+      attr_reader :error
+
+      def initialize(error)
+        @error = error
+        if @error.key?('documentation_url')
+          super("#{@error['message']}, see #{@error['documentation_url']}")
+        else
+          super("#{@error['message']}")
+        end
+      end
+    end
+  end
+end

data/lib/atum/core/link.rb

@@ -0,0 +1,77 @@
+require 'time'
+require 'active_support/inflector'
+require 'active_support/core_ext/hash/indifferent_access'
+
+module Atum
+  module Core
+    # A link invokes requests with an HTTP server.
+    class Link
+      # The amount limit is increased on each successive fetch in pagination
+      LIMIT_INCREMENT = 50
+
+      # Instantiate a link.
+      #
+      # @param url [String] The URL to use when making requests.  Include the
+      #   username and password to use with HTTP basic auth.
+      # @param link_schema [LinkSchema] The schema for this link.
+      # @param options [Hash] Configuration for the link.  Possible keys
+      #   include:
+      #   - default_headers: Optionally, a set of headers to include in every
+      #     request made by the client.  Default is no custom headers.
+      def initialize(url, link_schema, options = {})
+        root_url, @path_prefix = unpack_url(url)
+        @connection = Faraday.new(url: root_url)
+        @link_schema = link_schema
+        @headers = options[:default_headers] || {}
+      end
+
+      # Make a request to the server.
+      #
+      # @param parameters [Array] The list of parameters to inject into the
+      #   path.  A request body can be passed as the final parameter and will
+      #   always be converted to JSON before being transmitted.
+      # @raise [ArgumentError] Raised if either too many or too few parameters
+      #   were provided.
+      # @return [String,Object,Enumerator] A string for text responses, an
+      #   object for JSON responses, or an enumerator for list responses.
+      def run(*parameters)
+        options = parameters.pop
+        raise ArgumentError, 'options must be a hash' unless options.is_a?(Hash)
+
+        options = default_options.deep_merge(options)
+        path = build_path(*parameters)
+        Request.new(@connection, @link_schema.method, path, options).request
+      end
+
+      private
+
+      def default_options
+        {
+          headers: @headers,
+          envelope_name: @link_schema.resource_schema.name.pluralize
+        }
+      end
+
+      def build_path(*parameters)
+        @path_prefix + @link_schema.construct_path(*parameters)
+      end
+
+      def apply_link_schema(hash)
+        definitions = @link_schema.resource_schema.definitions
+        hash.each do |k, v|
+          next unless definitions.fetch(k, {}).fetch('format', nil)
+          case definitions[k]['format']
+          when 'date-time'
+            hash[k] = Time.parse(v) unless v.nil?
+          end
+        end
+        hash
+      end
+
+      def unpack_url(url)
+        path = URI.parse(url).path
+        [URI.join(url).to_s, path == '/' ? '' : path]
+      end
+    end
+  end
+end

data/lib/atum/core/paginator.rb

@@ -0,0 +1,32 @@
+module Atum
+  module Core
+    class Paginator
+      LIMIT_INCREMENT = 50
+
+      def initialize(request, initial_response, options)
+        @request = request
+        @options = options
+        @initial_response = initial_response
+      end
+
+      def enumerator
+        response = @initial_response
+        Enumerator.new do |yielder|
+          loop do
+            items = @request.unenvelope(response.body)
+            items.each { |item| yielder << item }
+
+            break if items.count < response.limit
+
+            new_options = @options.dup
+            new_options[:query] = @options.fetch(:query, {})
+            new_options[:query].merge!(after: response.meta['cursors']['after'],
+                                       limit: response.limit + LIMIT_INCREMENT)
+
+            response = @request.make_request(new_options)
+          end
+        end.lazy
+      end
+    end
+  end
+end

data/lib/atum/core/request.rb

@@ -0,0 +1,55 @@
+module Atum
+  module Core
+    class Request
+      def initialize(connection, method, path, options)
+        @connection = connection
+        @method = method
+        @path = path
+        @headers = options[:headers] || {}
+        @body = options[:body] || nil
+        @query = options[:query] || {}
+        @envelope_name = options[:envelope_name] || 'data'
+      end
+
+      def request
+        response = Response.new(make_request)
+        return response.body unless response.json?
+
+        if response.limit.nil?
+          unenvelope(response.body)
+        else
+          Paginator.new(self, response, options).enumerator
+        end
+      end
+
+      def make_request(opts = options)
+        body = opts[:body]
+        headers = opts.fetch(:headers, {})
+        query = opts[:query]
+
+        # TODO: Not sure this is required in faraday 0.9.0
+        if body.is_a?(Hash)
+          body = body.to_json
+          headers['Content-Type'] ||= 'application/json'
+        end
+
+        @connection.send(@method) do |request|
+          request.url @path
+          request.body = body
+          request.params = query
+          request.headers.merge!(headers)
+        end
+      end
+
+      def unenvelope(body)
+        body[@envelope_name] || body['data']
+      end
+
+      private
+
+      def options
+        { headers: @headers, body: @body, query: @query }
+      end
+    end
+  end
+end

data/lib/atum/core/resource.rb

@@ -0,0 +1,15 @@
+module Atum
+  module Core
+    # A resource with methods mapped to API links.
+    class Resource
+      # Instantiate a resource.
+      #
+      # @param links [Hash<String,Link>] A hash that maps method names to links.
+      def initialize(links)
+        links.each do |name, link|
+          define_singleton_method(name) { |*args| link.run(*args) }
+        end
+      end
+    end
+  end
+end

data/lib/atum/core/response.rb

@@ -0,0 +1,53 @@
+module Atum
+  module Core
+    class Response
+      def initialize(response)
+        @response = response
+      end
+
+      def body
+        json? ? handle_json : handle_raw
+      end
+
+      def json?
+        content_type = @response.headers['Content-Type'] ||
+                       @response.headers['content-type'] || ''
+        content_type.include?('application/json')
+      end
+
+      def error?
+        @response.status >= 400
+      end
+
+      def meta
+        unless json?
+          raise ResponseError, 'Cannot fetch meta for non JSON response'
+        end
+
+        json_body.fetch('meta', {})
+      end
+
+      def limit
+        meta.fetch('limit', nil)
+      end
+
+      private
+
+      def json_body
+        @json_body ||= JSON.parse(@response.body).with_indifferent_access
+      end
+
+      def raw_body
+        @response.body
+      end
+
+      def handle_json
+        error? ? raise(ApiError, json_body['error']) : json_body
+      end
+
+      def handle_raw
+        error? ? raise(ApiError) : raw_body
+      end
+    end
+  end
+end

data/lib/atum/core/schema.rb

@@ -0,0 +1,12 @@
+module Atum
+  module Core
+    module Schema
+    end
+  end
+end
+
+require 'atum/core/schema/api_schema'
+require 'atum/core/schema/link_schema'
+require 'atum/core/schema/resource_schema'
+require 'atum/core/schema/parameter'
+require 'atum/core/schema/parameter_choice'

data/lib/atum/core/schema/api_schema.rb

@@ -0,0 +1,62 @@
+module Atum
+  module Core
+    module Schema
+      class ApiSchema
+        attr_reader :schema
+
+        def initialize(schema)
+          @schema = schema
+        end
+
+        # Description of the API
+        def description
+          @schema['description']
+        end
+
+        # Get the schema for a resource.
+        #
+        # @param name [String] The name of the resource.
+        # @raise [SchemaError] Raised if an unknown resource name is provided.
+        # @return ResourceSchema The resource schema for resource called name
+        def resource_schema_for(name)
+          unless resource_schema_hash.key?(name)
+            raise SchemaError, "Unknown resource '#{name}'."
+          end
+
+          resource_schema_hash[name]
+        end
+
+        # @return [Array<ResourceSchema>] The resource schemata in this API.
+        def resource_schemas
+          resource_schema_hash.values
+        end
+
+        # Get a simple human-readable representation of this client instance.
+        def inspect
+          "#<Atum::ApiSchema description=\"#{description}\">"
+        end
+
+        alias_method :to_s, :inspect
+
+        # Lookup a path in this schema.
+        #
+        # @param path [Array<String>] Array of keys, one for each to look up in
+        #   the schema
+        # @return [Object] Value at the specifed path in this schema.
+        def lookup_path(*path)
+          path.reduce(@schema) { |a, e| a[e] }
+        end
+
+        private
+
+        def resource_schema_hash
+          @resource_schema_hash ||= Hash[
+            @schema['definitions'].map do |key, value|
+              [key, ResourceSchema.new(self, value, key)]
+            end
+          ]
+        end
+      end
+    end
+  end
+end

data/lib/atum/core/schema/link_schema.rb

@@ -0,0 +1,121 @@
+module Atum
+  module Core
+    module Schema
+      class LinkSchema
+        attr_reader :resource_schema
+
+        # @param api_schema [ApiSchema] The schema for the whole API
+        # @param resource_schema [ResourceSchema] The schema of the resource this
+        # link belongs to.
+        # @param link_schema [Hash] The link's schema
+        def initialize(api_schema, resource_schema, link_schema_hash)
+          @api_schema = api_schema
+          @resource_schema = resource_schema
+          @link_schema_hash = link_schema_hash
+        end
+
+        def name
+          @link_schema_hash['title'].downcase.gsub(' ', '_')
+        end
+
+        def description
+          @link_schema_hash['description']
+        end
+
+        def method
+          @link_schema_hash['method'].downcase.to_sym
+        end
+
+        def needs_request_body?
+          @link_schema_hash.key?('schema')
+        end
+
+        # Get the parameters this link expects.
+        #
+        # @param parameters [Array] The names of the parameter definitions to
+        #   convert to parameter names.
+        # @return [Array<Parameter|ParameterChoice>] A list of parameter instances
+        #   that represent parameters to be injected into the link URL.
+        def parameters
+          expected_params.map do |parameter|
+            # URI decode parameters and strip the leading '{(' and trailing ')}'.
+            parameter = URI.unescape(parameter[2..-3])
+            generate_parameter(parameter)
+          end
+        end
+
+        # Construct the URL and body for a call to this link
+        #
+        # @param params [Array] The list of parameters to inject into the
+        #   path.
+        # @raise [ArgumentError] Raised if either too many or too few parameters
+        #   were provided.
+        # @return [String,Object] A path and request body pair.  The body value is
+        #   nil if a payload wasn't included in the list of parameters.
+        def construct_path(*params)
+          if expected_params.count != params.count
+            raise ArgumentError, "Wrong number of arguments: #{params.count} " \
+                                 "for #{expected_params.count}"
+          end
+
+          href.gsub(PARAMETER_REGEX) { |_match| format_parameter(params.shift) }
+        end
+
+        private
+
+        # Match parameters in definition strings.
+        PARAMETER_REGEX = /\{\([%\/a-zA-Z0-9_-]*\)\}/
+
+        def href
+          @link_schema_hash['href']
+        end
+
+        def expected_params
+          href.scan(PARAMETER_REGEX)
+        end
+
+        # Unpack an 'anyOf' or 'oneOf' multi-parameter blob.
+        #
+        # @param parameters [Array<Hash>] An array of hashes containing '$ref'
+        #   keys and definition values.
+        # @return [Array<Parameter>] An array of parameters extracted from the
+        #   blob.
+        def unpack_multi_params(parameters)
+          parameters.map { |info| generate_parameter(info['$ref']) }
+        end
+
+        def generate_parameter(param)
+          path = param.split('/')[1..-1]
+          name = path[-1]
+          resource_name = path.size > 2 ? path[1] : nil
+          info = @api_schema.lookup_path(*path)
+          description = info['description']
+
+          if info.key?('anyOf')
+            ParameterChoice.new(resource_name, unpack_multi_params(info['anyOf']))
+          elsif info.key?('oneOf')
+            ParameterChoice.new(resource_name, unpack_multi_params(info['oneOf']))
+          else
+            Parameter.new(resource_name, name, description)
+          end
+        end
+
+        # Convert a path parameter to a format suitable for use in a path.
+        #
+        # @param [Fixnum,String,TrueClass,FalseClass,Time] The parameter to format.
+        # @return [String] The formatted parameter.
+        def format_parameter(parameter)
+          parameter.instance_of?(Time) ? iso_format(parameter) : parameter.to_s
+        end
+
+        # Convert a time to an ISO 8601 combined data and time format.
+        #
+        # @param time [Time] The time to convert to ISO 8601 format.
+        # @return [String] An ISO 8601 date in `YYYY-MM-DDTHH:MM:SSZ` format.
+        def iso_format(time)
+          time.getutc.iso8601
+        end
+      end
+    end
+  end
+end