shaf 1.5.1 → 2.1.0

data/lib/shaf/profiles/shaf_basic.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+module Shaf
+  module Profiles
+    class ShafBasic < Shaf::Profile
+      name 'shaf-basic'
+
+      rel :delete,
+          http_method: :delete,
+          doc: <<~DOC
+            When a resource contains a link with rel 'delete', this
+            means that the autenticated user (or any user if the
+            current user has not been authenticated), may send a
+            DELETE request to the href of the link.
+            If a DELETE request is sent to this href then the corresponding
+            resource will be deleted.
+          DOC
+    end
+  end
+end

data/lib/shaf/profiles/shaf_error.rb

@@ -0,0 +1,49 @@
+# frozen_string_literal: true
+
+module Shaf
+  module Profiles
+    class ShafError < Shaf::Profile
+      name 'shaf-error'
+      urn 'urn:shaf:error'
+
+      doc  'This profile describes a set of descriptors for generic error messages.'
+      example <<~EXAMPLE
+      {
+        "title": "Invalid entity",
+        "message": "The user could not be saved, due to unfulfilled requirements",
+        "code": "VALIDATION_ERROR",
+        "fields": {
+          "email": ["cannot be empty"]
+        }
+      }
+      EXAMPLE
+
+      example <<~EXAMPLE
+      {
+        "title": "Unpermitted action",
+        "message": "User is not allowed to edit this resource",
+        "code": "FORBIDDEN_ERROR",
+      }
+      EXAMPLE
+
+      attribute :code,
+        type: :string,
+        doc: 'An identifier that describes the type of error.'
+
+      attribute :title,
+        type: :string,
+        doc: 'A short string used for labeling the error.'
+
+      attribute :message,
+        type: :string,
+        doc: 'A description with details about the error.'
+
+      attribute :fields,
+        type: :string,
+        doc: 'An object describing validation errors. ' \
+             'The keys correspond to attributes of a resource. ' \
+             'The values are an array of strings describing validation errors ' \
+             'for the corresponding attribute.'
+    end
+  end
+end

data/lib/shaf/profiles/shaf_form.rb

@@ -0,0 +1,110 @@
+# frozen_string_literal: true
+
+module Shaf
+  module Profiles
+    class ShafForm < Shaf::Profile
+      name 'shaf-form'
+      urn 'urn:shaf:form'
+
+      doc 'This profile describes how a set of descriptors should be interpreted to ' \
+          'turn a generic media type into a form (similar to HTML forms). For ' \
+          'example, the HAL media type (application/hal+json) does not specify any ' \
+          'semantics about forms, however we can add semantics about forms to a HAL ' \
+          'document using this profile.'
+
+      example <<~EXAMPLE
+        Given the following form:
+
+        ```json
+          "create-form": {
+            "method": "POST",
+            "name": "create-post",
+            "title": "Create Post",
+            "href": "/posts",
+            "type": "application/json",
+            "_links": {
+              "self": {
+                "href": "http://localhost:3000/posts/form"
+              }
+            },
+            "fields": [
+              {
+                "name": "title",
+                "type": "string",
+              },
+              {
+                "name": "message",
+                "type": "string",
+              }
+            ]
+          }
+        ```
+
+        A client should then present a user interface with the possiblity to fill in two fields accepting string values (if applicable the interface should be titled "Create Post"). The entered values should be mapped to the keys title resp. message. (The client may of course fill in the details itself whenever possible). When the form is to be submitted, the client constructs a json string with the keys and values and makes a POST request to http://localhost:3000/posts/form with the header Content-Type header set to application/json and the json string as body.
+
+        Using Curl, the form above could be submitted using:
+
+        ```sh
+          curl -H "Content-Type: application/json" \
+               -X POST \
+               -d '{"title": "hello", "message": "world"}' \
+               localhost:3000/posts
+        ```
+      EXAMPLE
+
+      attribute :method,
+        type: :string,
+        doc: 'The HTTP method used for submitting the form'
+
+      attribute :href,
+        type: :string,
+        doc: 'The target uri that the form should be submitted to'
+
+      attribute :name,
+        type: :string,
+        doc: 'A string used to indentify the form.'
+
+      attribute :title,
+        type: :string,
+        doc: 'A string used as title/label when showing the form in a user interface'
+
+      attribute :type,
+        type: :string,
+        doc: 'The media type that must be set in the CONTENT-TYPE header when submiting the form'
+
+      attribute :submit,
+        type: :string,
+        doc: 'A string used as label for the CallToAction (e.g. the submit button text)'
+
+      attribute :fields, doc: 'A list of field descriptors' do
+
+        attribute :name,
+                  type: :string,
+                  doc: 'A string that should be used as key for the field.'
+
+        attribute :type,
+                  type: :string,
+                  doc: 'A string specifying the possible values accepted by the field.'
+
+        attribute :title,
+                  type: :string,
+                  doc: 'A string used to present this field in a UI. If not present name may be used instead.'
+
+        attribute :value,
+                  doc: 'A prefilled value. Should be shown in a user interface (unless hidden) and sent back on submission unless changed.'
+
+        attribute :required,
+                  type: :boolean,
+                  doc: 'A boolean specifying that the field must be given a value before the form is submitted.'
+
+        attribute :hidden,
+                  type: :boolean,
+                  doc: 'A boolean specifying that the field should not be shown in a user interface.'
+
+        attribute :accepted_values,
+                  type: :array,
+                  doc: 'A list of av acceptable values. Submitting a value not present in this list SHOULD result in a client error response.'
+      end
+    end
+  end
+end

