apia 3.0.0

data/lib/apia/errors/error_exception_error.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+require 'apia/errors/runtime_error'
+
+module Apia
+  # This is the error exception that must be raised when you wish to raise an
+  # error. It should be initialized with the Apia::Error class that you wish
+  # to raise.
+  class ErrorExceptionError < Apia::RuntimeError
+
+    attr_reader :error_class
+    attr_reader :fields
+
+    def initialize(error_class, fields = {})
+      @error_class = error_class
+      @fields = fields
+    end
+
+    def http_status
+      @error_class.definition.http_status || 500
+    end
+
+    def hash
+      {
+        code: @error_class.definition.code,
+        description: @error_class.definition.description,
+        detail: @error_class.definition.fields.generate_hash(@fields)
+      }
+    end
+
+  end
+end

data/lib/apia/errors/field_spec_parse_error.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+require 'apia/errors/runtime_error'
+
+module Apia
+  class FieldSpecParseError < Apia::RuntimeError
+
+    def http_status
+      400
+    end
+
+    def hash
+      {
+        code: 'invalid_field_spec',
+        description: 'The field spec string was invalid',
+        detail: {
+          details: message
+        }
+      }
+    end
+
+  end
+end

data/lib/apia/errors/invalid_argument_error.rb

@@ -0,0 +1,68 @@
+# frozen_string_literal: true
+
+require 'apia/errors/runtime_error'
+
+module Apia
+  # Raised when an argument set cannot be created based on the source object that
+  # has been provided. For example, if a validation rule exists or a scalar cannot
+  # be parsed for the underlying object.
+  #
+  # This is not raised for MISSING argument errors.
+  class InvalidArgumentError < Apia::RuntimeError
+
+    ISSUE_DESCRIPTIONS = {
+      invalid_scalar: 'The value provided was not of an appropriate type for the scalar that was requested. For example, you may have passed a string where an integer was required etc...',
+      parse_error: 'The value provided could not be parsed into an appropriate value by the server. For example, if a date was expected and the value could not be interpretted as such.',
+      validation_error: 'A validation rule that has been specified for this argument was not satisfied. See the further details in the response and in the documentation.',
+      invalid_enum_value: 'The value provided was not one of the options suitable for the enum.',
+      missing_lookup_value: 'A value for a lookup argument set has not been provided but at least one value is required.',
+      ambiguous_lookup_values: 'More than one value has been provided for a lookup argument set. Only one option may be provided.'
+    }.freeze
+
+    attr_reader :argument
+    attr_reader :index
+    attr_reader :path
+    attr_reader :errors
+    attr_reader :issue
+
+    def initialize(argument, issue: nil, index: nil, path: [], errors: [])
+      @argument = argument
+      @index = index
+      @path = path
+      @issue = issue
+      @errors = errors
+    end
+
+    def to_s
+      @issue.to_s
+    end
+
+    def http_status
+      400
+    end
+
+    def path_string
+      @path.map(&:name).join('.')
+    end
+
+    def hash
+      {
+        code: 'invalid_argument',
+        description: "The '#{path_string}' argument is invalid",
+        detail: {
+          path: @path.map(&:name),
+          index: @index,
+          issue: @issue&.to_s,
+          issue_description: ISSUE_DESCRIPTIONS[@issue.to_sym],
+          errors: @errors,
+          argument: {
+            id: argument.id,
+            name: argument.name,
+            description: argument.description
+          }
+        }
+      }
+    end
+
+  end
+end

data/lib/apia/errors/invalid_enum_option_error.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+require 'apia/errors/runtime_error'
+
+module Apia
+  class InvalidEnumOptionError < Apia::RuntimeError
+
+    attr_reader :enum
+    attr_reader :given_value
+
+    def initialize(enum, given_value)
+      @enum = enum
+      @given_value = given_value
+    end
+
+    def to_s
+      "Invalid option for `#{enum.class.definition.name || 'AnonymousEnum'}` (got: #{@given_value.inspect} (#{@given_value.class}))"
+    end
+
+  end
+end

