fun_with_json_api 0.0.1

data/lib/fun_with_json_api/deserializer.rb

@@ -0,0 +1,70 @@
+require 'active_support/inflector'
+require 'fun_with_json_api/attribute'
+require 'fun_with_json_api/deserializer_class_methods'
+
+module FunWithJsonApi
+  class Deserializer
+    extend FunWithJsonApi::DeserializerClassMethods
+
+    # Creates a new instance of a
+    def self.create(options = {})
+      new(options)
+    end
+
+    # Use DeserializerClass.create to build new instances
+    private_class_method :new
+
+    attr_reader :id_param
+    attr_reader :type
+    attr_reader :resource_class
+
+    attr_reader :attributes
+    attr_reader :relationships
+
+    def initialize(options = {})
+      @id_param = options.fetch(:id_param) { self.class.id_param }
+      @type = options[:type]
+      @resource_class = options[:resource_class]
+      @attributes = filter_attributes_by_name(options[:attributes], self.class.attributes)
+      @relationships = filter_attributes_by_name(options[:relationships], self.class.relationships)
+    end
+
+    # Takes a parsed params hash from ActiveModelSerializers::Deserialization and sanitizes values
+    def sanitize_params(params)
+      Hash[
+        serialize_attribute_values(attributes, params) +
+        serialize_attribute_values(relationships, params)
+      ]
+    end
+
+    def type
+      @type ||= self.class.type
+    end
+
+    def resource_class
+      @resource_class ||= self.class.resource_class
+    end
+
+    private
+
+    def filter_attributes_by_name(attribute_names, attributes)
+      if attribute_names
+        attributes.keep_if { |attribute| attribute_names.include?(attribute.name) }
+      else
+        attributes
+      end
+    end
+
+    # Calls <attribute.as> on the current instance, override the #<as> method to change loading
+    def serialize_attribute_values(attributes, params)
+      attributes.select { |attribute| params.key?(attribute.param_value) }
+                .map { |attribute| serialize_attribute(attribute, params) }
+    end
+
+    # Calls <attribute.as> on the current instance, override the #<as> method to change loading
+    def serialize_attribute(attribute, params)
+      raw_value = params.fetch(attribute.param_value)
+      [attribute.param_value, public_send(attribute.sanitize_attribute_method, raw_value)]
+    end
+  end
+end

data/lib/fun_with_json_api/deserializer_class_methods.rb

@@ -0,0 +1,83 @@
+require 'fun_with_json_api/attribute'
+
+module FunWithJsonApi
+  # Provides a basic DSL for defining a FunWithJsonApi::Deserializer
+  module DeserializerClassMethods
+    def id_param(id_param = nil)
+      @id_param = id_param if id_param
+      @id_param || :id
+    end
+
+    def type(type = nil)
+      @type = type if type
+      @type || type_from_class_name
+    end
+
+    def resource_class(resource_class = nil)
+      @resource_class = resource_class if resource_class
+      @resource_class || type_from_class_name.singularize.classify.constantize
+    end
+
+    # Attributes
+
+    def attribute(name, options = {})
+      Attribute.create(name, options).tap do |attribute|
+        add_parse_attribute_method(attribute)
+        attributes << attribute
+      end
+    end
+
+    def attributes
+      @attributes ||= []
+    end
+
+    # Relationships
+
+    def belongs_to(name, deserializer_class_or_callable, options = {})
+      Attributes::Relationship.create(
+        name,
+        deserializer_class_or_callable,
+        options
+      ).tap do |relationship|
+        add_parse_attribute_method(relationship)
+        relationships << relationship
+      end
+    end
+
+    # rubocop:disable Style/PredicateName
+
+    def has_many(name, deserializer_class_or_callable, options = {})
+      Attributes::RelationshipCollection.create(
+        name,
+        deserializer_class_or_callable,
+        options
+      ).tap do |relationship|
+        add_parse_attribute_method(relationship)
+        relationships << relationship
+      end
+    end
+
+    # rubocop:enable Style/PredicateName
+
+    def relationships
+      @relationships ||= []
+    end
+
+    private
+
+    def add_parse_attribute_method(attribute)
+      define_method(attribute.sanitize_attribute_method) do |param_value|
+        attribute.call(param_value)
+      end
+    end
+
+    def type_from_class_name
+      resource_class_name = name.demodulize.sub(/Deserializer/, '').underscore
+      if ActiveModelSerializers.config.jsonapi_resource_type == :singular
+        resource_class_name.singularize
+      else
+        resource_class_name.pluralize
+      end
+    end
+  end
+end