data/lib/shaf/responder.rb

@@ -1,7 +1,10 @@
 require 'set'
+require 'shaf/errors'
 
 module Shaf
   module Responder
+    MEDIA_TYPE_SUFFIX_PATTERN = %r{(.*)/([^+]+)\+(.*)}.freeze
+
     class << self
       def register(responder)
         uninitialized << responder
@@ -15,15 +18,23 @@ module Shaf
       end
 
       def for(request, resource)
+        return Responder::ProblemJson if resource.is_a?(Errors::NotAcceptableError)
+
         types = supported_responders_for(resource).map(&:mime_type)
-        mime = request.preferred_type(types)
-        responders[mime]
+        types = move_html_to_last(types)
+
+        mime = preferred_type(request, types)
+        responders[mime] or raise Errors::NotAcceptableError
       end
 
       def default=(responder)
         responders.default = responder
       end
 
+      def default
+        responders.default
+      end
+
       private
 
       def supported_responders_for(resource)
@@ -41,6 +52,23 @@ module Shaf
         @supported_responders ||= Hash.new { |hash, key| hash[key] = Set.new }
       end
 
+      def preferred_type(request, types)
+        mime = request.preferred_type(types)
+        return mime if mime
+
+        request.accept.find do |accept|
+          next if accept.match? MEDIA_TYPE_SUFFIX_PATTERN
+
+          types.find do |type|
+            m = type.match MEDIA_TYPE_SUFFIX_PATTERN
+            next unless m
+
+            format = "#{m[1]}/#{m[3]}"
+            return type if accept.to_str == format
+          end
+        end
+      end
+
       def uninitialized
         @uninitialized ||= []
       end
@@ -57,6 +85,16 @@ module Shaf
           init_responders!
         end
       end
+
+      # We want to always be able to respond with text/html, but only when
+      # asked for (Accept header) to be able to let other more specific mime
+      # types take precedence we need to move text/html to the end of the
+      # array.
+      def move_html_to_last(types)
+        return types unless types.include? Html.mime_type
+
+        (types - [Html.mime_type]) << Html.mime_type
+      end
     end
   end
 end
@@ -65,3 +103,4 @@ require 'shaf/responder/base'
 require 'shaf/responder/hal'
 require 'shaf/responder/html'
 require 'shaf/responder/problem_json'
+require 'shaf/responder/alps_json'

data/lib/shaf/responder/alps_json.rb

@@ -0,0 +1,25 @@
+require 'shaf/alps/json_serializer'
+
+module Shaf
+  module Responder
+    class AlpsJson < Base
+      mime_type :alps_json, 'application/alps+json'
+
+      def self.can_handle?(resource)
+        return false unless resource.is_a? Class
+        resource <= Shaf::Profile
+      end
+
+      def body
+        JSON.generate hash
+      end
+
+      private
+
+      def hash
+        ALPS::JsonSerializer.call(resource)
+      end
+    end
+  end
+end
+

data/lib/shaf/responder/base.rb

@@ -2,12 +2,14 @@ module Shaf
   module Responder
     class Response
       attr_reader :content_type, :body, :serialized_hash, :resource
+      attr_accessor :preload_links
 
       def initialize(content_type:, body:, serialized_hash: {}, resource: nil)
         @content_type = content_type
         @body = body
         @serialized_hash = serialized_hash
         @resource = resource
