media_types-serialization 0.8.0 → 1.1.0

data/lib/media_types/serialization/serialization_dsl.rb

@@ -0,0 +1,117 @@
+# frozen_string_literal: true
+
+require 'delegate'
+
+module MediaTypes
+  module Serialization
+    # Provides the serialization convenience methods
+    class SerializationDSL < SimpleDelegator
+      def initialize(serializer, links = [], vary = ['Accept'], value = {}, context: nil)
+        self.serialization_dsl_result = value
+        @serialization_links = links
+        @serialization_context = context
+        @serialization_vary = vary
+        super(serializer)
+      end
+
+      attr_accessor :serialization_dsl_result
+
+      def attribute(key, value = {}, &block)
+        unless block.nil?
+          subcontext = SerializationDSL.new(__getobj__, @serialization_links, @serialization_vary, value, context: @serialization_context)
+          value = subcontext.instance_exec(&block)
+        end
+
+        serialization_dsl_result[key] = value
+
+        serialization_dsl_result
+      end
+
+      def link(rel, href:, emit_header: true, **attributes)
+        serialization_dsl_result[:_links] = {} unless serialization_dsl_result.has_key? :_links
+
+        link = {
+          href: href,
+          rel: rel,
+        }
+        link = link.merge(attributes)
+
+        json = {
+          href: href,
+        }
+        json = json.merge(attributes)
+
+        @serialization_links.append(link) if emit_header
+        serialization_dsl_result[:_links][rel] = json
+
+        serialization_dsl_result
+      end
+
+      def index(array, serializer = __getobj__, version:, view: nil)
+        raise CollectionTypeError, array.class.name unless array.is_a? Array
+
+        links = []
+        identifier = serializer.serializer_validator.view(view).version(version).identifier
+
+        array.each do |e|
+          child_links = []
+          context = SerializationDSL.new(__getobj__, child_links, context: @serialization_context)
+          serializer.serialize(e, identifier, @serialization_context, dsl: context)
+
+          self_links = child_links.select { |l| l[:rel] == :self }
+          raise NoSelfLinkProvidedError, identifier unless self_links.any?
+          raise MultipleSelfLinksProvidedError, identifier if self_links.length > 1
+
+          links.append(self_links.first.reject { |k, _| k == :rel } )
+        end
+
+        serialization_dsl_result[:_index] = links
+
+        serialization_dsl_result
+      end
+
+      def collection(array, serializer = __getobj__, version:, view: nil, &block)
+        raise CollectionTypeError, array.class.name unless array.is_a? Array
+
+        identifier = serializer.serializer_validator.view(view).version(version).identifier
+
+        rendered = []
+
+        array.each do |e|
+          context = SerializationDSL.new(__getobj__, [], @serialization_vary, context: @serialization_context)
+          result = serializer.serialize(e, identifier, @serialization_context, dsl: context, raw: true)
+
+          result = block.call(result) unless block.nil?
+
+          rendered.append(result)
+        end
+
+        serialization_dsl_result[:_embedded] = rendered
+
+        serialization_dsl_result
+      end
+
+      def hidden(&block)
+        context = SerializationDSL.new(__getobj__, @serialization_links, context: @serialization_context)
+        context.instance_exec(&block)
+
+        serialization_dsl_result
+      end
+
+      def render_view(name, context:, **args)
+        context.render_to_string(name, **args)
+      end
+
+      def emit
+        serialization_dsl_result
+      end
+      
+      def object(&block)
+        context = SerializationDSL.new(__getobj__, @serialization_links, @serialization_vary, context: @serialization_context)
+        context.instance_exec(&block)
+
+        context.serialization_dsl_result
+      end
+    end
+  end
+end

data/lib/media_types/serialization/serialization_registration.rb