data/lib/fun_with_json_api/deserializer_config_builder.rb

@@ -0,0 +1,48 @@
+module FunWithJsonAPi
+  # Builds an options hash for ActiveModelSerializers::Deserialization.jsonapi_parse
+  class DeserializerConfigBuilder
+    def self.build(deserializer)
+      new(deserializer).build
+    end
+
+    private_class_method :new
+
+    attr_reader :deserializer
+
+    def initialize(deserializer)
+      @deserializer = deserializer
+    end
+
+    def build
+      {
+        only: build_only_values,
+        keys: build_keys_value
+      }
+    end
+
+    protected
+
+    def build_only_values
+      attribute_only_values(deserializer.attributes) +
+        attribute_only_values(deserializer.relationships)
+    end
+
+    def build_keys_value
+      Hash[
+        attribute_key_values(deserializer.attributes) +
+        attribute_key_values(deserializer.relationships)
+      ]
+    end
+
+    private
+
+    def attribute_only_values(attributes_or_relationships)
+      attributes_or_relationships.map(&:name)
+    end
+
+    def attribute_key_values(attributes_or_relationships)
+      attributes_or_relationships.select { |a| a.name != a.as }
+                                 .map { |a| [a.name, a.as] }
+    end
+  end
+end

data/lib/fun_with_json_api/exception.rb

@@ -0,0 +1,27 @@
+require 'fun_with_json_api/exception_payload'
+
+module FunWithJsonApi
+  class Exception < StandardError
+    attr_reader :payload
+
+    def initialize(message, payload)
+      super(message)
+      @payload = Array.wrap(payload)
+    end
+
+    # @return [Integer] The http status code for rendering this error
+    def http_status
+      payload_statuses = payload.map(&:status).uniq
+      if payload_statuses.length == 1
+        Integer(payload_statuses.first || '400') # Return the unique status code
+      elsif payload_statuses.any? { |status| status.starts_with?('5') }
+        500 # We have a server error
+      else
+        400 # Bad Request
+      end
+    end
+  end
+end
+
+# Load known Exceptions
+Dir["#{File.dirname(__FILE__)}/exceptions/**/*.rb"].each { |f| require f }

data/lib/fun_with_json_api/exception_payload.rb

@@ -0,0 +1,29 @@
+require 'active_model_serializers/model'
+
+module FunWithJsonApi
+  # id: a unique identifier for this particular occurrence of the problem.
+  # links: a links object containing the following members:
+  #   about: a link that leads to further details about this particular occurrence of the problem.
+  # status: the HTTP status code applicable to this problem, expressed as a string value.
+  # code: an application-specific error code, expressed as a string value.
+  # title: a short, human-readable summary of the problem that SHOULD NOT change from occurrence to
+  #   occurrence of the problem, except for purposes of localization.
+  # detail: a human-readable explanation specific to this occurrence of the problem. Like title,
+  #   this field's value can be localized.
+  # source: an object containing references to the source of the error, optionally including any of
+  #   the following members:
+  # pointer: a JSON Pointer [RFC6901] to the associated entity in the request document
+  #  [e.g. "/data" for a primary data object, or "/data/attributes/title" for a specific attribute].
+  #  parameter: a string indicating which URI query parameter caused the error.
+  #  meta: a meta object containing non-standard meta-information about the error.
+  class ExceptionPayload < ActiveModelSerializers::Model
+    [:id, :status, :code, :title, :detail, :pointer, :parameter].each do |param|
+      define_method param do
+        attributes[param]
+      end
+      define_method "#{param}=" do |value|
+        attributes[param] = value
+      end
+    end
+  end
+end