+        @preload_links = []
       end
 
       def log_entry
@@ -36,11 +38,10 @@ module Shaf
         end
 
         def call(controller, resource, preload: [], **kwargs)
-          responder = new(controller, resource, **kwargs)
+          responder = new(controller, resource, preload_rels: preload, **kwargs)
           response = responder.build_response
           log_response(controller, response)
-          preload_links = preload_links(preload, responder, response, controller)
-          write_response(controller, response, preload_links)
+          write_response(controller, response)
         end
 
         def can_handle?(_obj)
@@ -58,23 +59,14 @@ module Shaf
           controller.log.send(type, msg)
         end
 
-        def preload_links(rels, responder, response, controller = nil)
-          Array(rels).map do |rel|
-            links = responder.lookup_rel(rel, response)
-            links = [links].compact unless links.is_a? Array
-            log(controller, PRELOAD_FAILED_MSG % rel) if links.empty?
-            links
-          end
-        end
-
-        def write_response(controller, response, preload_links)
+        def write_response(controller, response)
           controller.content_type(response.content_type)
-          add_preload_links(controller, response, preload_links)
+          add_preload_links(controller, response)
           controller.body(response.body)
         end
 
-        def add_preload_links(controller, response, preload_links)
-          preload_links.each do |links|
+        def add_preload_links(controller, response)
+          response.preload_links.each do |links|
             links.each do |link|
               next unless link[:href]
               # Nginx http2_push_preload only processes relative URIs with absolute path
@@ -111,9 +103,20 @@ module Shaf
           body: body,
           serialized_hash: serialized_hash,
           resource: resource
-        )
+        ).tap do |response|
+          response.preload_links = preload_links(response)
+        end
       end
 
+        def preload_links(response)
+          Array(options[:preload_rels]).map do |rel|
+            links = lookup_rel(rel, response)
+            links = [links].compact unless links.is_a? Array
+            log(controller, PRELOAD_FAILED_MSG % rel) if links.empty?
+            links
+          end
+        end
+
       def lookup_rel(_rel, _response)
         []
       end

data/lib/shaf/responder/hal.rb

@@ -1,29 +1,84 @@
-require 'shaf/responder/hal_serializable'
-
 module Shaf
   module Responder
     class Hal < Base
-      include HalSerializable
-
       use_as_default!
       mime_type :hal, 'application/hal+json'
 
+      def self.can_handle?(resource)
+        return false if resource.is_a? StandardError
+
+        if resource.is_a? Class
+          return false if resource <= Shaf::Profile
+        end
+
+        true
+      end
+
       def body
-        @body ||= JSON.generate(serialized_hash)
+        @body ||= generate_json
       end
 
+      def lookup_rel(rel, response)
+        hal = response.serialized_hash
+        links = hal&.dig(:_links, rel.to_sym)
+        return [] unless links
+
+        links = [links] unless links.is_a? Array
+        links.map do |link|
+          {
+            href: link[:href],
+            as: 'fetch',
+            crossorigin: 'anonymous'
+          }
+        end
+      end
       private
 
       def mime_type
         type = super
-        type = "#{type};profile=#{profile}" if profile
+        type = "#{type}; profile=\"#{profile}\"" if profile
         type
       end
 
+      def collection?
+        !!options.fetch(:collection, false)
+      end
+
+      def serializer
+        @serializer ||= options[:serializer] || HALPresenter.lookup_presenter(resource)
+      end
+
+      def serialized_hash
+        raise Errors::NotAcceptableError unless serializer
+
+        @serialized_hash ||=
+          if collection?
+            serializer.to_collection(resource, current_user: user, as_hash: true, **options)
+          else
+            serializer.to_hal(resource, current_user: user, as_hash: true, **options)
+          end
+
+        # hal_presenter versions before v1.5.0 does not understand the :as_hash
+        # keyword argument and will always return a String from
+        # to_hal/to_collection, thus we need to parse it if its a String.
+        if @serialized_hash.is_a? String
+          @body = @serialized_hash
+          @serialized_hash = JSON.parse(@serialized_hash, symbolize_names: true)
+        end
+
+        @serialized_hash
+      end
+
       def profile
-        return unless serializer
+        @profile ||= options[:profile]
+        return unless @profile || serializer
+
+        @profile ||= serializer.semantic_profile
+      end
 
-        @profile ||= options[:profile] || serializer.semantic_profile
+      def generate_json
+        # FIXME: change to Oj??
+        JSON.generate(serialized_hash)
       end
     end
   end