@@ -0,0 +1,245 @@
+# frozen_string_literal: true
+
+require 'media_types/serialization/error'
+require 'media_types'
+
+module MediaTypes
+  module Serialization
+    # A collection that manages media type identifier registrations
+    class SerializationRegistration
+      def initialize(direction)
+        self.registrations = {}
+        self.inout = direction
+      end
+
+      attr_accessor :registrations, :inout
+
+      def has?(identifier)
+        registrations.key? identifier
+      end
+
+      def register_block(serializer, validator, version, block, raw, wildcards: true)
+        identifier = validator.identifier
+
+        raise DuplicateDefinitionError.new(identifier, inout) if registrations.key? identifier
+
+        raise ValidatorNotDefinedError.new(identifier, inout) unless raw || validator.validatable?
+
+        registration = SerializationBlockRegistration.new serializer, inout, validator, identifier, version, block, raw
+        registrations[identifier] = registration
+
+        register_wildcards(identifier, registration) if wildcards && inout == :output
+      end
+
+      def register_alias(serializer, alias_identifier, target_identifier, optional, hide_variant, wildcards: true)
+        raise DuplicateDefinitionError.new(alias_identifier, inout) if registrations.key? alias_identifier
+
+        unless registrations.key? target_identifier
+          potential_match = registrations.keys.find do |k|
+            k.starts_with? target_identifier
+          end
+          raise VersionedAliasDefinitionError.new(target_identifier, inout, potential_match) unless potential_match.nil?
+          raise UnbackedAliasDefinitionError.new(target_identifier, inout)
+        end
+
+        target = registrations[target_identifier]
+
+        result_content_type = alias_identifier
+        result_content_type += "; variant=#{target_identifier}" unless hide_variant
+
+        registration = SerializationAliasRegistration.new serializer, inout, target.validator, result_content_type, target, optional, hide_variant
+        registrations[alias_identifier] = registration
+
+        register_wildcards(alias_identifier, registration) if wildcards && inout == :output
+      end
+
+      def merge(other)
+        raise Error, 'Trying to merge two SerializationRegistration objects with a different direction.' unless inout == other.inout
+
+        result = SerializationRegistration.new(inout)
+
+        prev_keys = Set.new(registrations.keys)
+        new_keys = Set.new(other.registrations.keys)
+        overlap = prev_keys & new_keys
+
+        result.registrations = registrations.merge(other.registrations)
+        overlap.each do |identifier|
+          prev_item = registrations[identifier]
+          new_item = other.registrations[identifier]
+          merge_result = prev_item.merge(new_item)
+
+          raise DuplicateUsageError.new(identifier, inout, prev_item.serializer, new_item.serializer) if merge_result.nil?
+
+          result.registrations[identifier] = merge_result
+        end
+
+        result
+      end
+
+      def decode(victim, media_type, context)
+        registration = registrations[media_type]
+        raise UnregisteredMediaTypeUsageError.new(media_type, registrations.keys) if registration.nil?
+
+        registration.decode(victim, context)
+      end
+
+      def call(victim, media_type, context, dsl: nil, raw: nil)
+        registration = registrations[media_type]
+        raise UnregisteredMediaTypeUsageError.new(media_type, registrations.keys) if registration.nil?
+
+        registration.call(victim, context, dsl: dsl, raw: raw)
+      end
+
+      def identifier_for(input_identifier)
+        registration = registrations[input_identifier]
+        raise UnregisteredMediaTypeUsageError.new(media_type, registrations.keys) if registration.nil?
+
+        registration.display_identifier
+      end
+
+      def filter(views:)
+        result = SerializationRegistration.new inout
+
+        registrations.each do |identifier, registration|
+          if views.include? registration.validator.view
+            result.registrations[identifier] = registration
+          end
+        end
+
+        result
+      end
+
+      private
+
+      def register_wildcards(identifier, registration)
+        new_alias = SerializationAliasRegistration.new registration.serializer, registration.inout, registration.validator, identifier, registration, true, true
+
+        registrations['*/*'] = new_alias unless has? '*/*'
+
+        partial = "#{identifier.split('/')[0]}/*"
+        registrations[partial] = new_alias unless has? partial
+      end
+    end
+
+    # A registration in a SerializationRegistration collection
+    class SerializationBaseRegistration
+      def initialize(serializer, inout, validator, display_identifier)
+        self.serializer = serializer
+        self.inout = inout
+        self.validator = validator
+        self.display_identifier = display_identifier
+      end
+
+      def merge(_other)
+        nil
+      end
+
+      def decode(_victim, _context)
+        raise 'Assertion failed, decode function called on base registration.'
+      end
+      def call(_victim, _context, dsl: nil, raw: nil)
+        raise 'Assertion failed, call function called on base registration.'
+      end
+
+      attr_accessor :serializer, :inout, :validator, :display_identifier
+    end
+
+    # A registration with a block to be executed when called.
+    class SerializationBlockRegistration < SerializationBaseRegistration
+      def initialize(serializer, inout, validator, display_identifier, version, block, raw)
+        self.version = version
+        self.block = block
+        self.raw = raw
+        super(serializer, inout, validator, display_identifier)
+      end
+      
+      def merge(other)
+        return nil unless other.is_a?(SerializationAliasRegistration)
+
+        return self if other.optional
+
+        nil
+      end
+
+      def decode(victim, _context)
+        raise CannotDecodeOutputError if inout != :input
+
+        unless raw
+          if defined? Oj::ParseError
+            begin
+              victim = MediaTypes::Serialization.json_decoder.call(victim)
+              validator.validate!(victim)
+            rescue MediaTypes::Scheme::ValidationError, Oj::ParseError, JSON::ParserError, EncodingError => inner
+              raise InputValidationFailedError, inner
+            end
+          else
+            begin
+              victim = MediaTypes::Serialization.json_decoder.call(victim)
+              validator.validate!(victim)
+            rescue MediaTypes::Scheme::ValidationError, JSON::ParserError, EncodingError => inner
+              raise InputValidationFailedError, inner
+            end
+          end
+        end
+
+        victim
+      end
+
+      def call(victim, context, dsl: nil, raw: nil)
+        raw = self.raw if raw.nil?
+
+        result = nil
+        if dsl.nil?
+          result = victim
+          result = block.call(victim, version, context) if block
+        else
+          result = dsl.instance_exec victim, version, context, &block
+        end
+
+        if !raw && inout == :output
+          begin
+            validator.validate!(result)
+          rescue MediaTypes::Scheme::ValidationError => inner
+            raise OutputValidationFailedError, inner
+          end
+          result = MediaTypes::Serialization.json_encoder.call(result)
+        end
+
+        result
+      end
+
+      attr_accessor :version, :block, :raw
+    end
+
+    # A registration that calls another registration when called.
+    class SerializationAliasRegistration < SerializationBaseRegistration
+      def initialize(serializer, inout, validator, display_identifier, target, optional, hide_variant)
+        self.target = target
+        self.optional = optional
+        self.hide_variant = hide_variant
+        super(serializer, inout, validator, display_identifier)
+      end
+
+      def merge(other)
+        if optional
+          return other unless other.is_a?(SerializationAliasRegistration)
+        else
+          return nil if other.is_a?(SerializationAliasRegistration) && !other.optional # two non-optional can't merge
+          return self
+        end
+
+        other # if both optional, or other is !optional, newer one wins.
+      end
+
+      def decode(victim, context)
+        target.decode(victim, context)
+      end
+
+      def call(victim, context, dsl: nil, raw: nil)
+        target.call(victim, context, dsl: dsl, raw: raw)
+      end
+
+      attr_accessor :target, :optional, :hide_variant
+    end
+  end
+end