data/lib/fun_with_json_api/exception_payload_serializer.rb

@@ -0,0 +1,17 @@
+module FunWithJsonApi
+  class ExceptionPayloadSerializer < ActiveModel::Serializer
+    attributes :id, :status, :code, :title, :detail, :source
+
+    def attributes(*)
+      # Strips all empty values and empty arrays
+      super.select { |_k, v| v.present? }
+    end
+
+    def source
+      {
+        pointer: object.pointer,
+        parameter: object.parameter
+      }.select { |_k, v| v.present? }
+    end
+  end
+end

data/lib/fun_with_json_api/exception_serializer.rb

@@ -0,0 +1,15 @@
+require 'fun_with_json_api/exception_payload_serializer'
+
+module FunWithJsonApi
+  class ExceptionSerializer < ActiveModel::Serializer::CollectionSerializer
+    def initialize(exception, options = {})
+      super(exception.payload, options.reverse_merge(
+        serializer: ExceptionPayloadSerializer
+      ))
+    end
+
+    def root
+      'errors'
+    end
+  end
+end

data/lib/fun_with_json_api/exceptions/invalid_attribute.rb

@@ -0,0 +1,13 @@
+module FunWithJsonApi
+  module Exceptions
+    # Indicates a Supplied attributes value is not formatted correctly
+    class InvalidAttribute < FunWithJsonApi::Exception
+      def initialize(message, payload = ExceptionPayload.new)
+        payload.code ||= 'invalid_attribute'
+        payload.title ||= I18n.t(:invalid_attribute, scope: 'fun_with_json_api.exceptions')
+        payload.status ||= '400'
+        super
+      end
+    end
+  end
+end

data/lib/fun_with_json_api/exceptions/invalid_document.rb

@@ -0,0 +1,12 @@
+module FunWithJsonApi
+  module Exceptions
+    class InvalidDocument < FunWithJsonApi::Exception
+      def initialize(message, payload = ExceptionPayload.new)
+        payload.code ||= 'invalid_document'
+        payload.title ||= I18n.t(:invalid_document, scope: 'fun_with_json_api.exceptions')
+        payload.status ||= '400'
+        super
+      end
+    end
+  end
+end

data/lib/fun_with_json_api/exceptions/invalid_relationship.rb

@@ -0,0 +1,13 @@
+module FunWithJsonApi
+  module Exceptions
+    # Indicates a Supplied relationships value is not formatted correctly
+    class InvalidRelationship < FunWithJsonApi::Exception
+      def initialize(message, payload = ExceptionPayload.new)
+        payload.code ||= 'invalid_relationship'
+        payload.title ||= I18n.t(:invalid_relationship, scope: 'fun_with_json_api.exceptions')
+        payload.status ||= '400'
+        super
+      end
+    end
+  end
+end

data/lib/fun_with_json_api/exceptions/missing_relationship.rb

@@ -0,0 +1,15 @@
+module FunWithJsonApi
+  module Exceptions
+    # Indicates a Supplied relationships value is not able to be found
+    class MissingRelationship < FunWithJsonApi::Exception
+      def initialize(message, payload = ExceptionPayload.new)
+        payload = Array.wrap(payload).each do |missing|
+          missing.code ||= 'missing_relationship'
+          missing.title ||= I18n.t(:missing_relationship, scope: 'fun_with_json_api.exceptions')
+          missing.status ||= '404'
+        end
+        super
+      end
+    end
+  end
+end

