apia 3.0.0

data/lib/apia/definitions/enum.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+require 'apia/definition'
+require 'apia/dsls/enum'
+
+module Apia
+  module Definitions
+    class Enum < Definition
+
+      attr_accessor :cast
+      attr_reader :values
+
+      def setup
+        @values = {}
+      end
+
+      def dsl
+        @dsl ||= DSLs::Enum.new(self)
+      end
+
+      def validate(errors)
+        if cast && !cast.is_a?(Proc)
+          errors.add self, 'CastMustBeProc', 'The value provided for casting an enum must be an instance of Proc'
+        end
+
+        true
+      end
+
+    end
+  end
+end

data/lib/apia/definitions/error.rb

@@ -0,0 +1,59 @@
+# frozen_string_literal: true
+
+require 'apia/definition'
+require 'apia/dsls/error'
+require 'apia/field_set'
+
+module Apia
+  module Definitions
+    class Error < Definition
+
+      attr_accessor :code
+      attr_accessor :http_status
+      attr_reader :fields
+      attr_reader :catchable_exceptions
+
+      def setup
+        @fields = FieldSet.new
+        @catchable_exceptions = {}
+      end
+
+      def dsl
+        @dsl ||= DSLs::Error.new(self)
+      end
+
+      # Return the actual HTTP status code
+      #
+      # @return [Integer]
+      def http_status_code
+        if @http_status.is_a?(Symbol)
+          ::Rack::Utils::SYMBOL_TO_STATUS_CODE[@http_status]
+        else
+          @http_status
+        end
+      end
+
+      # Validate that this error class is valid and thus can be used in the
+      # API.
+      #
+      # @param errors [Apia::ManifestErrors]
+      # @reeturn [void]
+      def validate(errors)
+        unless code.is_a?(Symbol)
+          errors.add self, 'InvalidCode', 'Code must be a symbol'
+        end
+
+        if http_status_code.is_a?(Integer) && ::Rack::Utils::HTTP_STATUS_CODES[http_status_code]
+          # OK
+        elsif http_status_code.is_a?(Integer)
+          errors.add self, 'InvalidHTTPStatus', "The HTTP status is not valid (must be one of #{::Rack::Utils::HTTP_STATUS_CODES.keys.join(', ')})"
+        else
+          errors.add self, 'InvalidHTTPStatus', 'The HTTP status is not valid (must be an integer)'
+        end
+
+        @fields.validate(errors, self)
+      end
+
+    end
+  end
+end

data/lib/apia/definitions/field.rb

@@ -0,0 +1,117 @@
+# frozen_string_literal: true
+
+require 'apia/definition'
+require 'apia/helpers'
+require 'apia/dsls/field'
+require 'apia/definitions/type'
+require 'apia/errors/invalid_scalar_value_error'
+require 'apia/errors/null_field_value_error'
+
+module Apia
+  module Definitions
+    class Field < Definition
+
+      attr_accessor :description
+      attr_accessor :backend
+      attr_accessor :array
+      attr_accessor :null
+      attr_accessor :condition
+      attr_writer :type
+      attr_accessor :include
+
+      def initialize(name, id: nil)
+        @name = name
+        @id = id
+      end
+
+      # Return the type of object
+      #
+      # @return [Class]
+      def type
+        Type.new(@type)
+      end
+
+      # Can the result for thsi field be nil?
+      #
+      # @return [Boolean]
+      def null?
+        @null == true
+      end
+
+      # Is the result from this field expected to be an array?
+      #
+      # @return [Boolean]
+      def array?
+        @array == true
+      end
+
+      # Should this field be inclued for the given value and request
+      #
+      # @param value [Object]
+      # @param request [Apia::Request]
+      # @return [Boolean]
+      def include?(value, request)
+        return true if @condition.nil?
+
+        @condition.call(value, request) == true
+      end
+
+      # Return a DSL instance for this field
+      #
+      # @return [Apia::DSLs::Field]
+      def dsl
+        @dsl ||= DSLs::Field.new(self)
+      end
+
+      # Return the backend value from the given object based on the
+      # rules that exist for this field.
+      #
+      # @param object [Object]
+      # @return [Object]
+      def raw_value_from_object(object)
+        if @backend
+          get_value_from_backend(object)
+        else
+          get_value_directly_from_object(object, @name)
+        end
+      end
+
+      # Return an instance of a Type or a Scalar for this field
+      #
+      # @param object [Object]
+      # @return [Object]
+      def value(object, request: nil, path: [])
+        raw_value = raw_value_from_object(object)
+
+        return nil if raw_value.nil? && null?
+        raise Apia::NullFieldValueError.new(self, object) if raw_value.nil?
+
+        if array? && raw_value.is_a?(Array)
+          raw_value.map { |v| type.cast(v, request: request, path: path) }
+        else
+          type.cast(raw_value, request: request, path: path)
+        end
+      end
+
+      private
+
+      def get_value_from_backend(object)
+        case @backend
+        when Symbol
+          get_value_directly_from_object(object, @backend)
+        when Proc
+          @backend.call(object)
+        end
+      end
+
+      def get_value_directly_from_object(object, name)
+        if object.is_a?(Hash)
+          object.fetch(name.to_sym) { object[name.to_s] }
+        else
+          object.public_send(name.to_sym)
+        end
+      end
+
+    end
+  end
+end

data/lib/apia/definitions/lookup_argument_set.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+require 'apia/definitions/argument_set'
+require 'apia/dsls/lookup_argument_set'
+
+module Apia
+  module Definitions
+    class LookupArgumentSet < Definitions::ArgumentSet
+
+      attr_accessor :resolver
+
+      def dsl
+        @dsl ||= DSLs::LookupArgumentSet.new(self)
+      end
+
+      def potential_errors
+        @potential_errors ||= ErrorSet.new
+      end
+
+      def validate(errors)
+        super
+        @potential_errors&.validate(errors, self)
+      end
+
+    end
+  end
+end