data/lib/media_types/serialization/serializers/api_viewer.rb

@@ -0,0 +1,133 @@
+# frozen_string_literal: true
+
+require 'media_types/serialization/base'
+require 'erb'
+require 'cgi'
+
+module MediaTypes
+  module Serialization
+    module Serializers
+      class ApiViewer < MediaTypes::Serialization::Base
+        unvalidated 'text/html'
+
+        def self.viewerify(uri, current_host, type: 'last')
+          viewer = URI.parse(uri)
+
+          return uri unless viewer.host == current_host
+
+          query_parts = viewer.query&.split('&') || []
+          query_parts = query_parts.select { |p| !p.starts_with? 'api_viewer=' }
+          query_parts.append("api_viewer=#{type}")
+          viewer.query = query_parts.join('&')
+          viewer.to_s
+        end
+
+        output_raw do |obj, version, context|
+          original_identifier = obj[:identifier]
+          registrations = obj[:registrations]
+          original_output = obj[:output]
+          original_links = obj[:links]
+
+          api_fied_links = original_links.map do |l|
+            new = l.dup
+            new[:invalid] = false
+            begin
+              uri = viewerify(new[:href], context.request.host)
+              new[:href] = uri.to_s
+            rescue URI::InvalidURIError
+              new[:invalid] = true
+            end
+
+            new
+          end
+
+          media_types = registrations.registrations.keys.map do |identifier|
+            result = {
+              identifier: identifier,
+              href: viewerify(context.request.original_url, context.request.host, type: identifier),
+              selected: identifier == original_identifier,
+            }
+            result[:href] = '#output' if identifier == original_identifier
+
+            result
+          end
+
+
+          escaped_output = original_output&.split("\n").
+            map { |l| CGI::escapeHTML(l).gsub(/ (?= )/, '&nbsp;') }.
+            map { |l| (l.gsub(/\bhttps?:\/\/[-A-Z0-9+&@#\/%?=~_|!:,.;{}]*[-A-Z0-9+@#\/%=}~_|](?![a-z]*;)/i) do |m|
+              converted = m
+              invalid = false
+              begin
+                converted = viewerify(m, context.request.host)
+              rescue URI::InvalidURIError
+                invalid = true
+              end
+              style = ''
+              style = ' style="color: red"' if invalid
+              "<a#{style} href=\"#{converted}\">#{m}</a>"
+            end) }.
+            join("<br>\n")
+          
+
+          input = OpenStruct.new(
+            original_identifier: original_identifier,
+            escaped_output: escaped_output,
+            api_fied_links: api_fied_links,
+            media_types: media_types,
+            css: CommonCSS.css,
+          )
+
+          template = ERB.new <<-TEMPLATE
+            <html lang="en">
+              <head>
+                <title>API Viewer [<%= CGI::escapeHTML(original_identifier) %>]</title>
+                <style>
+                  <%= css.split("\n").join("\n      ") %>
+                </style>
+              </head>
+              <body>
+                <header>
+                  <div id="logo"></div>
+                  <h1>Api Viewer - <%= CGI::escapeHTML(original_identifier) %></h1>
+                </header>
+                <section id="content">
+                  <nav>
+                    <section id="representations">
+                      <h2>Representations:</h2>
+                      <ul>
+                        <% media_types.each do |m| %>
+                        <li>
+                          <a href="<%= m[:href] %>" <%= m[:selected] ? 'class="active" ' : '' %>>
+                            <%= CGI::escapeHTML(m[:identifier]) %>
+                          </a>
+                        </li>
+                        <% end %>
+                      </ul>
+                      <hr>
+                    </section>
+                    <section id="links">
+                      <span class="label">Links:&nbsp</span>
+                      <ul>
+                        <% api_fied_links.each do |l| %>
+                        <li><a <% if l[:invalid] %> style="color: red" <% end %>href="<%= l[:href] %>"><%= CGI::escapeHTML(l[:rel].to_s) %></a></li>
+                        <% end %>
+                      </ul>
+                    </section>
+                  </nav>
+                  <main>
+                    <code id="output">
+                      <%= escaped_output %>
+                    </code>
+                  </main>
+                </section>
+                <!-- API viewer made with ❤ by: https://delftsolutions.com -->
+              </body>
+            </html>
+          TEMPLATE
+          template.result(input.instance_eval { binding })
+        end
+      end
+    end
+  end
+end