media_types 0.1.0

data/lib/media_types/base/collector.rb

@@ -0,0 +1,44 @@
+# frozen_string_literal: true
+
+require 'delegate'
+
+module MediaTypes
+  class Base
+    class Collector < SimpleDelegator
+
+      def index(*args, **options)
+        view(INDEX_VIEW, *args, **options)
+      end
+
+      def create(*args, **options, &block)
+        view(CREATE_VIEW, *args, **options, &block)
+      end
+
+      def collection(*args, **options)
+        view(COLLECTION_VIEW, *args, **options)
+      end
+
+      def view(view, *args, **options)
+        register_type(*args, **options.merge(view: view))
+      end
+
+      def version(*args, **options, &block)
+        register_version(*args, **options, &block)
+      end
+
+      private
+
+      # This is similar to having a decorator / interface only exposing certain methods. In this private section
+      #   the +register_type+ and +register_version+ methods are made available
+      #
+
+      def register_type(*args, **options, &block)
+        __getobj__.instance_exec { register_type(*args, options, &block) }
+      end
+
+      def register_version(*args, **options, &block)
+        __getobj__.instance_exec { register_version(*args, options, &block) }
+      end
+    end
+  end
+end

data/lib/media_types/constructable_mime_type.rb

@@ -0,0 +1,126 @@
+# frozen_string_literal: true
+
+require 'delegate'
+require 'singleton'
+
+module MediaTypes
+  class ConstructableMimeType < SimpleDelegator
+
+    def initialize(klazz, **opts)
+      super klazz
+      self.opts = opts
+    end
+
+    def version(version = NO_ARG)
+      return opts[:version] if version == NO_ARG
+      ConstructableMimeType.new(__getobj__, **with(version: version))
+    end
+
+    def view(view = NO_ARG)
+      return opts[:view] if view == NO_ARG
+      ConstructableMimeType.new(__getobj__, **with(view: view))
+    end
+
+    def suffix(suffix = NO_ARG)
+      return opts[:suffix] if suffix == NO_ARG
+      ConstructableMimeType.new(__getobj__, **with(suffix: suffix))
+    end
+
+    def collection
+      view(COLLECTION_VIEW)
+    end
+
+    def collection?
+      opts[:view] == COLLECTION_VIEW
+    end
+
+    def create
+      view(CREATE_VIEW)
+    end
+
+    def create?
+      opts[:view] == CREATE_VIEW
+    end
+
+    def index
+      view(INDEX_VIEW)
+    end
+
+    def index?
+      opts[:view] == INDEX_VIEW
+    end
+
+    def ===(other)
+      to_str.send(:===, other)
+    end
+
+    def ==(other)
+      to_str.send(:==, other)
+    end
+
+    def +(other)
+      to_str + other
+    end
+
+    def split(pattern = nil, *limit)
+      to_str.split(pattern, *limit)
+    end
+
+    def hash
+      to_str.hash
+    end
+
+    def to_str(qualifier = nil)
+      # TODO: remove warning by slicing out these arguments if they don't appear in the format
+      qualified(qualifier, @to_str ||= format(
+        opts.fetch(:format),
+        version: opts.fetch(:version),
+        suffix: opts.fetch(:suffix) { :json },
+        type: opts.fetch(:type),
+        view: format_view(opts[:view])
+      ))
+    end
+
+    def valid?(output, **validation_opts)
+      __getobj__.valid?(
+        output,
+        version: opts[:version],
+        **validation_opts
+      )
+    end
+
+    def validate!(output, **validation_opts)
+      __getobj__.validate!(
+        output,
+        version: opts[:version],
+        **validation_opts
+      )
+    end
+
+    alias inspect to_str
+    alias to_s to_str
+
+    private
+
+    class NoArgumentGiven
+      include Singleton
+    end
+
+    NO_ARG = NoArgumentGiven.instance
+
+    attr_accessor :opts
+
+    def with(more_opts)
+      Hash(opts).merge(more_opts).dup
+    end
+
+    def qualified(qualifier, media_type)
+      return media_type unless qualifier
+      format('%<media_type>s; q=%<q>s', media_type: media_type, q: qualifier)
+    end
+
+    def format_view(view)
+      MediaTypes::Object.new(view).present? && ".#{view}" || ''
+    end
+  end
+end

