apia 3.0.0

data/lib/apia/dsls/polymorph.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+require 'apia/dsl'
+require 'apia/definitions/polymorph_option'
+require 'apia/helpers'
+
+module Apia
+  module DSLs
+    class Polymorph < DSL
+
+      def option(name, type: nil, matcher: nil)
+        id = "#{@definition.id}/#{Helpers.camelize(name)}Option"
+        option = Definitions::PolymorphOption.new(id, name, type: type, matcher: matcher)
+        @definition.options[name.to_sym] = option
+      end
+
+    end
+  end
+end

data/lib/apia/dsls/route_group.rb

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+module Apia
+  module DSLs
+    class RouteGroup
+
+      def initialize(route_set, group)
+        @route_set = route_set
+        @group = group
+      end
+
+      def route(path, **options)
+        @route_set.dsl.route(path, controller: options[:controller] || @group.default_controller, group: @group, **options)
+      end
+
+      def group(id, &block)
+        group = Apia::RouteGroup.new("#{@group.id}.#{id}", @group)
+        dsl = Apia::DSLs::RouteGroup.new(@route_set, group)
+        dsl.instance_eval(&block)
+        @group.groups << group
+      end
+
+      Route::REQUEST_METHODS.each do |method_name|
+        define_method method_name do |path, **options|
+          route(path, request_method: method_name, **options)
+        end
+      end
+
+      def name(name)
+        @group.name = name
+      end
+
+      def description(description)
+        @group.description = description
+      end
+
+      def controller(controller)
+        @group.default_controller = controller
+      end
+
+    end
+  end
+end

data/lib/apia/dsls/route_set.rb

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+require 'apia/route'
+require 'apia/route_group'
+require 'apia/dsls/route_group'
+
+module Apia
+  module DSLs
+    class RouteSet
+
+      def initialize(route_set)
+        @route_set = route_set
+      end
+
+      def schema(path: 'schema')
+        require 'apia/schema/controller'
+        get path, controller: Schema::Controller, endpoint: :schema
+      end
+
+      def route(path, request_method: nil, **options)
+        route = Route.new(path, request_method: request_method, **options)
+        @route_set.add(route)
+      end
+
+      Route::REQUEST_METHODS.each do |method_name|
+        define_method method_name do |path, **options|
+          route(path, request_method: method_name, **options)
+        end
+      end
+
+      def group(id, &block)
+        group = Apia::RouteGroup.new(id.to_s, nil)
+        dsl = Apia::DSLs::RouteGroup.new(@route_set, group)
+        dsl.instance_eval(&block)
+        @route_set.groups << group
+      end
+
+    end
+  end
+end

data/lib/apia/dsls/scalar.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+require 'apia/dsl'
+
+module Apia
+  module DSLs
+    class Scalar < DSL
+
+      def cast(&block)
+        @definition.cast = block
+      end
+
+      def parse(&block)
+        @definition.parse = block
+      end
+
+      def validator(&block)
+        @definition.validator = block
+      end
+
+    end
+  end
+end

data/lib/apia/dsls/scope_descriptions.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+module Apia
+  module DSLs
+    class ScopeDescriptions
+
+      def initialize(api)
+        @api = api
+      end
+
+      def add(name, description)
+        @api.scopes[name.to_s] = { description: description }
+      end
+
+    end
+  end
+end

data/lib/apia/endpoint.rb

