apia 3.0.0

data/lib/apia/object_set.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+require 'set'
+
+module Apia
+  class ObjectSet < ::Set
+
+    def add_object(object)
+      return self if include?(object)
+
+      self << object
+      if object.respond_to?(:collate_objects)
+        # Attempt to add any other objects if the object responds to
+        # collate_objects.
+        object.collate_objects(self)
+      end
+      self
+    end
+
+  end
+end

data/lib/apia/pagination_object.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+require 'apia/object'
+require 'apia/scalars/integer'
+require 'apia/scalars/boolean'
+
+module Apia
+  class PaginationObject < Apia::Object
+
+    name 'Pagination Details'
+    description 'Provides information about how data has been paginated'
+
+    field :current_page, type: Scalars::Integer do
+      description 'The current page'
+    end
+
+    field :total_pages, type: Scalars::Integer, null: true do
+      description 'The total number of pages'
+    end
+
+    field :total, type: Scalars::Integer, null: true do
+      description 'The total number of items across all pages'
+    end
+
+    field :per_page, type: Scalars::Integer do
+      description 'The number of items per page'
+    end
+
+    field :large_set, type: Scalars::Boolean do
+      description 'Is this a large set and therefore the total number of records cannot be returned?'
+    end
+
+  end
+end

data/lib/apia/polymorph.rb

@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+
+require 'apia/helpers'
+require 'apia/defineable'
+require 'apia/definitions/polymorph'
+require 'apia/errors/invalid_polymorph_value_error'
+
+module Apia
+  class Polymorph
+
+    extend Defineable
+
+    class << self
+
+      # Return the definition for this polymorph
+      #
+      # @return [Apia::Definitions::Polymorph]
+      def definition
+        @definition ||= Definitions::Polymorph.new(Helpers.class_name_to_id(name))
+      end
+
+      # Collate all objects that this polymorph references and add them to the
+      # given object set
+      #
+      # @param set [Apia::ObjectSet]
+      # @return [void]
+      def collate_objects(set)
+        definition.options.each_value do |opt|
+          set.add_object(opt.type.klass) if opt.type.usable_for_field?
+        end
+      end
+
+      # Return the type which should be returned for the given value by running
+      # through each of the matchers to find the appropriate type.
+      def option_for_value(value)
+        option = definition.options.values.find do |opt|
+          opt.matches?(value)
+        end
+
+        if option.nil?
+          raise InvalidPolymorphValueError.new(self, value)
+        end
+
+        option
+      end
+
+    end
+
+  end
+end

data/lib/apia/rack.rb