data/lib/apia/errors/invalid_helper_error.rb

@@ -0,0 +1,6 @@
+# frozen_string_literal: true
+
+module Apia
+  class InvalidHelperError < StandardError
+  end
+end

data/lib/apia/errors/invalid_json_error.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+require 'apia/errors/runtime_error'
+
+module Apia
+  class InvalidJSONError < Apia::RuntimeError
+
+    def http_status
+      400
+    end
+
+    def hash
+      {
+        code: 'invalid_json_body',
+        description: 'The JSON body provided with this request is invalid',
+        detail: {
+          details: message
+        }
+      }
+    end
+
+  end
+end

data/lib/apia/errors/invalid_polymorph_value_error.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+require 'apia/errors/runtime_error'
+
+module Apia
+  class InvalidPolymorphValueError < Apia::RuntimeError
+
+    attr_reader :polymorph
+    attr_reader :given_value
+
+    def initialize(polymorph, given_value)
+      @polymorph = polymorph
+      @given_value = given_value
+    end
+
+    def to_s
+      "Invalid value for `#{polymorph.definition.id}` (got: #{@given_value.inspect})"
+    end
+
+  end
+end

data/lib/apia/errors/invalid_scalar_value_error.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+require 'apia/errors/runtime_error'
+
+module Apia
+  class InvalidScalarValueError < Apia::RuntimeError
+
+    attr_reader :scalar
+    attr_reader :given_value
+
+    def initialize(scalar, given_value)
+      @scalar = scalar
+      @given_value = given_value
+    end
+
+    def to_s
+      "Invalid value for `#{scalar.name}` (got: #{@given_value.inspect} (#{@given_value.class}))"
+    end
+
+  end
+end

data/lib/apia/errors/manifest_error.rb

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+require 'apia/rack'
+
+module Apia
+  class ManifestError < StandardError
+
+    def initialize(errors)
+      @errors = errors
+    end
+
+    def to_s
+      "#{@errors.errors.size} object(s) have issues that need attention (#{errors})"
+    end
+
+    def errors
+      @errors.errors.each_with_object([]) do |(object, errors), array|
+        errors.each do |error|
+          array << "#{object.id}: #{error[:code]} (#{error[:message]})"
+        end
+      end.join(', ')
+    end
+
+    def detail
+      @errors.errors.map do |object, errors|
+        {
+          object: object.id,
+          errors: errors.map do |error|
+            {
+              code: error[:code],
+              description: error[:message]
+            }
+          end
+        }
+      end
+    end
+
+    def triplet
+      Rack.error_triplet('manifest_error', description: 'An issue exists with the API manifest that needs resolving by the developer.', detail: detail)
+    end
+
+  end
+end

data/lib/apia/errors/missing_argument_error.rb

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+require 'apia/errors/runtime_error'
+
+module Apia
+  # This is raised when an argument set cannot be created because an argument
+  # that was required is not present on the source object.
+  class MissingArgumentError < Apia::RuntimeError
+
+    attr_reader :argument
+
+    def initialize(argument, path: [])
+      @argument = argument
+      @path = path
+    end
+
+    def http_status
+      400
+    end
+
+    def path_string
+      @path.map(&:name).join('.')
+    end
+
+    def hash
+      {
+        code: 'missing_required_argument',
+        description: "The '#{path_string}' argument is required but has not been provided",
+        detail: {
+          path: @path.map(&:name),
+          argument: {
+            name: argument.name,
+            description: argument.description
+          }
+        }
+      }
+    end
+
+  end
+end

data/lib/apia/errors/null_field_value_error.rb

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+require 'apia/errors/runtime_error'
+
+module Apia
+  class NullFieldValueError < Apia::RuntimeError
+
+    attr_reader :field
+
+    def initialize(field, source)
+      @field = field
+      @source = source
+    end
+
+    def to_s
+      "Value for `#{field.name}` is null (but cannot be)"
+    end
+
+    def http_status
+      500
+    end
+
+    def hash
+      {
+        code: 'null_value_for_non_null_field',
+        description: to_s,
+        detail: {
+          field: {
+            id: @field.id,
+            name: @field.name
+          }
+        }
+      }
+    end
+
+  end
+end

