media_types-serialization 0.8.0 → 1.1.0

data/lib/media_types/serialization/base.rb

@@ -1,126 +1,150 @@
 # frozen_string_literal: true
 
-require 'uri'
-
-require 'http_headers/link'
-require 'http_headers/utils/list'
-
-require 'media_types/serialization/mime_type_support'
-require 'media_types/serialization/migrations_support'
-require 'media_types/serialization/wrapper_support'
+require 'media_types/serialization/error'
+require 'media_types/serialization/fake_validator'
+require 'media_types/serialization/serialization_registration'
+require 'media_types/serialization/serialization_dsl'
 
 module MediaTypes
   module Serialization
     class Base
-      include MimeTypeSupport
-      include MigrationsSupport
-      include WrapperSupport
+      module ClassMethods
+        def unvalidated(prefix)
+          self.serializer_validated = false
+          self.serializer_validator = FakeValidator.new(prefix)
+          self.serializer_input_registration = SerializationRegistration.new(:input)
+          self.serializer_output_registration = SerializationRegistration.new(:output)
+        end
 
-      attr_reader :current_media_type, :current_view, :serializable
+        def validator(validator = nil)
+          raise NoValidatorSetError if !defined? serializer_validator && validator.nil?
+          return serializer_validator if validator.nil?
 
-      def initialize(serializable, media_type:, view: nil, context:)
-        self.context = context
-        self.current_media_type = media_type
-        self.current_view = view
+          self.serializer_validated = true
+          self.serializer_validator = validator
+          self.serializer_input_registration = SerializationRegistration.new(:input)
+          self.serializer_output_registration = SerializationRegistration.new(:output)
+        end
 
-        set(serializable)
-      end
+        def disable_wildcards
+          self.serializer_disable_wildcards = true
+        end
 
-      def to_link_header
-        entries = header_links(view: current_view).each_with_index.map do |(rel, links), index|
-          links = [links] unless links.is_a?(Array)
+        def enable_wildcards
+          self.serializer_disable_wildcards = false
+        end
+
+        def output(view: nil, version: nil, versions: nil, &block)
+          versions = [version] if versions.nil?
+          raise VersionsNotAnArrayError unless versions.is_a? Array
+
+          raise ValidatorNotSpecifiedError, :output if serializer_validator.nil?
 
-          links.map do |opts|
-            next unless opts.is_a?(String) || opts.try(:[], :href)
-            href = opts.is_a?(String) ? opts : opts.delete(:href)
-            parameters =  { rel: rel }.merge(opts.is_a?(String) ? {} : opts)
+          versions.each do |v|
+            validator = serializer_validator.view(view).version(v)
+            validator.override_suffix(:json) unless serializer_validated
 
-            HttpHeaders::Link::Entry.new("<#{href}>", index: index, parameters: parameters)
+            serializer_output_registration.register_block(self, validator, v, block, false, wildcards: !self.serializer_disable_wildcards)
           end
-        end.flatten.compact
+        end
 
-        return nil unless entries.present?
-        HttpHeaders::Utils::List.to_header(entries)
-      end
+        def output_raw(view: nil, version: nil, versions: nil, &block)
+          versions = [version] if versions.nil?
+          raise VersionsNotAnArrayError unless versions.is_a? Array
 
-      COMMON_DERIVED_CALLERS = [:to_h, :to_hash, :to_json, :to_text, :to_xml, :to_html, :to_body, :extract_self].freeze
+          raise ValidatorNotSpecifiedError, :output if serializer_validator.nil?
 
-      def method_missing(symbol, *args, &block)
-        if COMMON_DERIVED_CALLERS.include?(symbol)
-          raise NotImplementedError, format(
-            'In %<class>s, %<symbol>s is not implemented. ' \
-            'Implement it or deny the MediaType[s] %<media_types>s for %<model>s',
-            symbol: symbol,
-            class: self.class.name,
-            model: serializable.class.name,
-            media_types: self.class.media_types(view: '[view]').to_s
-          )
+          versions.each do |v|
+            validator = serializer_validator.view(view).version(v)
+
+            serializer_output_registration.register_block(self, validator, v, block, true, wildcards: !self.serializer_disable_wildcards)
+          end
         end
 
-        super
-      end
+        def output_alias(media_type_identifier, view: nil, hide_variant: false)
+          validator = serializer_validator.view(view)
+          victim_identifier = validator.identifier
 