@@ -0,0 +1,184 @@
+# frozen_string_literal: true
+
+require 'json'
+require 'apia/rack_error'
+require 'apia/request'
+require 'apia/response'
+
+module Apia
+  class Rack
+
+    def initialize(app, api, namespace, **options)
+      @app = app
+      @api = api
+      @namespace = '/' + namespace.sub(/\A\/+/, '').sub(/\/+\z/, '')
+      @options = options
+    end
+
+    # Is this supposed to be running in development? This will validate the whole
+    # API on each request as well as being more verbose about internal server
+    # errors that are encountered.
+    #
+    # @return [Boolean]
+    def development?
+      env_is_dev = ENV['RACK_ENV'] == 'development'
+      return true if env_is_dev && @options[:development].nil?
+
+      @options[:development] == true
+    end
+
+    # Parse a given full path and return nil if it doesn't match our
+    # namespace or return a hash with the controller and endpoint
+    # named as available.
+    #
+    # @param path [String] /core/v1/controller/endpoint
+    # @return [nil, Hash]
+    def find_route(method, path)
+      return if api.nil?
+
+      api.definition.route_set.find(method.to_s.downcase.to_sym, path).first
+    end
+
+    # Return the API object
+    #
+    # @return [Apia::API]
+    def api
+      return Object.const_get(@api) if @api.is_a?(String) && development?
+      return @cached_api ||= Object.const_get(@api) if @api.is_a?(String)
+
+      @api
+    end
+
+    # Actually make the request
+    #
+    # @param env [Hash]
+    # @return [Array] a rack triplet
+    def call(env)
+      if @options[:hosts]&.none? { |host| host == env['HTTP_HOST'] }
+        return @app.call(env)
+      end
+
+      unless env['PATH_INFO'] =~ /\A#{Regexp.escape(@namespace)}\/([a-z].*)\z/i
+        return @app.call(env)
+      end
+
+      api_path = Regexp.last_match(1)
+
+      triplet = handle_request(env, api_path)
+      add_cors_headers(env, triplet)
+      triplet
+    end
+
+    private
+
+    def handle_request(env, api_path)
+      if env['REQUEST_METHOD'].upcase == 'OPTIONS'
+        return [204, {}, ['']]
+      end
+
+      validate_api if development?
+
+      route = find_route(env['REQUEST_METHOD'], api_path)
+      if route.nil?
+        raise RackError.new(404, 'route_not_found', "No route matches '#{api_path}' for #{env['REQUEST_METHOD']}")
+      end
+
+      request = Apia::Request.new(env)
+      request.api_path = api_path
+      request.namespace = @namespace
+      request.api = api
+      request.controller = route.controller
+      request.endpoint = route.endpoint
+      request.route = route
+
+      response = request.endpoint.execute(request)
+      response.rack_triplet
+    rescue ::StandardError => e
+      if e.is_a?(RackError) || e.is_a?(Apia::ManifestError)
+        return e.triplet
+      end
+
+      api.definition.exception_handlers.call(e, {
+        env: env,
+        api: api,
+        request: defined?(request) ? request : nil
+      })
+
+      if development?
+        return triplet_for_exception(e)
+      end
+
+      self.class.error_triplet('unhandled_exception', status: 500)
+    end
+
+    def validate_api
+      api.validate_all.raise_if_needed
+    end
+
+    def triplet_for_exception(exception)
+      self.class.error_triplet(
+        'unhandled_exception',
+        description: 'This is an exception that has occurred and not been handled.',
+        detail: {
+          class: exception.class.name,
+          message: exception.message,
+          backtrace: exception.backtrace
+        },
+        status: 500
+      )
+    end
+
+    # Add cross origin headers to the response triplet
+    #
+    # @param env [Hash]
+    # @param triplet [Array]
+    # @return [void]
+    def add_cors_headers(env, triplet)
+      triplet[1]['Access-Control-Allow-Origin'] = '*'
+      triplet[1]['Access-Control-Allow-Methods'] = '*'
+      if env['HTTP_ACCESS_CONTROL_REQUEST_HEADERS']
+        triplet[1]['Access-Control-Allow-Headers'] = env['HTTP_ACCESS_CONTROL_REQUEST_HEADERS']
+      end
+
+      true
+    end
+
+    class << self
+
+      # Return a JSON-ready triplet for the given body.
+      #
+      # @param body [Hash, Array]
+      # @param status [Integer]
+      # @param headers [Hash]
+      # @return [Array]
+      def json_triplet(body, status: 200, headers: {})
+        body_as_json = body.to_json
+        [
+          status,
+          headers.merge('content-type' => 'application/json', 'content-length' => body_as_json.bytesize.to_s),
+          [body_as_json]
+        ]
+      end
+
+      # Return a triplet for a given error using the standard error schema
+      #
+      # @param code [String]
+      # @param description [String]
+      # @param detail [Hash]
+      # @param status [Integer]
+      # @param headers [Hash]
+      # @return [Array]
+      def error_triplet(code, description: nil, detail: {}, status: 500, headers: {})
+        json_triplet({
+                       error: {
+                         code: code,
+                         description: description,
+                         detail: detail
+                       }
+                     }, status: status, headers: headers.merge('x-api-schema' => 'json-error'))
+      end
+
+    end
+
+  end
+end

data/lib/apia/rack_error.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+module Apia
+  class RackError < StandardError
+
+    def initialize(http_status, code, message)
+      @http_status = http_status
+      @code = code
+      @message = message
+    end
+
+    def triplet
+      Rack.error_triplet(@code, description: @message, status: @http_status)
+    end
+
+  end
+end