data/lib/media_types/minitest/assert_media_type_format.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+module Assertions
+  module MediaTypes
+    def assert_media_type_format(media_type, output, **opts)
+      if media_type.collection?
+        output[:_embedded].each do |embedded|
+          assert_media_type_format(media_type.view(nil), embedded, **opts)
+        end
+        return
+      end
+
+      if media_type.index?
+        return output[:_index] # TODO: sub_schema the "self" link
+      end
+
+      assert media_type.validate!(output, **opts)
+    end
+  end
+end

data/lib/media_types/minitest/assert_media_types_registered.rb

@@ -0,0 +1,143 @@
+# frozen_string_literal: true
+
+require 'minitest/mock'
+
+module MediaTypes
+  module Assertions
+    class << self
+      def block_exec_instance(instance, &block)
+        case block.arity
+        when 1, -1
+          instance.instance_exec(instance, &block)
+        else
+          instance.instance_exec(&block)
+        end
+      end
+    end
+
+    def assert_media_types_registered(media_type, &block)
+      collector = Collector.new(media_type)
+      Assertions.block_exec_instance(collector, &block)
+      assert_registered_types(media_type, collector.prepare_verify)
+    end
+
+    class Collector
+      def initialize(media_type)
+        self.media_type = media_type
+        self.registers = {}
+      end
+
+      def mime_type(mime_type, symbol:, synonyms: [])
+        registers[mime_type] = { symbol: symbol, synonyms: synonyms }
+      end
+
+      def formatted_mime_type(mime_type_format, &block)
+        collector = FormattedCollector.new(mime_type_format, {})
+        Assertions.block_exec_instance(collector, &block)
+        registers.merge!(collector.to_h)
+      end
+
+      def prepare_verify
+        expected_types_hash = registers.dup
+        expected_types_hash.each do |key, value|
+          expected_types_hash[key] = [value[:symbol], Array(value[:synonyms])]
+        end
+
+        expected_types_hash
+      end
+
+      private
+
+      attr_accessor :media_type, :registers
+    end
+
+    class FormattedCollector
+      def initialize(format, args = {})
+        self.mime_type_format = format
+        self.format_args = args
+        self.registers = {}
+      end
+
+      def version(version, **opts, &block)
+        new_format_args = format_args.merge(version: version)
+        register(new_format_args, **opts, &block)
+      end
+
+      def view(view, **opts, &block)
+        new_format_args = format_args.merge(view: view)
+        register(new_format_args, **opts, &block)
+      end
+
+      def create(**opts, &block)
+        view(Base::CREATE_VIEW, **opts, &block)
+      end
+
+      def collection(**opts, &block)
+        view(Base::COLLECTION_VIEW, **opts, &block)
+      end
+
+      def index(**opts, &block)
+        view(Base::INDEX_VIEW, **opts, &block)
+      end
+
+      def to_h
+        Hash(registers)
+      end
+
+      private
+
+      attr_accessor :mime_type_format, :registers, :format_args
+
+      def register(new_format_args, symbol: nil, synonyms: [], &block)
+        if block_given?
+          collector = FormattedCollector.new(mime_type_format, new_format_args)
+          Assertions.block_exec_instance(collector, &block)
+          registers.merge!(collector.to_h)
+        else
+          formatted_mime_type_format = format(mime_type_format, **new_format_args)
+          registers[formatted_mime_type_format] = { symbol: symbol, synonyms: synonyms }
+        end
+      end
+    end
+
+    # rubocop:disable Metrics/AbcSize, Metrics/MethodLength
+    def assert_registered_types(media_type, expected_types_hash)
+      mock = Minitest::Mock.new
+      uncalled = expected_types_hash.dup
+
+      uncalled.length.times do
+        mock.expect(:call, nil) do |arguments|
+          type = arguments.fetch(:mime_type)
+          symbol = arguments.fetch(:symbol)
+          synonyms = arguments.fetch(:synonyms)
+
+          options = uncalled.delete(type)
+          options && options == [symbol, synonyms] || raise(
+            MockExpectationError,
+            format(
+              'Called with [type: %<type>s, symbol: %<symbol>s, synonyms: %<synonyms>s]' + "\n"\
+              'Resolved options: [%<resolved>s]' + "\n"\
+              'Uncalled options: [%<uncalled>s]',
+              type: type,
+              symbol: symbol,
+              synonyms: synonyms,
+              resolved: options,
+              uncalled: uncalled
+            )
+          )
+        end
+      end
+
+      MediaTypes.stub(:register, mock) do
+        if block_given?
+          yield media_type
+        else
+          media_type.register.flatten
+        end
+      end
+
+      assert_mock mock
+    end
+    # rubocop:enable Metrics/AbcSize, Metrics/MethodLength
+  end
+end