-      def respond_to_missing?(method_name, include_private = false)
-        if COMMON_DERIVED_CALLERS.include?(method_name)
-          return false
+          serializer_output_registration.register_alias(self, media_type_identifier, victim_identifier, false, hide_variant, wildcards: !self.serializer_disable_wildcards)
         end
 
-        super
-      end
+        def output_alias_optional(media_type_identifier, view: nil, hide_variant: false)
+          validator = serializer_validator.view(view)
+          victim_identifier = validator.identifier
 
-      def header_links(view: current_view)
-        extract_view_links(view: view)
-      end
+          serializer_output_registration.register_alias(self, media_type_identifier, victim_identifier, true, hide_variant, wildcards: !self.serializer_disable_wildcards)
+        end
 
-      def set(serializable)
-        self.serializable = serializable
-        self
-      end
+        def input(view: nil, version: nil, versions: nil, &block)
+          versions = [version] if versions.nil?
+          raise VersionsNotAnArrayError unless versions.is_a? Array
 
-      protected
+          raise ValidatorNotSpecifiedError, :input if serializer_validator.nil?
 
-      attr_accessor :context
-      attr_writer :current_media_type, :current_view, :serializable
+          versions.each do |v|
+            validator = serializer_validator.view(view).version(v)
+            validator.override_suffix(:json) unless serializer_validated
 
-      def extract_links
-        {}
-      end
+            serializer_input_registration.register_block(self, validator, v, block, false)
+          end
+        end
 
-      def extract_set_links(view: current_view)
-        {}
-      end
+        def input_raw(view: nil, version: nil, versions: nil, &block)
+          versions = [version] if versions.nil?
+          raise VersionsNotAnArrayError unless versions.is_a? Array
 
-      def extract_view_links(view: current_view)
-        return extract_set_links(view: view) if view == ::MediaTypes::INDEX_VIEW
-        return extract_set_links(view: view) if view == ::MediaTypes::COLLECTION_VIEW
+          raise ValidatorNotSpecifiedError, :input if serializer_validator.nil?
 
-        extract_links
-      end
+          versions.each do |v|
+            validator = serializer_validator.view(view).version(v)
+
+            serializer_input_registration.register_block(self, validator, v, block, true)
+          end
+        end
+
+        def input_alias(media_type_identifier, view: nil)
+          validator = serializer_validator.view(view)
+          victim_identifier = validator.identifier
+
+          serializer_input_registration.register_alias(self, media_type_identifier, victim_identifier, false)
+        end
+
+        def input_alias_optional(media_type_identifier, view: nil)
+          validator = serializer_validator.view(view)
+          victim_identifier = validator.identifier
+
+          serializer_input_registration.register_alias(self, media_type_identifier, victim_identifier, true)
+        end
+
+        def serialize(victim, media_type_identifier, context, dsl: nil, raw: nil)
+          dsl ||= SerializationDSL.new(self, context: context)
+          serializer_output_registration.call(victim, media_type_identifier.to_s, context, dsl: dsl, raw: raw)
+        end
+
+        def deserialize(victim, media_type_identifier, context)
+          serializer_input_registration.call(victim, media_type_identifier, context)
+        end
 
-      def extract(extractable, *keys)
-        return {} unless keys.present?
-        extractable.slice(*keys)
-      rescue TypeError => err
-        raise TypeError, format(
-          '[serializer] failed to slice keys to extract. Given keys: %<keys>s. Extractable: %<extractable>s' \
-          'Error: %<error>s',
-          keys: keys,
-          extractable: extractable,
-          error: err
-        )
+        def outputs_for(views:)
+          serializer_output_registration.filter(views: views)
+        end
+
+        def inputs_for(views:)
+          serializer_input_registration.filter(views: views)
+        end
       end
 
-      def resolve_file_url(url)
-        return url if !url || URI(url).absolute?
-
-        format(
-          'https://%<host>s:%<port>s%<path>s',
-          host: context.default_url_options[:host],
-          port: context.default_url_options[:port],
-          path: url
-        )
-      rescue URI::InvalidURIError
-        url
+      def self.inherited(subclass)
+        subclass.extend(ClassMethods)
+        subclass.instance_eval do
+          class << self
+            attr_accessor :serializer_validated
+            attr_accessor :serializer_validator
+            attr_accessor :serializer_input_registration
+            attr_accessor :serializer_output_registration
+            attr_accessor :serializer_disable_wildcards
+          end
+        end
       end
     end
   end