data/lib/apia/request.rb

@@ -0,0 +1,67 @@
+# frozen_string_literal: true
+
+require 'rack/request'
+require 'apia/request_headers'
+require 'apia/errors/invalid_json_error'
+
+module Apia
+  class Request < Rack::Request
+
+    attr_accessor :api
+    attr_accessor :controller
+    attr_accessor :endpoint
+    attr_accessor :identity
+    attr_writer :arguments
+    attr_accessor :authenticator
+    attr_accessor :namespace
+    attr_accessor :route
+    attr_accessor :api_path
+
+    def self.empty(options: {})
+      new(options)
+    end
+
+    def arguments
+      @arguments ||= {}
+    end
+
+    def headers
+      @headers ||= RequestHeaders.create_from_request(self)
+    end
+
+    def json_body
+      return @json_body if instance_variable_defined?('@json_body')
+
+      @json_body = get_json_body_from_body || get_json_body_from_params
+    end
+
+    def body?
+      has_header?('rack.input')
+    end
+
+    private
+
+    def parse_json_from_string(body)
+      return {} if body.empty?
+
+      JSON.parse(body)
+    rescue JSON::ParserError => e
+      raise InvalidJSONError, e.message
+    end
+
+    def get_json_body_from_body
+      return unless content_type =~ /\Aapplication\/json/
+      return unless body?
+
+      parse_json_from_string(body.read)
+    end
+
+    def get_json_body_from_params
+      return unless body?
+      return unless params['_arguments'].is_a?(String)
+
+      parse_json_from_string(params['_arguments'])
+    end
+
+  end
+end

data/lib/apia/request_environment.rb

@@ -0,0 +1,84 @@
+# frozen_string_literal: true
+
+require 'apia/environment_error_handling'
+require 'apia/errors/invalid_helper_error'
+
+module Apia
+  class RequestEnvironment
+
+    attr_reader :request
+    attr_reader :response
+
+    include EnvironmentErrorHandling
+
+    def initialize(request, response)
+      @request = request
+      @response = response
+    end
+
+    def call(*args, &block)
+      return unless block_given?
+
+      instance_exec(@request, @response, *args, &block)
+    rescue ::StandardError => e
+      raise_exception(e)
+    end
+
+    # Call a helper
+    #
+    # @param name [Symbol]
+    # @return [Object, nil]
+    def helper(name, *args)
+      helper = @request.controller.definition.helpers[name.to_sym]
+      if helper.nil?
+        raise InvalidHelperError, "No helper found with name #{name}"
+      end
+
+      instance_exec(*args, &helper)
+    end
+
+    # Set appropriate pagination for the given set based on the configuration
+    # specified for the endpoint
+    #
+    # @param set [#limit, #count, #page, #per, #to_a, #total_pages, #current_page, #without_count]
+    # @param large_set [Boolean] whether or not this is expected to be a large set
+    # @return [void]
+    def paginate(set, potentially_large_set: false)
+      paginated_field = @request.endpoint.definition.paginated_field
+      if paginated_field.nil?
+        raise Apia::RuntimeError, 'Could not paginate response because no pagination has been configured for the endpoint'
+      end
+
+      paginated = set.page(@request.arguments[:page] || 1)
+      paginated = paginated.per(@request.arguments[:per_page] || 30)
+
+      large_set = false
+      if potentially_large_set
+        total_count = set.limit(1001).count
+        if total_count > 1000
+          large_set = true
+          paginated = paginated.without_count
+        end
+      end
+
+      @response.add_field paginated_field, paginated.to_a
+
+      pagination_info = {}
+      pagination_info[:current_page] = paginated.current_page
+      pagination_info[:per_page] = paginated.limit_value
+      pagination_info[:large_set] = large_set
+      unless large_set
+        pagination_info[:total] = paginated.total_count
+        pagination_info[:total_pages] = paginated.total_pages
+      end
+      @response.add_field :pagination, pagination_info
+    end
+
+    private
+
+    def potential_error_sources
+      [@request.endpoint, @request.authenticator].compact
+    end
+
+  end
+end