data/lib/fun_with_json_api/pre_deserializer.rb

@@ -0,0 +1,61 @@
+require 'active_model_serializers'
+
+module FunWithJsonApi
+  # Converts a json_api document into a rails compatible hash.
+  # Acts as an adaptor for ActiveModuleSerializer deserializer classes
+  class PreDeserializer
+    def self.parse(document, deserializer)
+      new(document, deserializer).parse
+    end
+
+    attr_reader :document
+    attr_reader :deserializer
+
+    def initialize(document, deserializer)
+      @document = document.to_h.deep_dup.deep_stringify_keys
+      @deserializer = deserializer
+    end
+
+    def parse
+      ams_deserializer_class.parse(document, ams_deserializer_config) do |invalid_document, reason|
+        exception_message = "Invalid payload (#{reason}): #{invalid_document}"
+        exception = convert_reason_into_exceptions(exception_message, reason).first ||
+                    Exceptions::InvalidDocument.new(exception_message)
+        raise exception
+      end
+    end
+
+    protected
+
+    def convert_reason_into_exceptions(exception_message, reason, values = [])
+      if reason.is_a?(String)
+        return convert_reason_message_into_error(exception_message, reason, values.join)
+      end
+      return nil unless reason.is_a?(Hash)
+      return nil unless reason.size == 1
+
+      reason.flat_map do |key, value|
+        convert_reason_into_exceptions(exception_message, value, (values + ["/#{key}"]))
+      end
+    end
+
+    def convert_reason_message_into_error(exception_message, reason, source)
+      payload = ExceptionPayload.new
+      payload.pointer = source.presence
+      payload.detail = reason
+      Exceptions::InvalidDocument.new(exception_message, payload)
+    end
+
+    def ams_deserializer_class
+      if defined?(ActiveModel::Serializer::Adapter::JsonApi::Deserialization)
+        ActiveModel::Serializer::Adapter::JsonApi::Deserialization
+      else
+        ActiveModelSerializers::Adapter::JsonApi::Deserialization
+      end
+    end
+
+    def ams_deserializer_config
+      @ams_deserializer_config ||= FunWithJsonAPi::DeserializerConfigBuilder.build(deserializer)
+    end
+  end
+end

data/lib/fun_with_json_api/railtie.rb

@@ -0,0 +1,11 @@
+require 'fun_with_json_api/controller_methods'
+
+module FunWithJsonApi
+  # Mountable engine for fun with json_api
+  class Railtie < Rails::Railtie
+    initializer 'fun_with_json_api.add_locales' do
+      translations = File.expand_path('../../../config/locales/**/*.{rb,yml}', __FILE__)
+      Dir.glob(translations) { |f| config.i18n.load_path << f.to_s }
+    end
+  end
+end

data/lib/fun_with_json_api/version.rb

@@ -0,0 +1,3 @@
+module FunWithJsonApi
+  VERSION = '0.0.1'.freeze
+end

data/lib/fun_with_json_api.rb

@@ -0,0 +1,24 @@
+require 'fun_with_json_api/exception'
+require 'fun_with_json_api/attribute'
+
+require 'fun_with_json_api/pre_deserializer'
+require 'fun_with_json_api/deserializer'
+require 'fun_with_json_api/deserializer_config_builder'
+
+# Makes working with JSON:API fun!
+module FunWithJsonApi
+  module_function
+
+  def deserialize(api_document, deserializer_class, options = {})
+    # Prepare the deserializer and the expected config
+    deserializer = deserializer_class.create(options)
+
+    # Run through initial document structure validation and deserialization
+    unfiltered = FunWithJsonApi::PreDeserializer.parse(api_document, deserializer)
+
+    # Ensure document matches schema, and sanitize values
+    deserializer.sanitize_params(unfiltered)
+  end
+end
+
+require 'fun_with_json_api/railtie' if defined?(Rails)