data/lib/media_types/serialization/error.rb

@@ -3,5 +3,191 @@ module MediaTypes
   module Serialization
     class Error < StandardError
     end
+
+    class ControlFlowError < Error
+    end
+
+    class InputNotAcceptableError < ControlFlowError
+      def initialize
+        super('Content-Type provided in the request is not acceptable.')
+      end
+    end
+
+    class RuntimeError < Error
+    end
+
+    class NoInputReceivedError < RuntimeError
+      def initialize
+        super('No Content-Type specified in request.')
+      end
+    end
+
+    class InputValidationFailedError < RuntimeError
+      def initialize(inner)
+        @inner = inner
+        super(inner.message)
+      end
+    end
+
+    class OutputValidationFailedError < RuntimeError
+      def initialize(inner)
+        @inner = inner
+        super(inner.message)
+      end
+    end
+
+    class CollectionTypeError < RuntimeError
+      def initialize(type)
+        super("Unable to serialize the collection. Input was of type #{type} but I expected an Array.")
+      end
+    end
+
+    class UnsupportedMediaTypeError < RuntimeError
+      def initialize(available)
+        super("The controller was unable to process your Content-Type. Please use one of: [#{available.join(', ')}]")
+      end
+    end
+
+    class ConfigurationError < Error
+    end
+
+    class CannotDecodeOutputError < ConfigurationError
+      def initialize
+        super('Unable to call decode on an output registration.')
+      end
+    end
+
+    class ValidatorNotSpecifiedError < ConfigurationError
+      def initialize(inout)
+        super("Serializer tried to define an #{inout} without first specifying a validator using either the validator function or unvalidated function. Please call one of those before defining #{inout}s.")
+      end
+    end
+
+    class ValidatorNotDefinedError < ConfigurationError
+      def initialize(identifier, inout)
+        super("Serializer tried to define an #{inout} using the media type identifier #{identifier}, but no validation has been set up for that identifier. Please add it to the validator.")
+      end
+    end
+
+    class UnbackedAliasDefinitionError < ConfigurationError
+      def initialize(identifier, inout)
+        super(
+            "Serializer tried to define an #{inout}_alias that points to the media type identifier #{identifier} but no such #{inout} has been defined yet. Please move the #{inout} definition above the alias.\n\n" \
+            "Move the #{inout} definition above the alias:\n" \
+            "\n" \
+            "class MySerializer < MediaTypes::Serialization::Base\n" \
+            "#...\n" \
+            "#{inout} do\n" \
+            "  # ...\n" \
+            "end\n" \
+            "\n" \
+            "#{inout}_alias 'text/html'\n" \
+            "# ^----- move here\n" \
+            'end'
+        )
+      end
+    end
+
+    class VersionedAliasDefinitionError < ConfigurationError
+      def initialize(identifier, inout, prefix_match)
+        super(
+          "Serializer tried to define an #{inout}_alias that points to the media type identifier #{identifier} but no such #{inout} has been defined yet. An #{inout} named #{prefix_match} was found. Often this can be fixed by providing an #{inout} with a nil version."
+        )
+      end
+    end
+
+    class DuplicateDefinitionError < ConfigurationError
+      def initialize(identifier, inout)
+        super("Serializer tried to define an #{inout} using the media type identifier #{identifier}, but another #{inout} was already defined with that identifier. Please remove one of the two.")
+      end
+    end
+
+    class DuplicateUsageError < ConfigurationError
+      def initialize(identifier, inout, serializer1, serializer2)
+        super("Controller tried to use two #{inout} serializers (#{serializer1}, #{serializer2}) that both have a non-optional #{inout} defined for the media type identifier #{identifier}. Please remove one of the two or filter them more specifically.")
+      end
+    end
+
+    class UnregisteredMediaTypeUsageError < ConfigurationError
+      def initialize(identifier, available)
+        super("A serialization or deserialization method was called using a media type identifier '#{identifier}' but no such identifier has been registered yet. Available media types: [#{available.join ', '}]")
+      end
+    end
+
+    class UnmatchedSerializerError < ConfigurationError
+      def initialize(serializer)
+        super("Called render_media with a resolved serializer that was not specified in the do block. Please add a 'serializer #{serializer.name}, <value>' entry.")
+      end
+    end
+
+    class VersionsNotAnArrayError < ConfigurationError
+      def initialize
+        super('Tried to create an input or output with a versions: parameter that is set to something that is not an array. Please use the version: parameter or conver the current value to an array.')
+      end
+    end
+    class ViewsNotAnArrayError < ConfigurationError
+      def initialize
+        super('Tried to create an input or output with a views: parameter that is set to something that is not an array. Please use the view: parameter or conver the current value to an array.')
+      end
+    end
+
+    class NoValidatorSetError < ConfigurationError
+      def initialize
+        super("Unable to return validator as no validator has been set. Either someone tried to fetch the currently defined validator or someone tried to set the validator to 'nil'.")
+      end
+    end
+
+    class NoSelfLinkProvidedError < ConfigurationError
+      def initialize(media_type_identifier)
+        super("Tried to render an index of '#{media_type_identifier}' elements but the serializer did not return a :self link for me to use. Please call 'link rel: :self, href: 'https://...' in the #{media_type_identifier} serializer.")
+      end
+    end
+
+    class MultipleSelfLinksProvidedError < ConfigurationError
+      def initialize(media_type_identifier)
+        super("Tried to render an index of '#{media_type_identifier}' elements but the serializer returned more than one :self link. Please make sure to only call 'link rel: :self, ...' once in the #{media_type_identifier} serializer.")
+      end
+    end
+
+    class ArrayInViewParameterError < ConfigurationError
+      def initialize(function)
+        super("Tried to call #{function} with an array in the view: parameter. Please use the views: parameter instead.")
+      end
+    end
+
+    class SerializersNotFrozenError < ConfigurationError
+      def initialize
+        super("Unable to serialize or deserialize objects with unfrozen serializers. Please add 'freeze_io!' to the controller definition.")
+      end
+    end
+
+    class SerializersAlreadyFrozenError < ConfigurationError
+      def initialize
+        super("Unable to add a serializer when they are already frozen. Please make sure to call 'freeze_io!' last.")
+      end
+    end
+
+    class UnableToRefreezeError < ConfigurationError
+      def initialize
+        super("Freeze was called while the serializers are already frozen. Please make sure to only call 'freeze_io!' once.")
+      end
+    end
+
+    class NoOutputSerializersDefinedError < ConfigurationError
+      def intialize
+        super("Called freeze_io! without any allowed output serializers. Users won't be able to make any requests. Please make sure to add at least one allow_output_serializer call to your controller.")
+      end
+    end
+
+    class AddedEmptyOutputSerializer < ConfigurationError
+      def initialize(name)
+        super("A serializer with name '#{name}' was just added to the controller but it contained no output definitions. Usually this is due to using the wrong view parameter when adding it.")
+      end
+    end
+    class AddedEmptyInputSerializer < ConfigurationError
+      def initialize(name)
+        super("A serializer with name '#{name}' was just added to the controller but it contained no input definitions. Usually this is due to using the wrong view parameter when adding it.")
+      end
+    end
   end
 end