@@ -0,0 +1,110 @@
+# frozen_string_literal: true
+
+require 'apia/helpers'
+require 'apia/defineable'
+require 'apia/definitions/endpoint'
+require 'apia/request_environment'
+require 'apia/errors/scope_not_granted_error'
+require 'apia/callable_with_environment'
+
+module Apia
+  class Endpoint
+
+    extend Defineable
+    include CallableWithEnvironment
+
+    class << self
+
+      # Return the definition object for the endpoint
+      #
+      # @return [Apia::Definitions::Endpoint]
+      def definition
+        @definition ||= Definitions::Endpoint.new(Helpers.class_name_to_id(name))
+      end
+
+      # Collate all objects that this endpoint references and add them to the
+      # given object set
+      #
+      # @param set [Apia::ObjectSet]
+      # @return [void]
+      def collate_objects(set)
+        set.add_object(definition.argument_set)
+
+        definition.potential_errors.each do |error|
+          set.add_object(error)
+        end
+
+        definition.fields.each_value do |field|
+          set.add_object(field.type.klass) if field.type.usable_for_field?
+        end
+      end
+
+      # Run this request by providing a request to execute it with.
+      #
+      # @param request [Apia::Request]
+      # @return [Apia::Response]
+      def execute(request)
+        response = Response.new(request, self)
+        environment = RequestEnvironment.new(request, response)
+
+        catch_errors(response) do
+          # Determine an authenticator and execute it before the request happens
+          request.authenticator = definition.authenticator || request.controller&.definition&.authenticator || request.api&.definition&.authenticator
+          request.authenticator&.execute(environment)
+
+          # Determine if we're permitted to run the action based on the endpoint's scopes
+          if request.authenticator && !request.authenticator.authorized_scope?(environment, definition.scopes)
+            environment.raise_error Apia::ScopeNotGrantedError, scopes: definition.scopes
+          end
+
+          # Process arguments into the request. This happens after the authentication
+          # stage because a) authenticators shouldn't be using endpoint specific args
+          # and b) the argument conditions may need to know the identity.
+          request.arguments = definition.argument_set.create_from_request(request)
+
+          # Call the action for the endpoint
+          endpoint_instance = new(environment)
+          endpoint_instance.call_with_error_handling
+
+          # We're going to call this here because we want to cache the actual values of
+          # the output within the catch_errors block.
+          response.hash
+        end
+
+        response
+      end
+
+      # Catch any runtime errors and update the given response with the appropriate
+      # values.
+      #
+      # @param response [Apia::Response]
+      # @return [void]
+      def catch_errors(response)
+        yield
+      rescue Apia::RuntimeError => e
+        catch_errors(response) do
+          response.body = { error: e.hash }
+          response.status = e.http_status
+          response.headers['x-api-schema'] = 'json-error'
+        end
+      end
+
+      # Should a given field be included
+      #
+      def include_field?(*args)
+        definition.fields.spec.include_field?(*args)
+      end
+
+      # Allow an endpoint to be executed with a mocked request.
+      #
+      def test
+        request = Apia::MockRequest.empty
+        request.endpoint = self
+        yield request if block_given?
+        execute(request)
+      end
+
+    end
+
+  end
+end

data/lib/apia/enum.rb

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+require 'apia/helpers'
+require 'apia/defineable'
+require 'apia/definitions/enum'
+require 'apia/errors/invalid_enum_option_error'
+
+module Apia
+  class Enum
+
+    extend Defineable
+
+    class << self
+
+      # Return the definition object for the enum
+      #
+      # @return [Apia::Definitions::Enum]
+      def definition
+        @definition ||= Definitions::Enum.new(Helpers.class_name_to_id(name))
+      end
+
+      # Cast a value or define a new block for casting (for DSL purposes)
+      #
+      # @param value [Object?]
+      # @return [Object?]
+      def cast(value = nil, &block)
+        if block_given? && value.nil?
+          return definition.dsl.cast(&block)
+        end
+
+        value = definition.cast.call(value) if definition.cast
+
+        if definition.values[value].nil?
+          raise InvalidEnumOptionError.new(self, value)
+        end
+
+        value
+      end
+
+    end
+
+  end
+end

data/lib/apia/environment_error_handling.rb