data/lib/media_types/scheme.rb

@@ -0,0 +1,238 @@
+# frozen_string_literal: true
+
+require 'media_types/scheme/allow_nil'
+require 'media_types/scheme/attribute'
+require 'media_types/scheme/links'
+require 'media_types/scheme/missing_validation'
+require 'media_types/scheme/not_strict'
+
+module MediaTypes
+  class ValidationError < ArgumentError
+  end
+
+  class ExhaustedOutputError < ValidationError
+  end
+
+  class StrictValidationError < ValidationError
+  end
+
+  class EmptyOutputError < ValidationError
+  end
+
+  ##
+  # Media Type Schemes can validate content to a media type, by itself.
+  #
+  class Scheme
+    def initialize(allow_empty: false)
+      self.validations = {}
+      self.allow_empty = allow_empty
+
+      validations.default = MissingValidation.new
+    end
+
+    ##
+    # Checks if the +output+ is valid
+    #
+    # @param [#each] output
+    # @param [Hash] opts
+    # @option exhaustive [Boolean] opts
+    # @option strict [Boolean] opts
+    #
+    # @return [Boolean] true if valid, false otherwise
+    #
+    def valid?(output, **opts)
+      validate(output, **opts)
+    rescue ExhaustedOutputError
+      !opts.fetch(:exhaustive) { true }
+    rescue ValidationError
+      false
+    end
+
+    class ValidationOptions
+      attr_accessor :exhaustive, :strict, :backtrace
+
+      def initialize(exhaustive: true, strict: true, backtrace: [])
+        self.exhaustive = exhaustive
+        self.strict = strict
+        self.backtrace = backtrace
+      end
+
+      def with_backtrace(backtrace)
+        ValidationOptions.new(exhaustive: exhaustive, strict: strict, backtrace: backtrace)
+      end
+
+      def trace(*traces)
+        with_backtrace(backtrace.dup.concat(traces))
+      end
+
+      def exhaustive!
+        ValidationOptions.new(exhaustive: true, strict: strict, backtrace: backtrace)
+      end
+    end
+
+    ##
+    # Validates the +output+ and raises on certain validation errors
+    #
+    # @param [#each] output output to validate
+    # @option opts [Boolean] exhaustive if true, the entire schema needs to be consumed
+    # @option opts [Boolean] strict if true, no extra keys may be present in +output+
+    # @option opts[Array<String>] backtrace the current backtrace for error messages
+    #
+    # @raise ExhaustedOutputError
+    # @raise StrictValidationError
+    # @raise EmptyOutputError
+    # @raise ValidationError
+    #
+    # @return [TrueClass]
+    #
+    def validate(output, options = nil, **opts)
+      options ||= ValidationOptions.new(**opts)
+
+      catch(:end) do
+        validate!(output, options, context: nil)
+      end
+    end
+
+    def validate!(output, call_options, **_opts)
+      empty_guard!(output, call_options)
+
+      exhaustive_guard!(validations.keys, call_options) do |mark|
+        all?(output, call_options) do |key, value, options:, context:|
+          mark.call(key)
+
+          validations[key].validate!(
+            value,
+            options.trace(key),
+            context: context
+          )
+        end
+      end
+    end
+
+    ##
+    # Adds an attribute to the schema
+    #
+    # @param key [Symbol] the attribute name
+    # @param type [Class, #===] The type of the value, can be anything that responds to #===
+    # @param opts [Hash] options
+    #
+    # @example Add an attribute named foo, expecting a string
+    #
+    #   class MyMedia < Base
+    #     current_schema do
+    #       attribute :foo, String
+    #     end
+    #   end
+    #
+    def attribute(key, type = String, **opts, &block)
+      validations[key] = Attribute.new(type, **opts, &block)
+    end
+
+    ##
+    # Allow for any key.
+    #   The +block+ defines the Schema for each value.
+    #
+    # @param [Boolean] allow_empty if true, empty (no key/value present) is allowed
+    #
+    def any(allow_empty: false, &block)
+      scheme = Scheme.new(allow_empty: allow_empty)
+      scheme.instance_exec(&block)
+
+      validations.default = scheme
+    end
+
+    ##
+    # Allow for extra keys in the schema/collection
+    #   even when passing strict: true to #validate!
+    #
+    def not_strict
+      validations.default = NotStrict.new
+    end
+
+    ##
+    # Expect a collection such as an array or hash.
+    #   The +block+ defines the Schema for each item in that collection.
+    #
+    # @param [Symbol] key
+    # @param [Boolean] allow_empty, if true accepts 0 items in an array / hash
+    #
+    def collection(key, allow_empty: false, &block)
+      scheme = Scheme.new(allow_empty: allow_empty)
+      scheme.instance_exec(&block)
+
+      validations[key] = scheme
+    end
+
+    ##
+    # Expect a link
+    #
+    def link(*args, **opts, &block)
+      validations.fetch(:_links) do
+        Links.new.tap do |links|
+          validations[:_links] = links
+        end
+      end.link(*args, **opts, &block)
+    end
+
+    private
+
+    attr_accessor :validations, :allow_empty
+
+    def empty_guard!(output, options)
+      return unless output.nil? || output.empty?
+      throw(:end, true) if allow_empty
+      raise_empty!(backtrace: options.backtrace)
+    end
+
+    class EnumerationContext
+      def initialize(validations:)
+        self.validations = validations
+      end
+
+      def enumerate(val)
+        self.key = val
+        self
+      end
+
+      attr_accessor :validations, :key
+    end
+
+    def all?(enumerable, options, &block)
+      context = EnumerationContext.new(validations: validations)
+
+      if enumerable.is_a?(Hash) || enumerable.respond_to?(:key)
+        return enumerable.all? do |key, value|
+          yield key, value, options: options, context: context.enumerate(key)
+        end
+      end
+
+      enumerable.each_with_index.all? do |array_like_element, i|
+        all?(array_like_element, options.trace(i), &block)
+      end
+    end
+
+    def raise_empty!(backtrace:)
+      raise EmptyOutputError, format('Expected output, got empty at %<backtrace>s', backtrace: backtrace.join('->'))
+    end
+
+    def raise_exhausted!(backtrace:, missing_keys:)
+      raise ExhaustedOutputError, format(
+        'Missing keys in output: %<missing_keys>s at [%<backtrace>s]',
+        missing_keys: missing_keys,
+        backtrace: backtrace.join('->')
+      )
+    end
+
+    def exhaustive_guard!(keys, options)
+      unless options.exhaustive
+        return yield(->(_) {})
+      end
+
+      exhaustive_keys = keys.dup
+      result = yield ->(key) { exhaustive_keys.delete(key) }
+      return result if exhaustive_keys.empty?
+
+      raise_exhausted!(missing_keys: exhaustive_keys, backtrace: options.backtrace)
+    end
+  end
+end