data/lib/media_types/serialization/fake_validator.rb

@@ -0,0 +1,52 @@
+
+# Validator that accepts all input
+class FakeValidator
+  def initialize(prefix, view = nil, version = nil, suffixes = {})
+    self.prefix = prefix
+    self.suffixes = suffixes
+    self.internal_view = view
+    self.internal_version = version
+  end
+
+  UNSET = Object.new
+
+  def view(view = UNSET)
+    return self.internal_view if view == UNSET
+    FakeValidator.new(prefix, view, internal_version, suffixes)
+  end
+
+  def version(version = UNSET)
+    return self.internal_version if version == UNSET
+    FakeValidator.new(prefix, internal_view, version, suffixes)
+  end
+
+  def override_suffix(suffix)
+    suffixes[[internal_view, internal_version]] = suffix
+  end
+
+  def identifier
+    suffix = suffixes[[internal_view, internal_version]] || ''
+    result = prefix
+    result += '.v' + internal_version.to_s unless internal_version.nil?
+    result += '.' + internal_view.to_s unless internal_view.nil?
+    result += '+' + suffix.to_s unless suffix.empty?
+
+    result
+  end
+
+  def validatable?
+    true
+  end
+
+  def validate!(_)
+    true
+  end
+
+  attr_accessor :prefix
+  attr_accessor :suffixes
+
+  protected
+
+  attr_accessor :internal_view
+  attr_accessor :internal_version
+end