data/lib/apia/errors/parse_error.rb

@@ -0,0 +1,10 @@
+# frozen_string_literal: true
+
+require 'apia/errors/runtime_error'
+
+module Apia
+  # A parse error is raised when we are unable to parse input provided by an
+  # API consumer to turn it into an appropriate Scalar or Type.
+  class ParseError < Apia::RuntimeError
+  end
+end

data/lib/apia/errors/runtime_error.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+module Apia
+  # Runtime errors occurr during API requests because they could not
+  # be detected before an action is processed.
+  class RuntimeError < StandardError
+
+    # Return the default HTTP status code that should be returned when this
+    # error is encoutered over HTTP
+    #
+    # @return [Integer]
+    def http_status
+      400
+    end
+
+    # Return the hash that describes this error
+    #
+    # @return [Hash]
+    def hash
+      {
+        code: 'generic_runtime_error',
+        description: message,
+        detail: {
+          class: self.class.name
+        }
+      }
+    end
+
+  end
+end

data/lib/apia/errors/scope_not_granted_error.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+require 'apia/error'
+
+module Apia
+  class ScopeNotGrantedError < Apia::Error
+
+    code :scope_not_granted
+    http_status 403
+    description 'The scope required for this endpoint has not been granted to the authenticating identity'
+
+    field :scopes, [:string]
+
+  end
+end

data/lib/apia/errors/standard_error.rb

@@ -0,0 +1,6 @@
+# frozen_string_literal: true
+
+module Apia
+  class StandardError < ::StandardError
+  end
+end

data/lib/apia/field_set.rb

@@ -0,0 +1,76 @@
+# frozen_string_literal: true
+
+require 'apia/helpers'
+require 'apia/scalar'
+require 'apia/object'
+require 'apia/enum'
+require 'apia/field_spec'
+
+module Apia
+  class FieldSet < Hash
+
+    # Add a new field to the fieldset
+    #
+    # @param field [Apia::Field]
+    # @return [Apia::Field]
+    def add(field)
+      self[field.name] = field
+    end
+
+    # Validate this field set and add errors as appropriate
+    #
+    # @param errors [Apia::ManifestErrors]
+    # @param object [Object]
+    # @return [void]
+    def validate(errors, object)
+      each_value do |field|
+        unless field.type.usable_for_field?
+          errors.add object, 'InvalidFieldType', "Type for field #{field.name} must be a scalar, enum or object"
+        end
+      end
+    end
+
+    # Generate a hash for the fields that are defined on this object.
+    # It should receive the source object as well as a request
+    #
+    # @param source [Object, Hash]
+    # @param request [Apia::Request]
+    # @param only [Array]
+    # @return [Hash]
+    def generate_hash(source, request: nil, path: [])
+      each_with_object({}) do |(_, field), hash|
+        next unless field.include?(source, request)
+
+        field_path = path + [field]
+        next if request&.endpoint && !request&.endpoint&.include_field?(field_path)
+
+        value = field.value(source, request: request, path: field_path)
+        next if value == :skip
+
+        hash[field.name.to_sym] = value
+      end
+    end
+
+    # Generate a default field spec for this field set based on the values
+    # provided for the include option.
+    #
+    # @return [FieldSpec]
+    def spec
+      @spec ||= begin
+        spec = each_with_object([]) do |(key, field), array|
+          next if field.include == false
+
+          if field.include.is_a?(::String)
+            array << "#{key}[#{field.include}]"
+          elsif field.type.object? || field.type.polymorph?
+            array << "#{key}[*]"
+          else
+            array << key
+          end
+        end.join(',')
+        FieldSpec.parse(spec)
+      end
+    end
+
+  end
+end