@@ -0,0 +1,74 @@
+# frozen_string_literal: true
+
+module Apia
+  module EnvironmentErrorHandling
+
+    # Raise an error
+    #
+    # @param error [String, Class] an error class or the name of a defined error
+    def raise_error(error, fields = {})
+      if error.respond_to?(:ancestors) && error.ancestors.include?(Apia::Error)
+        raise error.exception(fields)
+      end
+
+      if found_error = find_error_by_name(error)
+        raise found_error.exception(fields)
+      end
+
+      raise Apia::RuntimeError, "No error defined named #{error}"
+    end
+
+    # Return an error instance for a given exception class
+    #
+    # @param exception_class [Class] any error class
+    # @return [Class, nil] any class that inherits from Apia::Error or nil if no error is found
+    def error_for_exception(exception_class)
+      potential_error_sources.each do |source|
+        source.definition.potential_errors.each do |error|
+          if error.definition.catchable_exceptions.key?(exception_class)
+            return {
+              error: error,
+              block: error.definition.catchable_exceptions[exception_class]
+            }
+          end
+        end
+      end
+      nil
+    end
+
+    def raise_exception(exception)
+      error = error_for_exception(exception.class)
+      raise exception if error.nil?
+
+      fields = {}
+      error[:block]&.call(fields, exception)
+      raise error[:error].exception(fields)
+    end
+
+    private
+
+    def find_error_by_name(error_name)
+      return nil if potential_error_sources.nil?
+
+      potential_error_sources.each do |source|
+        error = find_potential_error(source, error_name)
+        return error if error
+      end
+
+      nil
+    end
+
+    def find_potential_error(source, name)
+      return nil if source.nil?
+
+      unless name =~ /\//
+        name = source.definition.id + '/' + name
+      end
+
+      source.definition.potential_errors.find do |error|
+        error.definition.id == name
+      end
+    end
+
+  end
+end

data/lib/apia/error.rb

@@ -0,0 +1,61 @@
+# frozen_string_literal: true
+
+require 'apia/helpers'
+require 'apia/defineable'
+require 'apia/definitions/error'
+require 'apia/object'
+require 'apia/scalar'
+require 'apia/errors/error_exception_error'
+
+module Apia
+  # An Error represents a specific failure that can be raised by any
+  # action within the API.
+  #
+  # An error can specify a `code` which is textual description of the
+  # error which will be returned to the user.
+  #
+  # An HTTP status code can be provided which will be sent to the user
+  # if the error is incurred. If no HTTP status code is provided, the
+  # a 500 error code will be used.
+  #
+  # You can also define an array of additional fields that can
+  # included when the error is raised. This works in the same way as
+  # any type and an object implementing those methods should be provided
+  # when the error is raised.
+  class Error
+
+    extend Defineable
+
+    class << self
+
+      # Return the definition object for errors
+      #
+      # @return [Apia::Definitions::Error]
+      def definition
+        @definition ||= Definitions::Error.new(Helpers.class_name_to_id(name))
+      end
+
+      # Collate all objects that this error references and add them to the
+      # given object set
+      #
+      # @param set [Apia::ObjectSet]
+      # @return [void]
+      def collate_objects(set)
+        definition.fields.each_value do |field|
+          set.add_object(field.type.klass) if field.type.usable_for_field?
+        end
+      end
+
+      # Return an exception that should be raised to represent this error
+      # when it is actually invoked
+      #
+      # @param fields [Hash]
+      # @return [ErrorExceptionError]
+      def exception(fields = {})
+        ErrorExceptionError.new(self, fields)
+      end
+
+    end
+
+  end
+end

data/lib/apia/error_set.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+module Apia
+  class ErrorSet < Array
+
+    def validate(errors, object)
+      each_with_index do |error, index|
+        unless error.respond_to?(:ancestors) && error.ancestors.include?(Apia::Error)
+          errors.add object, 'InvalidPotentialError', "Potential error at index #{index} must be a class that inherits from Apia::Error"
+        end
+      end
+    end
+
+  end
+end