data/lib/apia/definitions/object.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+require 'apia/definition'
+require 'apia/dsls/object'
+require 'apia/field_set'
+
+module Apia
+  module Definitions
+    class Object < Definition
+
+      attr_reader :conditions
+      attr_reader :fields
+
+      def setup
+        @conditions = []
+        @fields = FieldSet.new
+      end
+
+      def dsl
+        @dsl ||= DSLs::Object.new(self)
+      end
+
+      def validate(errors)
+        @fields.validate(errors, self)
+      end
+
+    end
+  end
+end

data/lib/apia/definitions/polymorph.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+require 'apia/definition'
+require 'apia/dsls/polymorph'
+require 'apia/helpers'
+
+module Apia
+  module Definitions
+    class Polymorph < Definition
+
+      attr_reader :options
+
+      def setup
+        @options = {}
+      end
+
+      def dsl
+        @dsl ||= DSLs::Polymorph.new(self)
+      end
+
+      def validate(errors)
+        @options.each_value do |option|
+          option.validate(errors)
+        end
+      end
+
+    end
+  end
+end

data/lib/apia/definitions/polymorph_option.rb

@@ -0,0 +1,53 @@
+# frozen_string_literal: true
+
+require 'apia/definitions/type'
+
+module Apia
+  module Definitions
+    class PolymorphOption
+
+      attr_reader :id
+      attr_reader :name
+      attr_reader :matcher
+
+      def initialize(id, name, type: nil, matcher: nil)
+        @id = id
+        @name = name
+        @type = type
+        @matcher = matcher
+      end
+
+      def type
+        Type.new(@type)
+      end
+
+      def matches?(value)
+        return false if @matcher.nil?
+
+        @matcher.call(value) == true
+      end
+
+      def cast(value, request: nil, path: [])
+        {
+          type: @name.to_s,
+          value: type.cast(value, request: request, path: path)
+        }
+      end
+
+      def validate(errors)
+        if @type.nil?
+          errors.add self, 'MissingType', "Type for #{name} is missing"
+        elsif !type.usable_for_field?
+          errors.add self, 'InvalidType', "Type for #{name} must a scalar, polymorph, object or enum "
+        end
+
+        unless @matcher.is_a?(Proc)
+          errors.add self, 'MissingMatcher', "A matcher must be provided for all options (missing for #{name})"
+        end
+
+        true
+      end
+
+    end
+  end
+end

data/lib/apia/definitions/scalar.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+require 'apia/definition'
+require 'apia/dsls/scalar'
+
+module Apia
+  module Definitions
+    class Scalar < Definition
+
+      attr_accessor :cast
+      attr_accessor :parse
+      attr_accessor :validator
+
+      def dsl
+        @dsl ||= DSLs::Scalar.new(self)
+      end
+
+      def validate(errors)
+      end
+
+    end
+  end
+end

data/lib/apia/definitions/type.rb

@@ -0,0 +1,109 @@
+# frozen_string_literal: true
+
+module Apia
+  module Definitions
+    class Type
+
+      def initialize(type)
+        @type = type
+      end
+
+      def id
+        klass&.definition&.id
+      end
+
+      def klass
+        if @type.is_a?(Symbol) || @type.is_a?(String)
+          Scalars.fetch(@type.to_sym)
+        else
+          @type
+        end
+      end
+
+      # Can this type actually be used?
+      #
+      # @return [Boolean]
+      def usable_for_field?
+        scalar? || object? || enum? || polymorph?
+      end
+
+      # Can this type be used for an argument?
+      #
+      # @return [Boolean]
+      def usable_for_argument?
+        scalar? || enum? || argument_set?
+      end
+
+      # Cast the given value into an response that can be sent to the
+      # consumer.
+      #
+      # @param value [Object, nil]
+      # @param request [Apia::Request, nil]
+      # @return [Object, nil]
+      def cast(value, request: nil, path: [])
+        return nil if value.nil?
+
+        if scalar? || enum?
+          # If this is a scalar or an enum, we're going to just return the
+          # value that they return. There's nothing complicated about them
+          # and they return scalars.
+          klass.cast(value)
+
+        elsif object?
+          # If this field returns an object, we'll go ahead and generate
+          # the hash for the object at this point.
+          object = klass.new(value)
+
+          # If this item shouldn't be included. we'll return :skip which
+          # will instruct the field set not to include it at all.
+          return :skip unless object.include?(request)
+
+          # Otherwise, we'll return the hash
+          object.hash(request: request, path: path)
+
+        elsif polymorph?
+          # If the type is a polymorph and this value
+          option = klass.option_for_value(value)
+          option.cast(value, request: request, path: path)
+
+        end
+      end
+
+      # Does this field return an argument set?
+      #
+      # @return [Boolean]
+      def argument_set?
+        klass&.ancestors&.include?(Apia::ArgumentSet)
+      end
+
+      # Does this field return a scalar?
+      #
+      # @return [Boolean]
+      def scalar?
+        klass&.ancestors&.include?(Apia::Scalar)
+      end
+
+      # Does this field return an enum?
+      #
+      # @return [Boolean]
+      def enum?
+        klass&.ancestors&.include?(Apia::Enum)
+      end
+
+      # Does this field return an object?
+      #
+      # @return [Boolean]
+      def object?
+        klass&.ancestors&.include?(Apia::Object)
+      end
+
+      # Does this field return a polymorph?
+      #
+      # @return [Boolean]
+      def polymorph?
+        klass&.ancestors&.include?(Apia::Polymorph)
+      end
+
+    end
+  end
+end